From 3bbeb1e7c80cbb0131deccd736e73a5eb3ff848b Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Sat, 17 Oct 2026 15:32:33 +0100 Subject: [PATCH 1/2] docs: refresh README --- README.md | 412 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 277 insertions(+), 135 deletions(-) diff --git a/README.md b/README.md index b0c2daff..c311a76b 100644 --- a/README.md +++ b/README.md @@ -1,55 +1,72 @@ # Appwrite Command Line SDK -![License](https://img.shields.io/github/license/appwrite/sdk-for-cli.svg?style=flat-square) +![License](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg?style=flat-square) ![Version](https://img.shields.io/badge/api%20version-2.5.0-blue.svg?style=flat-square) -[![Build Status](https://img.shields.io/travis/com/appwrite/sdk-generator?style=flat-square)](https://travis-ci.com/appwrite/sdk-generator) -[![Twitter Account](https://img.shields.io/twitter/follow/appwrite?color=00acee&label=twitter&style=flat-square)](https://twitter.com/appwrite) +[![npm](https://img.shields.io/npm/v/appwrite-cli?style=flat-square)](https://www.npmjs.com/package/appwrite-cli) +[![X Account](https://img.shields.io/badge/follow-%40appwrite-000000?logo=x&style=flat-square)](https://x.com/appwrite) [![Discord](https://img.shields.io/discord/564160730845151244?label=discord&style=flat-square)](https://appwrite.io/discord) **This SDK targets Appwrite server version 2.5.x as shipped on Appwrite Cloud.** Self-hosted releases can lag behind Cloud — if you run an older self-hosted build, use a matching older SDK from [previous releases](https://github.com/appwrite/sdk-for-cli/releases) when APIs differ. -Appwrite is an open-source backend as a service server that abstracts and simplifies complex and repetitive development tasks behind a very simple to use REST API. Appwrite aims to help you develop your apps faster and in a more secure way. Use the Command Line SDK to integrate your app with the Appwrite server to easily start interacting with all of Appwrite backend APIs and tools. For full API documentation and tutorials go to [https://appwrite.io/docs](https://appwrite.io/docs) +The Appwrite CLI manages your Appwrite projects from the terminal. Create and link projects, deploy functions and sites, sync tables, buckets, teams and other resources through `appwrite.config.json`, and call any Appwrite API. For full API documentation and tutorials go to [https://appwrite.io/docs](https://appwrite.io/docs) ![Appwrite](https://github.com/appwrite/appwrite/raw/main/public/images/github.png) ## Installation -The Appwrite CLI is a command line tool to help you interact with the Appwrite API. The CLI is distributed both as an [`npm package`](https://www.npmjs.com/package/appwrite-cli) as well as [native binaries](https://github.com/appwrite/sdk-for-cli/releases/latest) for specific operating systems and architectures. +The Appwrite CLI is a command line tool to help you interact with the Appwrite API. You can install it with [Homebrew](https://brew.sh), [`npm`](https://www.npmjs.com/package/appwrite-cli), [Scoop](https://scoop.sh) or our install scripts, or download a [native binary](https://github.com/appwrite/sdk-for-cli/releases/latest) for your operating system and architecture. -### Install using NPM ---- +### macOS and Linux -If you have `npm` installed, it's as easy as running +#### Homebrew -```sh -$ npm install -g appwrite-cli +```bash +brew install appwrite/appwrite/appwrite ``` -Once the installation is complete, you can verify the install using +Homebrew pulls the formula from the [`appwrite/homebrew-appwrite`](https://github.com/appwrite/homebrew-appwrite) tap and downloads the native binary for your platform. -```sh -$ appwrite -v -28.7.0 -``` +#### npm -### Install using prebuilt binaries ---- +```bash +npm install -g appwrite-cli +``` -If you do not have `npm` installed, you can always install the prebuilt binaries for your architecture and OS using our convenient installation scripts. +#### Install script -### Linux / MacOS Terminal ```bash -$ wget -q https://appwrite.io/cli/install.sh -O - | /bin/bash +wget -q https://appwrite.io/cli/install.sh -O - | /bin/bash +``` + +### Windows + +#### PowerShell + +```powershell +iwr -useb https://appwrite.io/cli/install.ps1 | iex ``` -### MacOS / Linux via [Homebrew](https://brew.sh) +#### Scoop + +```powershell +scoop install https://raw.githubusercontent.com/appwrite/sdk-for-cli/master/scoop/appwrite.config.json +``` + +The npm package also works on Windows: + +```powershell +npm install -g appwrite-cli +``` + +### Verify the installation + ```bash -$ brew install appwrite/appwrite/appwrite +appwrite -v ``` -Homebrew pulls the formula from the [`appwrite/homebrew-appwrite`](https://github.com/appwrite/homebrew-appwrite) tap and downloads the native binary for your platform. +This prints the installed version, for example `28.7.0`. -### Shell completion +## Shell completion Install completion for your current shell: @@ -57,178 +74,300 @@ Install completion for your current shell: appwrite completion install ``` -You can also generate or install completion scripts manually: +You can also install completion for a specific shell: ```bash -# zsh appwrite completion install zsh -# bash appwrite completion install bash -# fish appwrite completion install fish ``` For zsh, ensure `~/.zfunc` is in your `fpath` and `compinit` is loaded from your shell config. -### Windows -Via Powershell -```powershell -$ iwr -useb https://appwrite.io/cli/install.ps1 | iex +## Getting started + +Sign in to Appwrite Cloud: + +```sh +appwrite login ``` -Via [Scoop](https://scoop.sh) -```powershell -$ scoop install https://raw.githubusercontent.com/appwrite/sdk-for-cli/master/scoop/appwrite.config.json + +The CLI opens your browser and prints a one-time code to confirm there: + ``` +To sign in, confirm the code below in your browser: + + Code: + URL: -Once the installation completes, you can verify your install using +Signed in as you@example.com on https://cloud.appwrite.io/v1 ``` -$ appwrite -v -28.7.0 + +If the browser does not open, visit the URL yourself. Then create a project, or link the current directory to an existing one: + +```sh +appwrite init project ``` -## Getting Started +This writes `appwrite.config.json`, which records the project and every resource the CLI manages for it. Commit it to version control. To skip the prompts, pass `--organization-id`, `--project-id` and `--project-name`. Use `appwrite list-organizations` and `appwrite list-projects` to look up IDs. -Before you can use the CLI, you need to login to your Appwrite account. +Add resources, then push them: ```sh -$ appwrite login - -? Enter your email test@test.com -? Enter your password ******** -✓ Success +appwrite init function +appwrite push function ``` -This will also prompt you to enter your Appwrite endpoint ( default: http://localhost/v1 ) -* ### Initialising your project -Once logged in, the CLI needs to be initialised before you can use it with your Appwrite project. You can do this with the `appwrite init project` command. +## Self-hosted instances + +Point `login` at your instance's API endpoint. Self-hosted instances sign in with email and password: ```sh -$ appwrite init project +appwrite login --endpoint https://appwrite.example.com/v1 ``` -The following prompt will guide you through the setup process. The `init` command also creates an `appwrite.config.json` file representing your Appwrite project. +The CLI prompts for `Enter your email` and `Enter your password`, or takes them from `--email` and `--password`. If the account has multi-factor authentication, it then asks for a factor and a code. Pass them up front with `--mfa` (`email`, `phone`, `totp` or `recoveryCode`) and `--code`: -The `appwrite.config.json` file does a lot of things. -* Provides context to the CLI -* Keeps track of all your cloud functions -* Keeps track of all your project's tables -* Helps you deploy your Appwrite project to production and more.. +```sh +appwrite login --endpoint https://appwrite.example.com/v1 --email you@example.com --password "$PASSWORD" --mfa totp --code 123456 +``` + +Requests to an instance with a self-signed certificate are rejected by default. If you trust the instance, allow its certificate for the active account: -You can also fetch all the tables in your current project using ```sh -appwrite pull tables +appwrite client --self-signed true ``` -* ### Creating and deploying cloud functions +## Managing accounts -The CLI makes it extremely easy to create and deploy Appwrite's cloud functions. Initialise your new function using +The CLI can keep several signed-in accounts, on Cloud and on self-hosted instances, and uses one at a time. +```sh +# Show the active account +appwrite whoami + +# List every stored session and which one is active +appwrite sessions + +# Sign in to another account without signing out of the current one +appwrite login --new + +# Switch the active account, picking from a list +appwrite login --switch + +# Switch without a prompt +appwrite login --switch --endpoint https://appwrite.example.com/v1 --email you@example.com + +# Sign out of the active account +appwrite logout ``` -$ appwrite init function -? What would you like to name your function? My Awesome Function -? What runtime would you like to use? Node.js (node-15.5) -✓ Success -``` -This will create a new function `My Awesome Function` in your current Appwrite project and also create a template function for you to get started. +`logout` revokes the session on the server before removing it locally. + +## Working with your project + +`init` creates a resource in `appwrite.config.json`, `pull` copies resources from your project into it, and `push` applies it to your project. + +| Resource | `init` | `pull` | `push` | +| --- | --- | --- | --- | +| `function` | ✓ | ✓ | ✓ | +| `site` | ✓ | ✓ | ✓ | +| `table` | ✓ | ✓ | ✓ | +| `bucket` | ✓ | ✓ | ✓ | +| `team` | ✓ | ✓ | ✓ | +| `topic` | ✓ | ✓ | ✓ | +| `webhook` | | ✓ | ✓ | +| `settings` | | ✓ | ✓ | +| `collection` (legacy) | ✓ | ✓ | ✓ | + +Resource names also accept the plural, so `appwrite push functions` and `appwrite push function` are the same command. + +### Functions ```sh -$ tree My\ Awesome\ Function +appwrite init function +``` -My Awesome Function -├── README.md -├── index.js -├── package-lock.json -└── package.json +The CLI asks for a name, ID and runtime, copies the starter code for that runtime from [appwrite/templates](https://github.com/appwrite/templates) into `functions/`, and adds the function to `appwrite.config.json`. Fetching the template needs `git`. Pass `--name`, `--function-id` and `--runtime` to skip the prompts, `--source github` to connect a GitHub repository instead of deploying local code, and `--deploy` to create and deploy the function straight away. -0 directories, 4 files +```sh +appwrite push function ``` -You can now deploy this function using +`push function` asks which functions to deploy, creates or updates them, uploads the code and streams the build logs. Pass `--function-id ` for one function or `--all` for every function, `--with-variables` to replace the function's variables with those in its `.env` file, `--no-logs` to skip the build logs, and `--async` to return without waiting for the deployment. + +### Sites ```sh -$ appwrite push function +appwrite init site +appwrite push site +``` + +`init site` asks for a framework and can download its starter template. `push site` builds and deploys like `push function`; in a terminal it also prints a preview of the deployed page. -? Which functions would you like to deploy? My Awesome Function (61d1a4c81dfcd95bc834) -ℹ Info Deploying function My Awesome Function ( 61d1a4c81dfcd95bc834 ) -✓ Success Deployed My Awesome Function ( 61d1a4c81dfcd95bc834 ) +### Everything at once + +```sh +appwrite pull all +appwrite push all ``` -Your function has now been deployed on your Appwrite server! As soon as the build process is finished, you can start executing the function. +`push all` pushes settings, buckets, teams, webhooks, topics, functions, sites and tables, in that order. It skips legacy collections. -* ### Deploying Tables +## Local development -Similarly, you can deploy all your tables to your Appwrite server using +Run a function locally in the same runtime container Appwrite uses. This needs [Docker](https://docs.docker.com/engine/install/). ```sh -appwrite push tables +appwrite run function ``` -> ### Note -> By default, requests to domains with self signed SSL certificates (or no certificates) are disabled. If you trust the domain, you can bypass the certificate validation using +The function is served at `http://localhost:/` and restarts when you edit its code. Useful flags: + +| Flag | Description | +| --- | --- | +| `--function-id` | Function to run, instead of choosing from a list | +| `--port` | Local port | +| `--user-id` | ID of a user to impersonate | +| `--with-variables` | Load the function's variables from your project | +| `--no-reload` | Don't restart when files change | + +## Generating code + +Generate a type-safe TypeScript SDK for the databases and tables in `appwrite.config.json`: + ```sh -$ appwrite client --self-signed true +appwrite generate ``` -## Usage +Files are written to `generated/` by default. Change it with `--output`. + +Generate model types for your tables and collections: -The Appwrite CLI follows the following general syntax. ```sh -$ appwrite [COMMAND] --[OPTIONS] +appwrite types ./types ``` -A few sample commands to get you started +The language is detected from your project. Set it with `--language`: `ts`, `js`, `php`, `kotlin`, `swift`, `java`, `dart` or `cs`. Pass `--strict` to convert field names to the language's naming conventions. + +## AI agent skills + +Install Appwrite [skills](https://github.com/appwrite/skills) for AI coding agents into `.agents` or `.claude`: ```sh -$ appwrite users create --user-id "unique()" --email hello@appwrite.io --password very_strong_password -$ appwrite users list +appwrite init skill ``` -To create a row you can use the following command +Without a terminal, pass the selection as flags: + ```sh -$ appwrite tablesdb create-row --database-id --table-id --row-id "unique()" --data '{"name": "Walter O Brein"}' --permissions 'read("any")' --permissions 'read("team:abc")' +appwrite init skill --all --agent .claude --method copy ``` -### Some Gotchas -- `data` must be a valid JSON string where each key and value are enclosed in double quotes `"` like the example above. -- Some arguments like the `read` and `write` permissions are expected to be arrays. In the Appwrite CLI, array values are passed by repeating the flag once per value, like `--permissions` in the example above. +`--skill` installs a single skill and can be repeated. `init project` also installs skills that match your project. + +## Calling the API +Every Appwrite API is available as `appwrite [flags]`: -To get information about the different services available, you can use ```sh -$ appwrite -h +appwrite users list +appwrite users create --user-id "unique()" --email hello@appwrite.io --password very_strong_password +appwrite functions create-execution --function-id --body '{"hello":"world"}' ``` -To get information about a particular service and the commands available in a service you can use +Pass JSON arguments as a single-quoted string with double-quoted keys and values. Repeat a flag to pass an array: + ```sh -$ appwrite users // or -$ appwrite users --help // or -$ appwrite account +appwrite tablesdb create-row \ + --database-id \ + --table-id \ + --row-id "unique()" \ + --data '{"name": "Walter White"}' \ + --permissions 'read("any")' \ + --permissions 'read("team:abc")' ``` -To get information about a particular command and the parameters it accepts, you can use +List commands accept `--filter` (for example `--filter 'email=hello@appwrite.io'`), `--sort-asc`, `--sort-desc`, `--limit` and `--offset`. + +Results are printed as a table. Use `--json` for filtered JSON or `--raw` for the full response. Secrets in the output are redacted unless you pass `--show-secrets`. ```sh -$ appwrite users list --help -$ appwrite account get --help +appwrite users list --json ``` -At any point, you can view or reset the CLI configuration using the `client` service. +To discover services, commands and their flags: +```sh +appwrite --help +appwrite users --help +appwrite users list --help ``` -$ appwrite client --debug -// This will display your endpoint, projectID, API key and so on. -$ appwrite client --reset + +To inspect or reset the CLI's configuration: + +```sh +# Show the endpoint, project and masked credentials in use +appwrite client --debug + +# Sign out of every session and clear the configuration +appwrite client --reset ``` -## CI mode +## CI/CD -The Appwrite CLI can also work in a CI environment. The initialisation of the CLI works a bit differently in CI. In CI, you set your `endpoint`, `projectId` and `API Key` using +In CI, authenticate with an [API key](https://appwrite.io/docs/advanced/security/api-keys) instead of signing in. Give the key the scopes for the resources you push. + +```yaml +name: Deploy + +on: + push: + branches: [main] + +jobs: + deploy: + runs-on: ubuntu-latest + env: + APPWRITE_NO_UPDATE_CHECK: 1 + steps: + - uses: actions/checkout@v4 + + - name: Install the Appwrite CLI + run: npm install -g appwrite-cli + + - name: Configure the Appwrite CLI + run: appwrite client --endpoint https://cloud.appwrite.io/v1 --key ${{ secrets.APPWRITE_API_KEY }} + + - name: Deploy + run: | + appwrite push tables --all --force + appwrite push functions --all --force + appwrite push sites --all --force +``` + +Without an interactive terminal, the CLI never waits for input: a prompt fails with the flag that answers it. `--all` selects every resource of that type and `--force` accepts confirmations, including activating new deployments. + +An API key works for project resources, not for console-only commands. `push all` and `push settings` need a signed-in account, so push resources one type at a time. + +These environment variables override `appwrite.config.json`, so one job can deploy to several projects: + +| Variable | Overrides | +| --- | --- | +| `APPWRITE_ENDPOINT` | Project endpoint. Must match the endpoint configured with `appwrite client` | +| `APPWRITE_PROJECT_ID` | Project ID | +| `APPWRITE_ORGANIZATION_ID` | Organization ID | +| `APPWRITE_CONFIG_FILE` | Config file, like `--config-file` | +| `APPWRITE_NO_UPDATE_CHECK` | Set to any value to skip the daily update check | + +## Updating ```sh -appwrite client --endpoint http://localhost/v1 --project-id --key +appwrite update ``` +The CLI updates itself the way it was installed: through npm, Homebrew or by replacing the standalone binary. `appwrite update --manual` prints the commands instead of running them. + ## Project configuration @@ -283,35 +422,38 @@ Includes and resource paths are resolved relative to the chosen file. ## Contribution -This library is auto-generated by Appwrite custom [SDK Generator](https://github.com/appwrite/sdk-generator). To learn more about how you can help us improve this SDK, please check the [contribution guide](https://github.com/appwrite/sdk-generator/blob/master/CONTRIBUTING.md) before sending a pull-request. +This library is auto-generated by Appwrite custom [SDK Generator](https://github.com/appwrite/sdk-generator). To learn more about how you can help us improve this SDK, please check the [contribution guide](https://github.com/appwrite/sdk-generator/blob/main/CONTRIBUTING.md) before sending a pull request. -To build and test the CLI for development, follow these steps +To build and test the CLI for development: -1. Clone the SDK Generator repository and cd into the directory -```sh -$ git clone https://github.com/appwrite/sdk-generator -$ cd sdk-generator -``` +1. Clone the SDK Generator repository and change into it. -2. Ensure Docker is running locally and then install the composer dependencies using -```sh -$ docker run --rm --interactive --tty --volume "$(pwd)":/app composer install --ignore-platform-reqs --optimize-autoloader --no-plugins --no-scripts --prefer-dist + ```sh + git clone https://github.com/appwrite/sdk-generator + cd sdk-generator + ``` -# Generate the CLI -$ docker run --rm -v $(pwd):/app -w /app php:8.5-cli php example.php cli -``` +2. Make sure Docker is running, then install the Composer dependencies and generate the CLI. -3. Head over to the generated SDK and build it. -```sh -$ cd examples/cli -$ go mod tidy -$ go build -ldflags="-s -w" -o appwrite . -``` + ```sh + docker run --rm --interactive --tty --volume "$(pwd)":/app composer install --ignore-platform-reqs --optimize-autoloader --no-plugins --no-scripts --prefer-dist + docker run --rm --volume "$(pwd)":/app --workdir /app php:8.5-cli php example.php cli + ``` + +3. Build the generated CLI. + + ```sh + cd examples/cli + go mod tidy + go build -ldflags="-s -w" -o appwrite . + ``` + +4. Run the CLI. + + ```sh + ./appwrite -v + ``` -4. You can now use the CLI -```sh -$ ./appwrite -v -``` ## License -Please see the [BSD-3-Clause license](https://raw.githubusercontent.com/appwrite/appwrite/master/LICENSE) file for more information. +Please see the [BSD-3-Clause license](LICENSE.md) file for more information. From 2c919bf8cb29b49d541d95c7effe870e15fc80f7 Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Sat, 17 Oct 2026 17:47:03 +0100 Subject: [PATCH 2/2] docs: list analytics in push all and python in types languages --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c311a76b..5d602fff 100644 --- a/README.md +++ b/README.md @@ -212,7 +212,7 @@ appwrite pull all appwrite push all ``` -`push all` pushes settings, buckets, teams, webhooks, topics, functions, sites and tables, in that order. It skips legacy collections. +`push all` pushes settings, buckets, teams, webhooks, topics, analytics, functions, sites and tables, in that order. It skips legacy collections. ## Local development @@ -248,7 +248,7 @@ Generate model types for your tables and collections: appwrite types ./types ``` -The language is detected from your project. Set it with `--language`: `ts`, `js`, `php`, `kotlin`, `swift`, `java`, `dart` or `cs`. Pass `--strict` to convert field names to the language's naming conventions. +The language is detected from your project. Set it with `--language`: `ts`, `js`, `php`, `kotlin`, `swift`, `java`, `dart`, `cs` or `python`. Pass `--strict` to convert field names to the language's naming conventions. ## AI agent skills