# Use the CLI > Install the Orchard CLI, sign in to an instance, set a default project, and script commands with JSON output. Source: https://docs.orchard.hackclub.com/cli/ The `orchard` command-line interface (CLI) calls the same API as the dashboard. Use it to deploy apps, read logs, and manage databases from a terminal, a script, or a CI job. Output is a table in a terminal and JSON when piped, and exit codes are stable, so scripts can rely on both. This page covers installing the CLI, signing in, and choosing what a command acts on. For every command and flag, refer to the [CLI reference](/reference/cli/). To run commands on the machine that hosts Orchard, use [host commands](/operate/host-commands/) instead. ## Install the CLI To install with Homebrew, run the following command: ```bash brew install --cask leafdtk/tap/orchard-cli ``` The cask is named `orchard-cli`. The installed command is `orchard`. To install without Homebrew, run the following install script: ```bash curl -fsSL https://raw.githubusercontent.com/LeafdTK/orchard-releases/main/install.sh | sh ``` To confirm the installation, run the following command: ```bash orchard version ``` ## Sign in To sign in to an instance, run the following command: ```bash orchard auth login --api-url https://orchard.example.com ``` The command opens a browser. After you approve the request, the CLI stores a token in `~/.orchard/config.json`. The CLI has no default instance. If no instance is set up and you run `orchard auth login` without `--api-url`, the CLI asks for the URL of your instance. The CLI checks that the URL is an Orchard instance, adds a context for it, and continues to sign-in. The first command that needs an instance does the same. After the first sign-in, `orchard auth login` signs in to the current context. To add another instance, pass `--api-url`. Without a terminal or in CI, the CLI never asks. If no instance is set up, the command stops with an error. Pass `--api-url` to `orchard auth login` or set `ORCHARD_API_URL`. ## Work with several instances Each instance you sign in to becomes a context: its URL, your token for it, and the default organization, project and environment you set with `orchard use`. Signing in to another instance adds a context and switches to it. ```bash orchard auth login --api-url https://staging.example.com --name staging orchard context list orchard context use # pick from a list orchard context use staging ``` To run a single command against another instance, pass `--context ` or set `ORCHARD_CONTEXT`. To rename a context, run `orchard context rename`. To forget a context and its token, run `orchard context remove`. To sign in on a machine with no browser, add `--no-browser`. The CLI prints a URL and the local port that it listens on. Forward that port to your own machine with `ssh -L` before you open the URL. Without a terminal, the CLI cannot ask which instance to use, so also pass `--api-url` or set `ORCHARD_API_URL`. To authenticate a script, set the instance URL and a token in the environment. A token in the environment overrides a stored token. ```bash export ORCHARD_API_URL=https://orchard.example.com export ORCHARD_API_TOKEN= ``` To create a token, refer to [Manage API tokens](/account/tokens/). ## Choose an organization and project Most commands act on an organization, a project, or an environment. Orchard uses the first value it finds, in the following order: 1. The `--org`, `--project`, and `--env` flags. 2. The `ORCHARD_ORG`, `ORCHARD_PROJECT`, and `ORCHARD_ENV` environment variables. 3. The saved context from `orchard use`. To save a context, run the following commands: ```bash orchard use org my-org orchard use project my-app orchard context show ``` To link a directory to a project, run `orchard link --project my-app` in that directory. The command writes `.orchard/project.json`. Commands that you run from that directory then use the project. ## Common commands | Task | Command | | -------------------------------------------------------------------------------------- | ------------------------------------ | | List apps | `orchard deploy list` | | [Scale an app](/deploy/scaling/#change-replicas) | `orchard deploy scale 3` | | [Read or follow logs](/run/logs/) | `orchard logs -f` | | [Build and deploy the current directory](/deploy/deploy-from-terminal/) | `orchard up` | | [Write variables to `.env.orchard`](/run/environments/#pull-variables-to-a-local-file) | `orchard env pull` | | List databases | `orchard db list` | | [Run a job](/run/jobs/) | `orchard job run ` | | [Roll back an app](/deploy/rollbacks/) | `orchard deploy rollback --yes` | ## Use the CLI in scripts The CLI writes JSON to stdout when stdout is not a terminal. To request JSON in a terminal, add `-o json`. Status and warnings go to stderr. ```bash orchard deploy list -o json | jq -r '.[].name' ``` Destructive commands ask for confirmation in a terminal. Without a terminal, they fail with exit code `2` unless you pass `--yes`. To block until a deploy finishes, add `--wait`: ```bash orchard deploy rebuild --wait --timeout 15m ``` To list every command and flag as JSON, run the following command: ```bash orchard commands -o json ``` ### Exit codes | Code | Meaning | | ----- | ---------------------------------------------------------------------------------------------------- | | `0` | Success | | `1` | General or network error, or no token configured | | `2` | Usage error, or a refused confirmation | | `3` | Authentication rejected (HTTP 401) | | `4` | Not found (HTTP 404) | | `5` | Request rejected (other HTTP 4xx, including a missing scope) | | `6` | Rate limited (HTTP 429) | | `7` | Server error (HTTP 5xx) | | `8` | The request deadline passed, or `--wait` reached `--timeout` | | `9` | The build failed during a wait | | `10` | Pods are crash-looping or the rollout is unhealthy, or `orchard db diagnose` found the database down | | `11` | `orchard doctor` found at least one failing check | | `130` | Interrupted | ## Related resources - [Code mode for agents](/agents-code-mode/) - Let a coding agent drive Orchard through the CLI instead of MCP. - [Use the terminal dashboard](/run/terminal-dashboard/) - Read logs, deploy, scale, and manage databases from an interactive dashboard in your terminal. - [`orchard auth` reference](/reference/cli/#auth) - Every sign-in, session, and token command.