✦ EVERY COMMAND, IN ONE PLACE
CLI Command Reference
Each card below is one command: what it's for, then its flags. Commands and flags are written exactly as you'd type them.
Words you'll meet on this page
A reference page jumps around, so here are the words it leans on, each in a line. Skim it once and the rest of the page will read easily.
- your orchy: your computers, joined into one small cloud by Orchy. Each computer in it is a device.
- app: a program you run on your orchy. To deploy an app is to put it there and start it.
- brain: the device that keeps your orchy's records and decides which device runs which app.
- mesh: the private, encrypted network your devices talk over.
- join code: a one-time password that lets a new device into your orchy.
- front door: where visitors from the internet arrive. A tunnel is the connection your device opens outwards so they can get in without any open ports on your router. Cloudflare, Tailscale and ngrok are companies that provide tunnels.
- domain: a web address, like example.com. A zone is a domain you've handed to Orchy so it can make addresses under it, such as app.example.com. A route connects one address to one app.
- certificate: the file behind the browser's padlock (HTTPS, also called TLS). Let's Encrypt is a free service that issues them, and Orchy fetches them for you.
- data disk: storage an app writes to like a normal folder, copied to other devices. A snapshot is a saved moment of a disk you can go back to.
- bucket: a shared place for files that every device can reach. Facts are small shared notes. Secrets are passwords and keys, kept encrypted.
- isolation: how boxed-in an app is. Raw means no box. Guarded keeps it apart from other programs. Jailed locks it down hard. Sealed puts it in its own tiny virtual machine (a microVM).
- container image: an app packed up with everything it needs, in the format Docker made popular. A registry is the online shelf images are kept on.
- access key: a password that lets a program or a far-away computer give your orchy commands.
- tenant: a named group of apps that belong to someone else, kept apart from yours.
- daemon: the Orchy program running quietly in the background on each device. Its name is
orchyd. - pipeline: a list of steps (build, test, release) that runs by itself. People call this CI/CD.
- flag: an option you add to a command, starting with two dashes, like
--json.
These flags work on every command.
| Flag | Type | Default | Description |
|---|
| --json | bool | false | Print JSON (a format programs can read) instead of text, for scripts and AI tools |
| --verbose | bool | false | Say more: why each decision was made, and how long things took |
| --state-dir <path> | string | ~/.local/share/orchy | The folder where your orchy keeps its files on this device |
| --tenant <name> | string | default | Act for this tenant (a named group of 3rd-party apps) instead of your own |
| -s, --socket <path> | string | <state-dir>/orchy.sock | Where to find the daemon's control socket (the local file the CLI talks to it through), if it isn't in the usual place |
| -F, --fabric <name> | string | orchystra | Which orchy to talk to, when this device runs more than one |
| -e, --endpoint <url> | string | <local socket> | The web address of an orchy on another machine (e.g. https://your-orchy-domain) |
| --token <token> | string | "" | Access key, for giving commands from another machine or a pipeline (created with orchy token create) |
orchy up [join-code]
Lifecycle
Gets this device going. Run it with nothing after it on a fresh machine and it starts a brand-new orchy, with this device as the brain. Give it a join code and it finds your brain (at its public address) and joins the orchy you already have.
| Flag | Type | Default | Description |
|---|
| --name <name> | string | orchystra | Name of your new orchy |
| --new | bool | false | Start an additional orchy on this device, beside any already here (--create still works but is deprecated) |
| --device <name> | string | $(hostname) | A name for this device, if you don't want its hostname (--node is a deprecated alias) |
| --mesh-addr <addr> | string | 0.0.0.0:7946 | The address this device listens on for the mesh |
| --public-addr <addr> | string | auto | The public address other devices should call, written into join codes |
| --relay <addr> | string | auto | The brain's public address, for devices stuck behind a home router |
| --tunnel <provider> | string | cloudflare | Which tunnel provider to use: cloudflare, tailscale or ngrok |
| --tunnel-token <token> | string | "" | The token your tunnel provider gave you |
| --domain <zone> | string | "" | The zone Orchy makes app addresses under (e.g. example.com; --zone is a deprecated alias) |
| --mesh-zone <zone> | string | "" | The zone for your orchy's own public address, <fabric-id>.<zone> (e.g. mesh.example.com) |
| --foreground | bool | false | Run the daemon in this terminal, where you can watch it |
| -r, --restart | bool | false | Restart the daemon even if it's already running |
$ orchy up --name my-mesh --device nas-server
✦ your orchy 'my-mesh' started successfully on nas-server
Mesh relay active on 0.0.0.0:7946 • Join code: orchy1_AgAE4WPWrAkVUteChY3…
Stops orchy on this device, tidies up after itself, and closes any tunnels.
$ orchy down
Draining local sessions...
Stopping Front Door proxy and tunnel connectors...
✓ Orchy daemon on this host stopped cleanly
orchy join <join-code>
Lifecycle
A shortcut: join this device to your orchy with a join code.
$ orchy join "orchy1_AgAE4WPWrAkVUteChY3…"
✓ connected to your orchy "orchystra" · daemon online
✓ joined your orchy "orchystra" · worker-1 · linux/amd64
✓ classified: always on → worker
orchy deploy [dir|url|image]
Apps
Puts an app online. It reads your project, shows you a plan, packages the app, sends it to your devices, and sets up HTTPS at the front door. You can also hand it a container image (orchy deploy nats:2.10-alpine). Then it pulls the image, pins the exact version it got (its digest) so it can't change under you, and runs it jailed, in its own root filesystem. You don't need Docker. A few things to know about images: they run on Linux devices only; the app gets no network of its own and can only call the addresses you list with --egress; its ports are reachable on the device; and its data lives on a data disk if you give it one with --volume.
| Flag | Type | Default | Description |
|---|
| --plan | bool | false | Show the plan and stop. Nothing is deployed |
| --isolation <tier> | string | "" | How boxed-in the app is: owner (raw), soft (guarded), strong (jailed) or max (sealed). An access key with the deployer role has to pick soft or stronger |
| --env <KEY=VALUE> | string[] | [] | Set an environment variable (a named setting the app can read); can be given more than once |
| --on / --avoid / --prefer | string[] | [] | Say where the app should run: only on, never on (both strict), or ideally on (prefer) a device or key=value; repeatable |
| --rollout <strategy> | string | "" | How the new version replaces the old: blue-green (start the new one beside the old, then switch), all-at-once, rolling (one device at a time) or phased (in growing steps, with --rollout-phases 5,25,100) |
| --branch <ref> | string | "" | Branch, tag or commit to deploy (git URL targets only) |
| --force-all-devices | bool | false | Put the new version on every device that can run it |
| -y, --yes | bool | false | Accept the plan without asking |
Container image flags (used when the target is an image such as nats:2.10-alpine):
| Flag | Type | Default | Description |
|---|
| --volume <name:/path[:interval]> | string[] | [] | Container image: a data disk, a real directory at that path inside the image. It is snapshotted into your orchy when it changes (every minute by default, or the interval you give; at most that much can be lost if the device is), and restored on whichever device takes the app over. The app runs as one copy. orchy rm keeps the disk's files on the device |
| --port <n> | int[] | all exposed | Container image: a port to reach it on; repeatable. The first is the app's port; each other gets a host port of its own, shown in orchy apps --json |
| --egress <host:port> | string[] | [] | Container image: an outside address it may call, through a proxy on the host. Nothing else can be reached |
| --cpu / --memory | string | "" | Container image: limits (500m, 512Mi). Enforced where this device delegates cgroups to orchy; the result says which are in force and which are not, and why |
| --registry-secret <scope> | string | "" | Container image: the secret scope holding REGISTRY_USER and REGISTRY_PASSWORD to reach a private registry. Your orchy pulls the image with them, and they are never shown, never kept in the spec, and never reach your machine |
| --run-as <user> | string | "" | Container image: the user it runs as (name, uid or uid:gid); default is the image's own user, or root. Databases whose image declares none need this (--run-as postgres) |
| --platform <os/arch> | string | what your devices run | Container image: the platform to pull, e.g. linux/arm64. An image is built for one platform and is placed only on devices of it |
$ orchy deploy ./studio --yes
Packaging your app • sha256:d82e1... (3.4 MB)
Deploying to epic-nas · keeping 2 copies of your data...
Configuring the front door: studio.example.com → port 8080...
✓ App 'studio' is live at https://studio.example.com
Lists your apps, whichever device they're on.
$ orchy ps
NAME SUITE TENANT PID STATE ISOLATION PORT DEVICES / DOMAIN
studio default 14812 healthy raw :0 epic-nas · studio.example.com
Shows what an app is printing, from whichever device is running it. Other apps' secrets are blanked out.
orchy stop & orchy restart
Apps
Pauses or restarts an app. Its data and settings stay put.
orchy start • rm • settings • tools place
Apps
Things you can do to an app once it's deployed.
orchy start <app>
Starts a stopped app.
orchy rm <app> [--yes] [--routes]
Permanently removes an app: every device stops it, and its files, routes and saved settings are deleted. --routes also deletes your own domains that point at it. A container image's data disks are kept, so deploying it again brings its data back; --volumes deletes them from every device and from your orchy.
orchy settings <app> [--copies N] [--sleep-when-idle yes|no] [--idle-time 10m]
Shows or changes how many devices run the app, and whether it sleeps when idle. With no flags on a terminal it opens an editor.
orchy tools place <app> --on / --avoid / --prefer
Steers where a deployed app runs: --on and --avoid are hard rules, --prefer is a soft one.
Already got something running on this device? This gives it a public address (orchy expose <port>) without deploying anything. For a domain of your own, use orchy domain add.
orchy pipeline (alias: orchy ci)
CI/CD
Runs your build-and-release steps (a CI/CD pipeline) on your own devices. There's no separate runner to install. Orchy looks for orchy.pipeline.json (or pipeline.json) in the current folder, runs each step on the device that suits it best, and shows you progress as it goes.
orchy pipeline run [spec-file] [-w | --wait]
Runs a pipeline from its spec, the file that lists its steps (orchy.pipeline.json or pipeline.json unless you name another). -w waits and shows each step's status as it goes.
orchy pipeline list
Lists recent runs, their trigger, status, steps, and duration.
orchy pipeline status <run-id>
Shows how a run is going, step by step: which device ran it, how it ended and how long it took.
orchy pipeline logs <run-id> [step]
Views the console output of a run, or of a single step.
orchy pipeline install <spec-file> · orchy pipeline installed
Keeps a pipeline on your orchy so something else can start it. The usual way is a webhook: a web address another service calls to say "something happened", for example your git host announcing a new release tag. Your orchy serves that address for you. installed lists what is installed and where each webhook is served.
orchy pipeline retry <run-id> · orchy pipeline cancel <run-id>
Tries a failed step again on another device, or cancels a run.
$ orchy pipeline run --wait
✦ Triggering pipeline "quick-smoke" on the fabric...
▸ Step lint-and-vet running...
✓ Step lint-and-vet succeeded (412ms)
✦ Pipeline quick-smoke succeeded in 1.2s ✨
orchy device <subcommand>
Devices
Looks after your devices: who's a member, when each one is around, moving apps off a device before you work on it (a drain), and shutting out one you no longer trust.
orchy device status [<device>]
Shows a device's role, when it's available, its memory/CPU limits, and whether it can hold your data.
orchy device drain <device>
Moves running apps off a device, in an orderly way, before you take it down.
orchy device boot <device>
Removes a device that's stopped answering or is gone for good.
orchy device ban-list & unban <device>
Shows the devices you've shut out, and lets one back in.
orchy brain <subcommand>
Devices
A look at your orchy's brains: which one is in charge right now, and which devices keep a share of the key that signs every device's identity (the CA key).
orchy brain status
Which device is the brain, which devices hold a share of the key, and when the shares were last dealt out again (a re-key).
orchy brain add <device> · remove <device>
Gives a device a share of the CA key, so more than one device can stand in as brain, or takes its share away. Either way the shares are dealt out again.
orchy brain elect
Holds a brain election now: the freshest device wins, and a majority must agree.
orchy brain collapse
Takes your orchy back to a single brain, which puts the CA key back together on one device.
orchy domain <subcommand>
Network
Sets up web addresses for your apps: ones Orchy hands out under your zone (*.<zone>), or a domain you bring yourself. Either way you get an HTTPS certificate from Let's Encrypt without lifting a finger.
orchy domain add <domain> [target-port]
Points a domain at an app. Leave out the port and it uses the front door's usual one.
orchy domain list
Lists your domains, whether each has its certificate, and which tunnel serves it.
orchy domain rm <domain>
Removes a domain and lets go of its certificate.
$ orchy domain add studio.example.com --port 8080
Add this and I'll handle the rest (I wait for DNS, then ACME — usually <60s):
CNAME studio.example.com → edge.example.com
✓ domain studio.example.com registered (TLS: acme)
$ orchy domain list
DOMAIN CLASS TARGET TLS STATUS
studio.example.com custom :8080 acme active
orchy tools disk <subcommand>
Storage
Takes a snapshot of an app's data disk, and puts the disk back to a snapshot when you need to. Every save the app makes already reaches your other devices. Snapshots are different: they're the moments you pick to be able to go back to, like a save point in a game.
orchy tools disk snapshot <app> <disk> [name]
Keeps the disk as it stands now, under a name (the time, if you give none).
orchy tools disk snapshots <app> <disk>
Lists the copies kept of the disk.
orchy tools disk restore <app> <disk> <name>
Puts the disk back to a kept copy. The app restarts on it; what it wrote since is gone from the disk.
orchy tools float-disks <app>
Moves an app's disks from the older kind (copied by snapshot every so often) to the newer kind (every save copied as it happens). The app restarts once, from each disk's last snapshot.
$ orchy tools disk snapshot limerance state before-upgrade
✓ kept limerance's disk state as before-upgrade (3 files, 48.2 MB)
$ orchy tools disk restore limerance state before-upgrade
✓ limerance's disk state is going back to before-upgrade; the app restarts on it
orchy storage <subcommand>
Shared Storage
Makes shared storage places (buckets) that every device in your orchy can use. They're kept in more than one copy, and you can give one a public address if you want.
orchy storage create <name> [--replication <n>]
Creates a shared storage place. Copies default to 2; pass --tenant to make it for another tenant.
orchy storage list · orchy storage status <name>
Lists your storage places with copy count and health, or shows one in detail.
orchy storage put <name> <key> · get · ls · rm
Upload (- reads what you pipe in), download, list and delete files in a storage place.
orchy storage key create|list|revoke <name>
Bucket keys: a key ID and secret that reach one bucket, with one role. They work with tools made for Amazon S3, the best-known file storage service. The secret is shown once.
orchy storage archive <name> <key> · restore
Moves a file you rarely touch into space-saving storage: it's split into pieces with a few spares, one per device, so it can be rebuilt if some are lost (the method is called Reed-Solomon coding). Restore brings it back to full copies.
orchy storage expose <name> --domain <domain>
Gives a storage place a public address through the front door.
$ orchy storage create photos
created storage place default/photos
$ orchy storage list
default/photos · 2 copies · healthy
orchy kv <subcommand>
Shared Notes
Reads and changes shared notes (facts) that apps on any device keep in sync. Each change gets a revision number, so you always see the latest agreed value.
orchy kv get <key> · orchy kv set <key> <value> --durability local|quorum
Reads or writes a shared value. Writes report the new revision number.
orchy kv watch [prefix]
Follows changes live — every update across your devices prints key, value, and revision.
$ orchy kv set theme dark --durability local
saved theme at revision 1
$ orchy kv watch theme
theme = "dark" (revision 1)
orchy secret <subcommand>
Security
Keeps passwords and API keys encrypted, for one app or one tenant. A secret's value is never logged and never shown back to you.
orchy secret set <scope> <KEY> [VALUE]
Encrypts and stores a secret (with AES-256-GCM, a standard strong cipher). Leave out VALUE and it asks you for it without showing what you type.
orchy secret list [<scope>]
Lists secret names and who they're for. Values are never shown.
orchy secret rm <scope> <KEY>
Deletes an encrypted secret from the fabric store.
$ orchy secret set default API_KEY "sec_98124"
✓ saved as default · injected as env · encrypted at rest
$ orchy secret list
API_KEY
DATABASE_URL
orchy trust & orchy tenant
Security
You decide who gets to run apps on your devices, just you or 3rd parties too, and how tightly their apps are boxed in.
orchy trust show [<node>]
Shows who's trusted on this device and how other people's apps are boxed in.
orchy trust allow <tenant>
Lets a tenant run apps on this device, at the isolation you choose (--isolation soft|strong).
orchy trust deny <tenant>
Stops a tenant running apps on this device.
orchy tenant add <name>
Creates a new tenant.
orchy tenant list
Lists your tenants and the apps each one is running.
$ orchy trust
Trust Posture: foreign deny
Min Isolation: jailed
Allowed Tenants: none (foreign: deny default)
Makes access keys, so something that isn't one of your devices can still talk to your orchy: a GitHub Actions job, say, or your laptop at a café.
orchy token create [--tenant <name>] [--role <role>] [--ttl <duration>]
Generates a fresh access key (default role deployer, valid 30 days; change it with --ttl). Prints the exact ORCHY_ENDPOINT / ORCHY_TOKEN exports for your runner.
$ orchy token create
✦ Generated CI/CD & Remote Access Key:
orchy_tok_5078…
export ORCHY_ENDPOINT="https://your-fabric-domain"
export ORCHY_TOKEN="orchy_tok_5078…"
orchy deploy
orchy events • explain • advise • summary
Intelligence
What happened, and why. Every action your orchy takes is written down and kept in your fabric store, so you can ask later.
orchy events [-f]
Shows what your orchy is doing and deciding as it happens, one JSON record per line.
orchy explain <resource-or-event-id>
The "why" command: shows the trail of decisions behind anything that happened.
orchy advise
The Advisor: suggests moving apps between devices for speed, flags anything risky, and proposes improvements.
orchy summary
Outputs the “What Have I Built” summary: your devices, apps, storage copies, and how open your front door is.
orchy update & orchy daemon
Maintenance
Updates orchy on your devices one at a time, lets you roll back if an update goes badly, and manages the background program (the daemon) itself.
orchy update status • rollout [<ver>] • rollback
Shows each device's version, updates them one at a time, or reverts to a previous build.
orchy daemon start • stop • restart • reload • status
Starts, stops and restarts the daemon. Reload picks up new tunnel settings and certificates without a restart.