Skip to content
Install

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.

To install with Homebrew, run the following command:

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:

curl -fsSL https://raw.githubusercontent.com/LeafdTK/orchard-releases/main/install.sh | sh

To confirm the installation, run the following command:

orchard version

To sign in to an instance, run the following command:

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.

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 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 <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.com
export ORCHARD_API_TOKEN=<API_TOKEN>

To create a token, refer to Manage API tokens.

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:

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.

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

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 15m

To list every command and flag as JSON, run the following command:

orchard commands -o json
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