Use the 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. To run commands on the machine that hosts Orchard, use host commands instead.
Install the CLI
Section titled “Install the CLI”To install with Homebrew, run the following command:
brew install --cask leafdtk/tap/orchard-cliThe cask is named orchard-cli. The installed command is orchard.
To install without Homebrew, run the following install script:
curl -fsSL https://raw.githubusercontent.com/LeafdTK/orchard-releases/main/install.sh | shTo confirm the installation, run the following command:
orchard versionSign in
Section titled “Sign in”To sign in to an instance, run the following command:
orchard auth login --api-url https://orchard.example.comThe 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
Section titled “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.
orchard auth login --api-url https://staging.example.com --name stagingorchard context listorchard context use # pick from a listorchard context use stagingTo run a single command against another instance, pass --context <name> 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.
export ORCHARD_API_URL=https://orchard.example.comexport ORCHARD_API_TOKEN=<API_TOKEN>To create a token, refer to Manage API tokens.
Choose an organization and project
Section titled “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:
- The
--org,--project, and--envflags. - The
ORCHARD_ORG,ORCHARD_PROJECT, andORCHARD_ENVenvironment variables. - The saved context from
orchard use.
To save a context, run the following commands:
orchard use org my-orgorchard use project my-apporchard context showTo 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
Section titled “Common commands”| Task | Command |
|---|---|
| List apps | orchard deploy list |
| Scale an app | orchard deploy scale <ID> 3 |
| Read or follow logs | orchard logs <ID> -f |
| Build and deploy the current directory | orchard up |
Write variables to .env.orchard |
orchard env pull |
| List databases | orchard db list |
| Run a job | orchard job run <ID> |
| Roll back an app | orchard deploy rollback <ID> --yes |
Use the CLI in scripts
Section titled “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.
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:
orchard deploy rebuild <ID> --wait --timeout 15mTo list every command and flag as JSON, run the following command:
orchard commands -o jsonExit codes
Section titled “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
Section titled “Related resources”- Code mode for agents - Let a coding agent drive Orchard through the CLI instead of MCP.
- Use the terminal dashboard - Read logs, deploy, scale, and manage databases from an interactive dashboard in your terminal.
orchard authreference - Every sign-in, session, and token command.