diff --git a/src/routes/changelog/(entries)/2026-08-03.markdoc b/src/routes/changelog/(entries)/2026-08-03.markdoc new file mode 100644 index 0000000000..037f6e221c --- /dev/null +++ b/src/routes/changelog/(entries)/2026-08-03.markdoc @@ -0,0 +1,17 @@ +--- +layout: changelog +title: Easier project discovery and targeting in the Appwrite CLI +date: 2026-08-03 +--- + +The latest Appwrite CLI makes it easier to find and manage projects from any directory. Use `appwrite list-projects` and `appwrite list-organizations` to see what your current session can access, then pass `--project-id` or `--organization-id` to project and organization commands without first linking a local directory. The same IDs can be supplied with `APPWRITE_PROJECT_ID` and `APPWRITE_ORGANIZATION_ID` in scripts. + +Cloud regional endpoints now route Console-level commands correctly, and project discovery and organization lookup also work with supported self-hosted installations. Custom endpoints are validated before login and produce concise, actionable errors when the URL or `/v1` path is incorrect. + +The CLI now groups root help by task, formats responses for easier reading, and offers safer account recovery and reset flows. Use `appwrite login --switch` to return to a saved account after changing endpoints. `appwrite client --reset` now asks before signing out saved accounts, while `--force` provides explicit confirmation for scripts. + +Update to the latest CLI version to use these improvements. + +{% arrow_link href="/docs/tooling/command-line/installation#update-your-cli" %} +Update the Appwrite CLI +{% /arrow_link %} diff --git a/src/routes/docs/tooling/command-line/commands/+page.markdoc b/src/routes/docs/tooling/command-line/commands/+page.markdoc index cb3ca88b46..0c52d28e15 100644 --- a/src/routes/docs/tooling/command-line/commands/+page.markdoc +++ b/src/routes/docs/tooling/command-line/commands/+page.markdoc @@ -21,6 +21,8 @@ appwrite [COMMAND] [OPTIONS] Below is a list of the available commands in the Appwrite CLI. You can get more information on each command by running `appwrite [COMMAND] --help`. +Run `appwrite --help` to browse commands grouped by what you want to do, including getting started, managing project settings and resources, and using CLI utilities. The root help uses short descriptions so commonly used commands are easier to find. + ## General commands {% #general-commands %} {% table %} @@ -30,6 +32,12 @@ Below is a list of the available commands in the Appwrite CLI. You can get more * `client [options]` * The client command allows you to configure your CLI. --- +* `list-organizations [options]` +* List the organizations available to your current session. +--- +* `list-projects [options]` +* List the projects available to your current session, including each project's region and endpoint. +--- * `locale` * The locale command allows you to customize your app based on your users' location. --- @@ -60,7 +68,7 @@ Below is a list of the available commands in the Appwrite CLI. You can get more * Prints link to register an Appwrite account. --- * `whoami` -* The whomai command gives information about the currently logged-in user. +* The whoami command gives information about the currently logged-in user and shows how to recover another saved account when one is available. --- {% /table %} @@ -93,6 +101,12 @@ The `init`, `pull`, `push`, and `run` commands support [multi-file project confi * Command * Description --- +* `project` +* Manage project settings, usage, variables, API keys, platforms, and other project-level resources. Pass `--project-id` to target a project without linking the current directory. +--- +* `organization` +* Manage an organization and its projects. Pass `--organization-id` to target an organization explicitly. +--- * `account` * The account command allows you to authenticate and manage a user account. --- @@ -119,6 +133,25 @@ The `init`, `pull`, `push`, and `run` commands support [multi-file project confi --- {% /table %} +## Target projects and organizations {% #target-projects-and-organizations %} + +Project and organization commands can be run from any directory. Pass the target explicitly when you do not want to use the IDs in `appwrite.config.json`: + +```sh +appwrite project get --project-id "" +appwrite project list-keys --project-id "" +appwrite organization list-projects --organization-id "" +``` + +The CLI resolves these IDs in the following order: the command option, the `APPWRITE_PROJECT_ID` or `APPWRITE_ORGANIZATION_ID` environment variable, then `appwrite.config.json`. This makes the same commands usable in scripts without creating a project configuration file. + +```sh +APPWRITE_PROJECT_ID="" appwrite project get +APPWRITE_ORGANIZATION_ID="" appwrite organization list-projects +``` + +When only a project ID is available, the CLI can discover its organization. Project API requests continue to use the project's regional endpoint, while account, organization, and other Console-level requests are sent to the appropriate Console endpoint. + ## Command options {% #command-options %} {% table %} @@ -135,8 +168,8 @@ The `init`, `pull`, `push`, and `run` commands support [multi-file project confi * `-j, --json` * Output in JSON format --- -* `-f,--force` -* Flag to confirm all warnings +* `-f, --force` +* Skip confirmation prompts --- * `-a,--all` * Flag to push all resources @@ -167,12 +200,17 @@ appwrite users list --json ``` # Force {% #force %} -By default, when pushing or pulling resources, the Appwrite CLI will ask you to confirm destructive operations. Use the `--force` flag to verify all questions. +By default, the Appwrite CLI asks you to confirm destructive operations such as resetting the client or overwriting resources. Use the `--force` flag to skip confirmation prompts, including in non-interactive scripts. ```sh appwrite push tables --force +appwrite client --reset --force ``` +# Human-readable and JSON output {% #command-output %} + +By default, the CLI formats responses for quick reading. It summarizes long lists of enabled settings, adds readable hints to timestamps, durations, and byte sizes, and hides secret values. Use `--json` for filtered JSON or `--raw` for the complete API response when you need machine-readable output. Add `--show-secrets` only when you intentionally need secret values in the output. + # All {% #all %} By default, when pushing or pulling resources, Appwrite CLI would ask you to select specific resources. Use the `--all` flag to select all available options. diff --git a/src/routes/docs/tooling/command-line/installation/+page.markdoc b/src/routes/docs/tooling/command-line/installation/+page.markdoc index beea12f679..c7658e4ff9 100644 --- a/src/routes/docs/tooling/command-line/installation/+page.markdoc +++ b/src/routes/docs/tooling/command-line/installation/+page.markdoc @@ -126,9 +126,11 @@ appwrite login Add the `--endpoint` flag if you're using a self-hosted instance of Appwrite. This flag requires you to add the URL string you're using for your self-hosted instance after the `--endpoint` flag. Self-hosted instances do not currently support OAuth-based CLI authentication, so the CLI will prompt for your email and password instead. ```sh -appwrite login --endpoint "" +appwrite login --endpoint "https://appwrite.example.com/v1" ``` +Include the `/v1` API path. The CLI validates and normalizes custom endpoints before prompting for credentials, and suggests the correct URL when the API path is missing. A trailing slash is optional. + The CLI signs you in through your browser using device authorization. It displays a code and a URL, then waits for approval. ![Appwrite CLI login in the terminal](/images/docs/command-line/cli-login-terminal.avif) @@ -162,6 +164,14 @@ Once authorized, the browser confirms that your device is connected. Return to y You can log in to multiple accounts or change the **current** account by re-running the command. You can revoke the CLI's access anytime in your account settings. +If changing the client endpoint leaves a previously signed-in account inactive, switch back to any saved account without signing in again: + +```sh +appwrite login --switch +``` + +The CLI lists the available accounts and endpoints for you to choose from. You can also run `appwrite whoami` to see the active account or get recovery instructions when another saved account is available. + {% info title="Seeing an email and password prompt instead?" %} Older CLI versions, and CLI sessions pointed at a self-hosted Appwrite instance, do not support the OAuth device authorization flow and fall back to asking for your email and password. Run `appwrite update` to get the latest version, or pass the Appwrite Cloud endpoint explicitly: @@ -288,14 +298,19 @@ appwrite help # Configuration {% #configuration %} -At any point, if you would like to change your server's endpoint, project ID, or self-signed certificate acceptance, use the `client` command. +At any point, if you would like to change your server's endpoint, API key, or self-signed certificate acceptance, use the `client` command. When the endpoint matches a saved signed-in account, the CLI switches to that account. For a new endpoint, the current account remains saved and can be restored with `appwrite login --switch`. ```sh appwrite client --endpoint https://.cloud.appwrite.io/v1 appwrite client --key 23f24gwrhSDgefaY appwrite client --self-signed true -appwrite client --reset // Resets your CLI configuration -appwrite client --debug // Prints your current configuration +appwrite client --debug +``` + +Use `appwrite client --reset` to clear the CLI configuration. If the reset would sign out saved accounts, the CLI asks for confirmation. For scripts and other non-interactive environments, explicitly confirm the reset with: + +```sh +appwrite client --reset --force ``` # Uninstall {% #uninstall %}