CLI reference
Everything in orch runs through one executable, orch. The same binary sets
up controllers and workers, deploys applications, and opens the TUI and the web
dashboard. This page lists every command the CLI accepts, grouped by task, with
its flags and their defaults.
Run any command with --help to print its flags, for example
orch deploy --help. orch help prints the full usage summary.
Conventions
Selecting a cluster
Commands that talk to a controller (remote commands) need to know which cluster to use. orch picks one in this order:
--target NAMEon the command line (also written--target=NAME).- The
ORCH_TARGETenvironment variable. - The
ORCH_TOKENenvironment variable, an access token fromorch token create. - The selected target, set with
orch target useororch target add. - On the controller host, when no target is selected, the local administrator
socket at
/var/lib/orch-controller/admin.sock. Only root can open it.
If none of these apply, the command stops with:
$ orch nodes
no target is selected; run 'orch target add NAME ssh://root@CONTROLLER' or 'orch target use NAME'--target may appear anywhere before a -- separator and only once. Pass it
explicitly in scripts and CI so a command never runs against the wrong cluster:
orch deploy --wait --target production--context FILE names an administrator context file directly. It remains for
compatibility and cannot be combined with --target. See
targets and interfaces for how targets are stored and reached.
These are the remote commands: join-token, status, events, deploy,
rollback, nodes, logs, exec, remove, job, secret, registry, notify,
tui, web, app list|status|history|diff|watch, cron runs|logs,
network configure, and every node subcommand except node install and
node doctor. All other commands run locally.
Flags and output
- Flags use Go flag syntax:
--flag value,--flag=value, and the single-dash forms-flagare all accepted. - Most commands that take positional arguments also accept flags after them,
for example
orch logs hello web --tail 50. Commands that print "accepts flags only" take no positional arguments. --jsonprints machine-readable JSON on stdout. With--json, errors are also written as JSON ({"error": "...", "problems": [...]}) on stderr.- Streams such as logs and job output write the workload's stdout to stdout and its stderr to stderr.
Idempotency keys
Commands that change cluster state send an idempotency key so a retry after a
lost reply does not apply the change twice. orch generates a key when you omit
--idempotency-key. deploy, remove, rollback, network configure, and
job run|retry print the key they used, and the node update commands include
it in their error message, so you can retry with the same value:
orch deploy --idempotency-key idem_4f2a9c0d7e1b3a5c6d8e0f1a2b3c4d5e --target productionKeys for deploy, remove, network configure, node, and rollback must
be 16 to 128 characters: letters, digits, ., _, :, and -, starting with
a letter or digit.
Exit codes
| Code | Meaning |
|---|---|
0 |
The command succeeded |
1 |
Operational failure, such as an unreachable controller or a failed rollout |
2 |
Usage error or manifest validation failure |
Cluster setup
orch init
orch init [--name NAME] [--advertise-address IP] [--port 9443] [--recovery-dir DIR] [--wait-timeout 2m] [--json]Installs a controller on this host as a systemd service and waits until it answers. Run it as root on the controller host.
| Flag | Default | Purpose |
|---|---|---|
--name |
orch |
Cluster name |
--advertise-address |
detected | Address workers and clients use to reach this host |
--port |
9443 |
Controller port, 1024 to 65535 |
--recovery-dir |
none | Also write a day-zero recovery set to this new directory |
--wait-timeout |
2m |
Maximum wait for controller readiness |
--json |
false |
Emit machine-readable JSON |
The controller listens on 0.0.0.0:PORT and advertises
https://ADDRESS:PORT. A break-glass administrator context is written to
/etc/orch/admin. See installation.
orch join-token
orch join-token NODE [--ttl 1h] [--target NAME] [--json]Creates a single-use join token for a worker called NODE and prints the
orch join command to run on it.
| Flag | Default | Purpose |
|---|---|---|
--ttl |
1h |
Token lifetime, from 1m through 24h |
--json |
false |
Print the token id, node name, expiry, token, and command as JSON |
orch join
orch join TOKEN|- [--advertise-address IP] [--wait-timeout 5m] [--json]Installs a worker on this host with a token from orch join-token. Run it as
root on the worker. Pass - instead of the token to read it from stdin, which
keeps it out of the process list.
| Flag | Default | Purpose |
|---|---|---|
--advertise-address |
detected | IPv4 address other nodes use to reach this host |
--wait-timeout |
5m |
Maximum wait for agent readiness |
--json |
false |
Emit machine-readable JSON |
sudo orch join - < worker-1.tokenorch cluster doctor
orch cluster doctor --server HTTPS_URL --listen ADDRESS [--json]Checks whether this host can run a controller and prints each check with its
fix. It exits with 1 when the host is not ready.
| Flag | Default | Purpose |
|---|---|---|
--server |
required | Canonical controller HTTPS URL |
--listen |
required | Controller IP listen address |
--json |
false |
Emit machine-readable JSON |
orch cluster install
orch cluster install --name NAME --server HTTPS_URL --listen ADDRESS --admin-dir DIR [--recovery-dir DIR] [--dry-run] [--wait-timeout 2m] [--json]Installs a controller like orch init, but lets you choose the URL, listen
address, and where the administrator directory is written.
| Flag | Default | Purpose |
|---|---|---|
--name |
required | Cluster name |
--server |
required | Canonical controller HTTPS URL |
--listen |
required | Controller IP listen address |
--admin-dir |
required | New portable administrator directory |
--recovery-dir |
none | Optional new day-zero recovery directory |
--dry-run |
false |
Inspect and show planned actions without modifying the host |
--wait-timeout |
2m |
Maximum wait for authenticated controller readiness |
--json |
false |
Emit machine-readable JSON |
Import the resulting context.json with orch target import.
orch cluster init
orch cluster init --name NAME --server HTTPS_URL --data-dir DIR [--context FILE] [--json]Creates controller state in a directory without installing services. Use it
when you run orch controller serve yourself.
| Flag | Default | Purpose |
|---|---|---|
--name |
required | Cluster name |
--server |
required | Controller HTTPS URL |
--data-dir |
required | Controller state directory |
--context |
none | Write the administrator context to this path |
--json |
false |
Emit machine-readable JSON |
Without --context, orch stores the administrator credentials as a local
target named after the cluster and selects it.
orch node doctor
orch node doctor --advertise-address IPV4 [--json]Checks whether this host can run a worker, without changing it. It exits with
1 when the host is not ready. It always runs locally.
| Flag | Default | Purpose |
|---|---|---|
--advertise-address |
required | Private or public IPv4 address of this host that other nodes can reach |
--json |
false |
Emit machine-readable results |
orch node install
orch node install --advertise-address IPV4 [--join-file FILE|-] [--dry-run] [--wait-timeout 5m] [--json]Installs a worker from a join file created by orch node join create. It
always runs locally.
| Flag | Default | Purpose |
|---|---|---|
--advertise-address |
required | Private or public IPv4 address of this host that other nodes can reach |
--join-file |
none | Private join file path, or - for stdin |
--dry-run |
false |
Show planned actions without modifying the host or reading join credentials |
--wait-timeout |
5m |
Maximum wait for authenticated agent readiness |
--json |
false |
Emit machine-readable results |
orch node join
orch node join create NODE --output FILE [--ttl 15m] [--idempotency-key KEY] [--target NAME] [--json]
orch node join list [--target NAME] [--json]
orch node join revoke JOIN_ID [--idempotency-key KEY] [--target NAME] [--json]Manages join credentials. create writes a join file (mode 0600) for
orch node install; list shows join credentials and their state; revoke
invalidates one, including tokens from orch join-token.
| Flag | Default | Purpose |
|---|---|---|
--output |
required for create |
New join file path; must not exist |
--ttl |
15m |
Join lifetime, from 1m through 24h |
--idempotency-key |
generated | Stable key for safe retries |
--json |
false |
Emit machine-readable JSON |
If create is interrupted, a private FILE.pending stage remains. Rerun the
same command with the same output path to finish it.
Targets
See targets and interfaces for a full walkthrough.
orch target add
orch target add NAME ssh://[USER@]HOST[:PORT] [--use] [--json]Remembers a controller reached over SSH. orch connects once to confirm a controller answers and records the cluster's identity. Your SSH login is the credential; no certificate is stored.
| Flag | Default | Purpose |
|---|---|---|
--use |
false |
Select the new target. It is selected automatically when no target is selected yet |
--json |
false |
Emit machine-readable JSON |
The location can also be unix:///PATH for an administrator socket on this
machine, and an SSH location can end in a socket path
(ssh://root@HOST/path/to/admin.sock). Without a path, the target uses
/var/lib/orch-controller/admin.sock.
orch target import
orch target import NAME CONTEXT [--use] [--replace] [--json]Copies an mTLS administrator context, such as /etc/orch/admin/context.json,
into a private target.
| Flag | Default | Purpose |
|---|---|---|
--use |
false |
Select the imported target |
--replace |
false |
Replace the credentials of an existing target for the same cluster and keep its transport |
--json |
false |
Emit machine-readable JSON |
orch target list
orch target list [--json]Lists remembered targets. The selected one is marked with *.
orch target use
orch target use NAMESelects the target that remote commands use by default.
orch target transport
orch target transport NAME direct
orch target transport NAME wireguard --address HOST:PORT
orch target transport NAME ssh --host SSH_ALIAS [--destination HOST:PORT]Changes how an imported (certificate) target reaches its controller.
| Flag | Default | Purpose |
|---|---|---|
--address |
required for wireguard |
WireGuard-reachable controller host:port |
--host |
required for ssh |
OpenSSH host or alias |
--destination |
controller URL host and port | Controller host:port as seen from the SSH host |
A target added with orch target add cannot switch to a certificate transport,
and an imported target cannot switch to a socket transport. Add a new target
instead.
orch target test
orch target test [NAME] [--json]Connects to the named or selected target within 10 seconds and prints the cluster name.
$ orch target test production
Connected to production through target production (socket)Applications and deployments
These commands read orch.pkl in the current directory unless you pass
-f. See applications for the file format.
orch validate
orch validate [-f orch.pkl] [--root DIR] [--json]Evaluates and validates the application file and prints its name, service and
cron job counts, and digest. Validation problems exit with 2.
| Flag | Default | Purpose |
|---|---|---|
-f, --file |
orch.pkl |
Pkl manifest path |
--root |
manifest directory | Pkl evaluation root |
--json |
false |
Emit machine-readable JSON |
orch render
orch render [-f orch.pkl] [--root DIR]Prints the canonical JSON that orch would submit for the application.
| Flag | Default | Purpose |
|---|---|---|
-f, --file |
orch.pkl |
Pkl manifest path |
--root |
manifest directory | Pkl evaluation root |
orch plan
orch plan [-f orch.pkl] [--root DIR] [--against previous.pkl] [--json]Lists the changes in the application file and summarizes how many items are
added, changed, and removed. It runs locally: without --against it compares
with an empty application.
| Flag | Default | Purpose |
|---|---|---|
-f, --file |
orch.pkl |
Target Pkl manifest path |
--root |
each manifest's directory | Pkl evaluation root |
--against |
none | Existing Pkl manifest to compare against; must have the same application name |
--json |
false |
Emit machine-readable JSON |
To compare against what is deployed, use orch app diff.
orch deploy
orch deploy [-f orch.pkl] [--root DIR] [--image [NAME=]REF]... [--preview N] [--wait] [--timeout 10m] [--idempotency-key KEY] [--target NAME] [--json]Submits the application as desired state. Without --wait it returns as soon
as the controller accepts it; the rollout continues in the background.
| Flag | Default | Purpose |
|---|---|---|
-f, --file |
orch.pkl |
Pkl manifest path |
--root |
manifest directory | Pkl evaluation root |
--image |
none | Deploy this image instead of the manifest's; repeatable |
--preview |
none | Deploy the preview of pull request N as APP-pr-N on pr-N. subdomains; see preview deployments |
--wait |
false |
Wait for this revision to become ready, printing progress |
--timeout |
10m |
Rollout wait deadline |
--idempotency-key |
generated | Stable key for safe retries |
--json |
false |
Emit machine-readable JSON |
Submitting the same configuration again reports that the desired state is
already current. With --wait, the result is READY, FAILED, TIMED_OUT,
or CANCELED. Stopping the watcher does not cancel the deployment; resume
watching with orch app watch.
--image NAME=REF replaces the image of the service or cron job called
NAME for this deployment. A bare --image REF replaces it for every service
and cron job whose image has the same repository, which is what CI usually
wants after building one image. Each override must match something. History
records the deployed image like any other.
Images you built yourself need no registry. When an image is in the local
Docker (or Podman) engine and its registry does not have it, orch deploy
uploads it to the controller and pins it by digest, and nodes pull it from the
controller:
docker build -t myapp .
orch deploy
# Uploading local image myapp (84 MB)An unchanged image is not uploaded again. An image the registry has, such as
redis:7, is pulled from the registry as usual, even if Docker has a copy. If
the image was built for another architecture than your nodes, for example on
an arm64 laptop for amd64 servers, the deploy stops before uploading and tells
you to rebuild with --platform. The controller keeps the uploaded images
of each application's last 10 deployments, so rollbacks to them keep working.
Uploaded images are not part of controller backups; after restoring a
controller, run orch deploy again to upload them.
A service with static needs no image at all: orch deploy packs its folder
into an image and uploads it the same way, so a container engine isn't needed.
See static sites.
Inside GitHub Actions, the deployment also records the repository, commit,
branch, actor and run link, shown by orch app history. See
deploy from GitHub.
orch dev
orch dev [-f orch.pkl] [--root DIR] [--env-file FILE] [--http-port 8080] [--timeout 10m]
orch dev down [--volumes]Runs the application on this machine: starts a one-node cluster in a container
on the local Docker-compatible engine, adds it as target dev, and deploys the
manifest to it with HTTP services at http://SERVICE.APP.localhost:8080. See
local development.
| Flag | Default | Purpose |
|---|---|---|
-f, --file |
orch.pkl |
Pkl manifest path |
--root |
manifest directory | Pkl evaluation root |
--env-file |
orch.dev.env next to the manifest |
Secret values as NAME=VALUE lines |
--http-port |
8080 |
Local port for HTTP services |
--timeout |
10m |
Rollout wait deadline |
--volumes |
false |
With down, also delete the dev node's data |
orch app list
orch app list [--target NAME] [--json]Lists every application on the cluster with its desired generation, revision, and rollout status.
orch app status
orch app status APP [--target NAME] [--json]Shows the desired, observed, and active generation of an application, its status and reason, every replica with its health and node, HTTP and TCP routes, node ports, and cron jobs with their next run.
orch app history
orch app history APP [--limit 20] [--before-generation N] [--target NAME] [--json]Lists deployments, newest first, with revision, outcome, resolved images, and for deployments from GitHub Actions the commit and run that deployed them. The current and active deployments are marked.
| Flag | Default | Purpose |
|---|---|---|
--limit |
20 |
Page size, 1 to 50 |
--before-generation |
none | Show deployments older than this generation |
--json |
false |
Emit machine-readable JSON |
When more history exists, the output ends with the command for the next page.
orch app diff
orch app diff APP REVISION [--against REVISION] [--target NAME] [--json]Compares a stored revision with the current desired state, or with another revision. Output is limited to 500 changes.
| Flag | Default | Purpose |
|---|---|---|
--against |
current desired state | Revision to compare to |
--json |
false |
Emit machine-readable JSON |
orch app watch
orch app watch APP [--revision REVISION] [--timeout 10m] [--target NAME] [--json]Follows a rollout until it is ready, fails, or the deadline passes.
| Flag | Default | Purpose |
|---|---|---|
--revision |
current desired state | Revision to watch |
--timeout |
10m |
Rollout wait deadline |
--json |
false |
Emit machine-readable JSON |
orch rollback
orch rollback APP REVISION [--expected-generation N] [--wait] [--timeout 10m] [--idempotency-key KEY] [--target NAME] [--json]Creates a new deployment from a stored revision, reusing its resolved image digests. Before sending the request, orch prints the exact command to retry it safely.
| Flag | Default | Purpose |
|---|---|---|
--expected-generation |
current generation | Generation being replaced; the rollback is refused if the application has moved on |
--wait |
false |
Wait for the rollback revision to become ready |
--timeout |
10m |
Rollout wait deadline |
--idempotency-key |
generated | Stable retry key; requires --expected-generation |
--json |
false |
Emit machine-readable JSON |
See rollbacks.
orch remove
orch remove APP [--idempotency-key KEY] [--target NAME] [--json]Removes an application's desired state, which stops its workloads.
| Flag | Default | Purpose |
|---|---|---|
--idempotency-key |
generated | Stable key for safe retries |
--json |
false |
Emit machine-readable JSON |
orch schema
orch schemaPrints the embedded Application.pkl schema that manifests amend.
orch pkl reader and version
orch pkl reader
orch pkl versionversion prints the Pkl version this CLI evaluates manifests with.
reader serves the embedded schema over Pkl's external-reader protocol on
stdin and stdout, so stock Pkl tooling can resolve older orch: imports. You
do not run it by hand.
Status, events, and logs
orch status
orch status [--target NAME] [--json]Shows the cluster name and ID, controller URL, generation, workload network, creation time, and when the administrator and controller certificates expire. Certificates that expire within 30 days are flagged with the renewal command.
orch nodes
orch nodes [--target NAME] [--json]Lists every node with its lifecycle and connection state, operating system, capacity, allocatable and assigned resources, labels, network and ingress state, drain blockers, and certificate expiry.
orch events
orch events [--after SEQUENCE] [--limit 50] [--target NAME] [--json]Prints cluster events with their sequence number, time, kind, and JSON payload.
| Flag | Default | Purpose |
|---|---|---|
--after |
0 |
Only events after this sequence number |
--limit |
50 |
Maximum events to return, 1 to 200 |
--json |
false |
Emit JSON, including next_after_sequence for the next call |
orch logs
orch logs APP SERVICE [--replica 1] [--tail 100] [-f | --previous] [--target NAME]Prints the most recent log lines of one service replica and exits. With -f
it keeps printing new output until you press Ctrl-C, and carries on through
restarts and short disconnects, noting them on stderr.
With --previous it prints the logs of the replica's previous instance: the
one a deploy, orch restart, or a failed start replaced. Nodes keep a
replaced instance's logs for 24 hours, up to 256 MiB per node with the oldest
dropped first. They stay on the node that ran it, so they are not found once
the replica has moved to another node.
On a terminal, logs, exec, and the job and cron log commands drop control
characters and escape sequences other than colors, so a workload cannot
control your terminal. Piped or redirected output is passed through unchanged.
| Flag | Default | Purpose |
|---|---|---|
--replica |
1 |
Replica ordinal |
--tail |
100 |
Maximum lines per stream, 1 to 10000 |
-f, --follow |
false |
Keep printing new output |
-p, --previous |
false |
Show the previous instance's logs |
orch restart
orch restart APP [SERVICE] [--replica N] [--target NAME]Restarts a service, or every service of the application, with the same spec.
Replicas restart one at a time, and each must be running again before the next
one stops. Each replica gets its stopGracePeriod to shut down. --replica
restarts just one replica.
orch exec
orch exec APP SERVICE [--replica 1] [--timeout 30] [--target NAME] -- COMMAND [ARG...]Runs a non-interactive command inside a running replica and streams its
output. A non-zero exit status from the command makes orch exec exit with 1.
| Flag | Default | Purpose |
|---|---|---|
--replica |
1 |
Replica ordinal |
--timeout |
30 |
Timeout in seconds, 1 to 300 |
The command takes 1 to 64 non-empty arguments and at most 8 KiB in total.
orch exec hello web --replica 1 -- ./bin/healthcheck --verboseorch volume
orch volume list [APP] [--target NAME] [--json]
orch volume backups APP VOLUME [--target NAME] [--json]
orch volume backup APP VOLUME [--target NAME] [--json]
orch volume restore APP VOLUME BACKUP [--target NAME] [--json]
orch volume download APP VOLUME BACKUP [--output FILE|-] [--target NAME]
orch volume move APP VOLUME NODE [--target NAME] [--json]list shows each local volume, its worker, its backup schedule, the newest
backup, and whether the last scheduled backup failed. backups lists every
backup of one volume. backup takes one now, running the volume's before
command first; it is labeled -manual and never pruned.
restore stops the service that mounts the volume, replaces the volume with
the backup, and starts the service again. The volume's previous contents are
kept as a -before-restore backup, and the command prints how to restore it.
download copies a backup archive (.tar.gz) to this machine, by default as
APP-VOLUME-BACKUP.tar.gz; --output - writes it to standard output. See
volume backups.
move moves the volume to NODE, together with every other volume of the
service that mounts it. The service stops, a final -manual backup of each
volume is copied to NODE through the controller and restored there, and the
service starts on NODE. If a step fails, the service starts on its old node
again with its data untouched. NODE must be active, connected, and match the
service's constraints. See moving a volume.
With a backup destination, backups also lists the copies in
the bucket and where each backup is stored, and restore and download
fetch a backup that only the bucket still has to the volume's node first.
orch backup
orch backup destination [--target NAME] [--json]
orch backup destination set s3://BUCKET[/PREFIX] [--endpoint URL] [--region REGION] [--new-recovery-key] [--target NAME] [--json]
orch backup destination remove [--target NAME] [--json]set makes the cluster copy every volume and database backup, and the
controller's daily backups, to an S3 bucket. It checks that the bucket is
writable and claims the prefix for this cluster first. Any S3-compatible
service works; leave out --endpoint for AWS. The region is detected when
left out. The access key comes from AWS_ACCESS_KEY_ID and
AWS_SECRET_ACCESS_KEY, or is asked for, and is stored encrypted on the
controller. The first set prints a recovery key that controller backups are
encrypted to before they reach the bucket; store it in a password manager,
because orch cluster restore --from needs it and the controller keeps only
its public half. Volume and database backups are always encrypted, to a key
the controller keeps. Setting the destination again keeps the key unless
--new-recovery-key is passed. Without an argument, destination shows the
bucket, whether controller backups are encrypted, and whether the last copy
succeeded. remove stops copying and leaves the bucket as it
is. See off-host backups.
orch db
orch db list [APP] [--target NAME] [--json]
orch db backups APP DATABASE [--target NAME] [--json]
orch db backup APP DATABASE [--target NAME] [--json]
orch db restore APP DATABASE [BACKUP] [--target NAME] [--json]
orch db move APP DATABASE NODE [--target NAME] [--json]Works with the databases declared under databases in orch.pkl. list
shows each database's engine, the secret that holds its connection URL, and
its backup schedule. backups and backup list and take backups of the
volume that holds the database's backups. restore uses the newest backup
unless BACKUP is given; for Postgres, MySQL, MariaDB and MongoDB it also loads
the restored dump into the running database. move moves the database and
its volumes to NODE, like orch volume move. See Databases.
Jobs
orch job
orch job run APP SERVICE [--wait] [--revision REVISION] [--timeout 15m] [--wait-timeout 20m] [--idempotency-key KEY] [--target NAME] [--json] -- COMMAND [ARG...]
orch job list [APP] [--limit 20] [--before ID] [--target NAME] [--json]
orch job show ID [--target NAME] [--json]
orch job logs ID [--tail 100] [--target NAME]
orch job cancel ID [--target NAME] [--json]
orch job retry ID [--wait] [--idempotency-key KEY] [--target NAME] [--json]
orch job wait ID [--timeout 15m] [--target NAME] [--json]Runs and manages one-off jobs. run starts a command with the image and
settings of a service in the current application revision. The other actions
list, inspect, read logs of, cancel, retry, or wait for a job.
| Flag | Default | Purpose |
|---|---|---|
--wait |
false |
Wait for the exact run to finish (run, retry, cancel) |
--revision |
none | Only run if this is the application's current revision |
--timeout |
15m |
Process timeout for run; wait deadline for wait. 10s to 24h |
--wait-timeout |
20m |
Maximum time --wait waits, 1s to 24h |
--limit |
20 |
Maximum jobs for list, 1 to 100 |
--before |
none | History cursor for list; printed as Next page: --before ID |
--tail |
100 |
Log lines per stream for logs, 1 to 10000 |
--idempotency-key |
generated | Stable key for run or retry, printed on stderr |
--json |
false |
Machine-readable output |
orch job run hello web --wait -- ./bin/migrate upSee jobs for pre-deploy hooks and retry behavior.
orch cron
orch cron run APP JOB [--wait] [--wait-timeout 20m] [--idempotency-key KEY] [--target NAME] [--json]
orch cron runs APP JOB [--limit 20] [--target NAME] [--json]
orch cron logs APP JOB RUN_ID [--tail 100] [--target NAME]run starts the scheduled job once now, with the same image, command,
secrets, and read-only volume mounts as its schedule and on the node that owns
the schedule. Use it to check that a backup job works without waiting for its
next run. The run is a job: follow it with orch job logs ID, and with
--wait the command exits nonzero unless it succeeds. runs lists recent
scheduled runs with their scheduled time, state, and reason; logs prints the
logs of one.
| Flag | Default | Purpose |
|---|---|---|
--wait |
false |
Wait for the run started by run to finish |
--wait-timeout |
20m |
Maximum time --wait waits, 1s to 24h |
--limit |
20 |
Maximum runs, 1 to 100 |
--tail |
100 |
Maximum lines per stream, 1 to 10000 |
--json |
false |
Emit machine-readable JSON (runs only) |
Secrets and registries
orch secret
orch secret set APP NAME --from-stdin [--idempotency-key KEY] [--target NAME] [--json]
orch secret list APP [--target NAME] [--json]
orch secret delete APP NAME [--idempotency-key KEY] [--target NAME] [--json]Stores, lists, and deletes an application's secrets. set only reads the value
from stdin, never from an argument, and accepts 1 byte to 1 MiB. list shows
each name, its current version, whether the application references it, and
when it was updated; it never shows values.
printf '%s' "$DATABASE_URL" | orch secret set hello database-url --from-stdinSee secrets.
orch registry
orch registry login HOST --username USER --password-stdin [--idempotency-key KEY] [--target NAME] [--json]
orch registry list [--target NAME] [--json]
orch registry logout HOST [--idempotency-key KEY] [--target NAME] [--json]Stores, lists, and removes credentials for private image registries. The password or token is read from stdin and accepts 1 byte to 1 MiB.
Deployer and access-token credentials can only use registries on public addresses, so an image reference cannot make the controller reach hosts on its own network. A registry on a private address works for them once an administrator has logged in to it.
orch github
orch github init [--app APP] [--branch BRANCH] [--environment NAME] [--image REPOSITORY] [--domain DOMAIN]... [--previews] [-f orch.pkl] [--repo OWNER/REPO] [--force] [--target NAME] [--json]
orch github trust OWNER/REPO --app APP [--branch main] [--environment NAME] [--domain DOMAIN]... [--previews] [--target NAME] [--json]
orch github list [--target NAME] [--json]
orch github untrust OWNER/REPO --app APP [--target NAME] [--json]Lets GitHub Actions runs of a repository deploy one application without stored
credentials. Run init inside the repository's checkout: it reads the
repository from the origin remote, the application from orch.pkl, and the
branch from the remote's default branch, trusts the repository, and writes
.github/workflows/deploy.yml. When a Dockerfile sits next to the manifest
and its workloads use one image repository, the workflow builds and pushes that
image before deploying; --image names the repository explicitly. trust does
the same without touching the checkout and prints the workflow instead. When ORCH_CLUSTER is set and no target is given, remote
commands sign in with the run's GitHub OIDC token, and ORCH_APP picks the
application when the repository is trusted for several. --domain, on
init and trust, limits the domains its deploys may route. --previews
lets pull requests deploy and remove their own APP-pr-N, and makes init
also write .github/workflows/preview.yml. See
deploy from GitHub and
preview deployments.
orch notify
orch notify add slack|discord|webhook [URL] [--name NAME] [--on EVENT,...] [--target NAME] [--json]
orch notify list [--target NAME] [--json]
orch notify test [NAME] [--target NAME] [--json]
orch notify remove NAME [--target NAME] [--json]Sends cluster problems (a lost node, a full disk, a certificate close to
expiry, a stale controller backup) to Slack, Discord or a webhook. add
stores the URL encrypted on the controller, reading it from stdin when it is
left out, and sends a test message; it exits nonzero when the test fails.
--on can also name application events, which are then sent for every
application. See cluster notifications.
orch token
orch token create [NAME] --app APP [--read-only] [--domain DOMAIN]... [--ttl 720h] [--target NAME] [--json]
orch token create [NAME] --admin [--ttl 720h] [--target NAME] [--json]
orch token list [--target NAME] [--json]
orch token revoke NAME [--target NAME] [--json]Gives an agent or script access to one application, without sharing your
administrator credentials. create prints a token on stdout. With it in
ORCH_TOKEN, every remote command and orch mcp can deploy, roll back, and
inspect APP (with --read-only, only inspect it) and nothing else. The token
contains the controller address and pins the cluster CA, so no target is
needed.
export ORCH_TOKEN=$(orch token create --app shop --read-only)
orch app status shop| Flag | Default | Purpose |
|---|---|---|
--app |
required unless --admin |
The one application the token may use |
--admin |
false |
Allow everything an administrator can do, for tools that manage the whole cluster; excludes --app and --read-only |
--read-only |
false |
Allow status, logs, history, and diffs, but no deploys or rollbacks |
--domain |
any | Deploys may route only this domain and its subdomains, and not the public listener; repeat for more |
--ttl |
720h |
How long the token works, up to 8760h |
NAME defaults to APP, or APP-read-only with --read-only, or admin
with --admin. An administrator token is exchanged for a 15-minute
administrator certificate, so treat it like a context file. The token is
shown only once; the controller keeps only a hash of it. Each command trades
it for a 15-minute certificate, so revoke takes effect within 15 minutes.
list shows when each token was last used. The controller address in the
token must be reachable from where the token is used.
Nodes
orch node usage
orch node usage NODE [--target NAME] [--json]Shows a node's CPU, memory and disk use over the last 24 hours (in 5-minute
buckets) next to what its replicas reserve and what it can offer. --json
prints the node and its samples, which orch mcp draws as graphs.
orch node label and unlabel
orch node label NODE KEY=VALUE... [--target NAME] [--json]
orch node unlabel NODE KEY... [--target NAME] [--json]Adds or removes node labels used by service constraints. The orch.* prefix
is reserved.
orch node cordon, uncordon, and drain
orch node cordon NODE [--target NAME] [--json]
orch node uncordon NODE [--target NAME] [--json]
orch node drain NODE [--target NAME] [--json]cordon stops new placement on a node, drain moves its movable workloads
away, and uncordon makes it active again. drain prints an
orch volume move command for each service a local volume keeps on the node.
See
node maintenance.
orch node update
orch node update NODE...|--all [--drain-timeout 10m] [--reboot-timeout 15m] [--target NAME] [--json]Upgrades the operating-system packages of the named nodes, or of every node
with --all, one node at a time: drain, upgrade with apt-get or dnf,
reboot when the upgrade needs it, wait for the agent, return the node to
service. Workers go first, then ingress nodes, then the controller's host.
When a drain takes longer than --drain-timeout, the update goes ahead
anyway. Nodes that are not connected are skipped and reported. See
operating-system updates.
orch node ingress
orch node ingress NODE --enable|--disable [--target NAME] [--json]Turns public HTTP, HTTPS, and TCP ingress on or off for a node. Exactly one of
--enable or --disable is required.
orch node remove
orch node remove NODE [--lost --confirm-fenced] [--target NAME] [--json]Removes a node from the cluster. For a node that is unreachable, pass both
--lost and --confirm-fenced to confirm it can no longer run workloads.
All node update commands also accept --idempotency-key KEY.
Network
orch network configure
orch network configure --cidr CIDR [--idempotency-key KEY] [--target NAME] [--json]Sets the private workload network.
| Flag | Default | Purpose |
|---|---|---|
--cidr |
10.88.0.0/16 |
RFC 1918 workload CIDR, /16 through /19 |
--idempotency-key |
generated | Stable key for safe retries |
--json |
false |
Emit machine-readable JSON |
Once a worker reports its network as ready, the network is frozen and a different CIDR is refused. Choose it before workers join. See networking.
Upgrades
orch cluster upgrade and orch node upgrade
orch cluster upgrade [--binary FILE] [--dry-run] [--wait-timeout 5m] [--json]
orch node upgrade [--binary FILE] [--dry-run] [--wait-timeout 5m] [--json]Replaces the installed orch binary on a controller or worker with a trusted
candidate and restarts its services. Run each as root on the host it upgrades.
After orch cluster upgrade, the controller upgrades every worker to its own
version, one node at a time, so orch node upgrade is only needed for a worker
that cannot upgrade itself.
| Flag | Default | Purpose |
|---|---|---|
--binary |
this orch |
Trusted local candidate orch executable |
--dry-run |
false |
Validate and show the upgrade without changing the host |
--wait-timeout |
5m |
Maximum wait for service readiness |
--json |
false |
Emit machine-readable JSON |
The output reports compatibility, the candidate version and SHA-256, planned actions, and a recovery path. See upgrades.
Backup and recovery
These commands work on controller files directly and run as root on the controller host or a recovery host.
orch cluster backup
orch cluster backup --data-dir DIR --output FILE [--secret-key-output FILE] [--json]Writes a standalone copy of the controller database.
| Flag | Default | Purpose |
|---|---|---|
--data-dir |
required | Controller state directory, /var/lib/orch-controller for installed controllers |
--output |
required | New backup database path |
--secret-key-output |
none | New path for the secret-encryption key, when one is required |
--json |
false |
Emit machine-readable JSON |
orch cluster backup inspect
orch cluster backup inspect --backup FILE [--pki-dir DIR] [--secret-key FILE] [--json]Checks a backup without restoring it and reports its cluster, schema version, counts of nodes, applications, deployments, and jobs, and any missing recovery material.
orch cluster restore
orch cluster restore --backup FILE|DIR [--pki-dir DIR] [--secret-key FILE] --data-dir NEW_DIR [--json]
orch cluster restore --from s3://BUCKET[/PREFIX] [--backup NAME] [--endpoint URL] --data-dir NEW_DIR [--json]Restores a backup into a new controller directory, which must not exist.
--backup also takes one of the controller's automatic backup directories
from DATA_DIR/backups, which already holds the PKI and secret key, so the
other two flags are not needed. orch cluster backup inspect accepts the
same.
--from downloads the newest controller backup from the cluster's
backup destination instead, or the one --backup names. It
reads the access key from AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or
asks for it, and the recovery key of an encrypted backup from
ORCH_RECOVERY_KEY, or asks for it.
| Flag | Default | Purpose |
|---|---|---|
--backup |
required without --from |
Standalone database backup, an automatic backup directory, or with --from a backup name |
--from |
none | Bucket to download the backup from |
--endpoint |
AWS | S3 endpoint for --from |
--region |
detected | Signing region for --from |
--pki-dir |
none | Saved controller PKI directory |
--secret-key |
none | Saved secret-encryption key |
--data-dir |
required | New controller directory |
--json |
false |
Emit machine-readable JSON |
orch cluster certificates renew
orch cluster certificates renew --data-dir DIR --admin-dir NEW_DIR [--json]Issues new controller and administrator certificates from the existing cluster
CA. Restart the controller afterwards and import the new context with
orch target import NAME CONTEXT --replace. After the restart, administrator
certificates issued before the renewal are refused. See
certificate renewal.
TUI and web dashboard
orch tui
orch tui [--target NAME] [--refresh 2s]Opens the keyboard-driven terminal interface for the selected target. It needs an interactive terminal.
| Flag | Default | Purpose |
|---|---|---|
--refresh |
2s |
Refresh interval, 1s through 1m |
orch web
orch web [--target NAME] [--port N] [--no-open]Serves the browser dashboard for the selected target on 127.0.0.1 and prints
a one-time URL. Press Ctrl+C to stop it.
| Flag | Default | Purpose |
|---|---|---|
--port |
0 |
Loopback port; 0 picks a free port |
--no-open |
false |
Print the URL without opening a browser |
See targets and interfaces for both interfaces.
orch mcp
orch mcp [--target NAME] [--read-only | --allow-destructive]Serves the cluster to AI assistants over the Model Context Protocol on stdin and stdout. Clients such as Claude Code start it themselves; see AI assistants for setup and the list of tools.
| Flag | Default | Purpose |
|---|---|---|
--target |
selected target | Cluster that remote tools use when a call names none |
--read-only |
false |
Offer only tools that do not change the cluster |
--allow-destructive |
false |
Also offer tools that delete or replace workloads, secrets and data, or run commands in replicas |
orch mcp expose and approve
orch mcp expose [DOMAIN | --off] [--target NAME] [--json]
orch mcp approve CODE [--deploy | --allow-destructive] [--app APP] [--ttl 720h] [--target NAME] [--json]expose serves the MCP server from the controller at https://DOMAIN/mcp,
for any MCP client that connects by URL with OAuth. Point DNS for
DOMAIN at the controller's server; its ingress gets the certificate. Without
arguments it prints the current URL, and --off stops serving it.
approve lets the assistant waiting on the approval page with CODE connect.
See remote MCP.
| Flag | Default | Purpose |
|---|---|---|
--deploy |
false |
Also allow rolling back, restarting, backing up, retrying jobs and running cron jobs |
--allow-destructive |
false |
Allow everything the MCP tools can do, including deleting apps, changing secrets and running commands in replicas |
--app |
every app | Limit the connection to what an access token for this application can do |
--ttl |
720h |
How long the connection works, from 1h to 8760h |
Services and internals
These commands are run by the systemd units that orch init, orch join, and
the install commands create. You rarely run them yourself.
orch controller serve
orch controller serve --data-dir DIR --listen ADDRESS [--admin-socket PATH|off] [--mcp-listen ADDRESS|off] [--backups-keep 7]Runs the controller process. It writes a backup into DATA_DIR/backups once a
day; see backups.
| Flag | Default | Purpose |
|---|---|---|
--data-dir |
required | Initialized controller state directory |
--listen |
required | TCP listen address, for example 0.0.0.0:9443 |
--admin-socket |
DATA_DIR/admin.sock |
Local administrator socket; off disables it |
--mcp-listen |
127.0.0.1:9444 |
Loopback address of the remote MCP gateway that the ingress on this host forwards orch mcp expose's domain to; off disables it |
--backups-keep |
7 |
Daily backups to keep, 0 to 365; 0 turns automatic backups off |
orch agent init
orch agent init --join-file FILE|- --data-dir DIR [--json]Enrolls an agent with a join file and writes its state directory.
orch agent serve
orch agent serve --data-dir DIR --containerd-socket PATH --advertise-address IPV4 [flags]Runs the worker agent.
| Flag | Default | Purpose |
|---|---|---|
--data-dir |
required | Agent state directory |
--containerd-socket |
required | containerd socket path |
--advertise-address |
required | Private or public IPv4 address reachable by the other nodes |
--snapshotter |
overlayfs |
containerd snapshotter |
--wireguard-port |
51820 |
WireGuard UDP listen port |
--system-reserved-cpu |
500m |
CPU reserved for the host |
--system-reserved-memory |
512Mi |
Memory reserved for the host |
--cni-bin-dir |
/opt/cni/bin |
Directory containing the CNI plugins |
--caddy-binary |
/usr/bin/caddy |
Pinned Caddy executable |
--ingress-user |
orch-ingress |
Unprivileged user that runs Caddy |
--ingress-data-dir |
/var/lib/orch-ingress |
Private Caddy data directory owned by --ingress-user |
Other commands
| Command | Purpose |
|---|---|
orch version [--json] |
Print the version, or build information as JSON |
orch help |
Print the usage summary |
orch runtime-log-sink, orch runtime-secret-init |
Helpers that the agent starts inside workload runtimes; not for direct use |