CLI

One executable is both the node daemon and the operator commands. Top-level commands, in the order scafo --help prints them:

sail, health, remote, operator, fleet, app, deploy, deployment, trust, metrics, traces, wg.

Two hidden aliases remain from a rename: scafo up → scafo sail, and scafo keygen → scafo operator keygen. Both still work, print a deprecation line before running, are hidden from help, and are removed at launch.

#Exit behaviour

Every command wraps its work in a single failure reporter.

The bracketed urn:scafo:<code> is the stable contract; see /reference/errors. A failure answered by a node is re-rendered from the node's own problem document, so the code the node chose is the code printed.

#Shared flag groups

Referenced by name in each command below.

#Bucket flags

Where the registry lives, taken exactly as scafo sail takes them. All strings.

Each also reads from the environment and the config file; see /config for precedence and variable names.

#Remote flags

Which installation an invocation reaches, and who is speaking. All strings.

Resolution order: the key comes from --key, then SCAFO_OPERATOR_KEY, then the remote. The endpoint comes from --node, then whatever a portable key carried, then the remote. The remote comes from --remote, then SCAFO_REMOTE, then the config file's remote pin, then the only remote registered; a home holding several with nothing to choose between them prompts on a TTY and is refused (invalid-input) otherwise.

#--json

Boolean. Prints the records as JSON instead of a table. Accepted by fleet nodes, app list, app show, app domain add, app domain remove, app domain list, metrics and traces.

#Naming an application

Every command that acts on one application addresses it the same way, with two flags resolved client-side before anything is contacted:

--env is a naming convenience and nothing else: the node never sees it, and --name shop --env preview addresses the application shop-preview exactly as --name shop-preview would. Both halves must be application names in their own right, and so must the joined result; a join that is no name — too long for a DNS label, above all — is refused with invalid-slug naming both parts.

An application name is 1–63 lowercase alphanumeric characters, optionally separated by single hyphens.

--name is required by app (every subcommand), trust (every subcommand) and deployment prune. It is optional on deploy, where the project directory's config supplies it, and on metrics and traces, where leaving it out means every application.

#scafo sail

scafo sail [flags]

Join this machine to the fleet and serve the node API. Talks to the bucket (registers the node, reads and writes the registry) and binds the node API listener. Prints scafo <version> listening on <url> as node "<id>" once serving.

Every flag is the kebab-case name of a configuration setting, plus --config. Flags win over environment variables, which win over the config file. Booleans support --no- negation; a boolean nobody wrote leaves the environment and the file to decide.

#scafo health

scafo health [bucket flags] [--listen] [--transport] [--wg-address]

Ask this machine's node whether it is serving. Talks to the local node API — GET /.well-known/scafo/health, with a 2-second deadline. It is what the image's HEALTHCHECK runs.

It resolves node.listen exactly as scafo sail does, from the environment and the config file, so the probe follows the listener. A setting given to the daemon only on its command line must be repeated here.

Failures are not-found: Node is not answering (nothing answered within the deadline) or Node is not healthy (something answered, but not the health document this node serves). Both name the URL that was asked.

#scafo remote

Name the installations you can reach, and hold the key that speaks to each. Everything here acts on the operator home (a local directory), except --register, which writes to the bucket.

#scafo remote add

scafo remote add [name] --endpoint <url> [flags]

Register a remote, with a key of its own.

Without --register, a freshly minted key is only local: register it later, or have an admin admit it with scafo operator enroll.

#scafo remote list

scafo remote list

Print the remotes this operator can reach. No arguments.

#scafo remote remove

scafo remote remove <name>

Unregister a remote, and its key if nothing shares it. name is a required positional. Nothing is said to the installation itself: the key it holds stays accepted there until it is removed from the registry.

#scafo remote export

scafo remote export <name> [--out <file>]

Write a remote out as one portable, self-contained file.

#scafo operator

The people: every human here is an operator, and admin is a role an operator holds.

#scafo operator keygen

scafo operator keygen [bucket flags] [--out <file>] [--id <op-...>] [--register] [--role <tier>]

Write an operator key file for the node API. To set an operator up, use scafo remote add instead. Talks to nothing unless --register is given, which writes the public half straight to the bucket — the bootstrap path, needing no daemon.

#scafo operator show

scafo operator show [--config] [--remote] [--key]

Print this operator's public half, to send to an admin. Local only. The document goes to stdout and the explanatory line to stderr, so scafo operator show > me.json produces a file an admin can enrol as it stands.

#scafo operator enroll

scafo operator enroll <pubkey> [--remote <name>] [--role] [--apps] [--node] [bucket flags]

Admit somebody else's public key to a fleet. Two paths, never chosen by default: the wire path (POST /v1/operators on a node, authorized by an admin key) and the bucket ceremony (authorized by the bucket credential, for an installation being seeded or one that has locked every operator out).

The bucket ceremony seeds and recovers admins: it is never scoped and never at the operator tier.

#scafo operator rotate

scafo operator rotate [--config] [--remote] [--node] [--keep-old] [--purge-old]

Replace the key a remote signs with, proving the new one before dropping the old. Talks to the node API.

#scafo operator revoke

scafo operator revoke --id <id> [--config] [--remote] [--node]

Stop a fleet trusting a key that is not your own. Talks to the node API.

#scafo operator list

scafo operator list [--config] [--remote] [--node]

Print the operator keys a fleet trusts, and their tiers. Talks to the node API. An admin sees every key; an operator sees only its own rotation lineage.

#scafo fleet

The machines of one installation: what is out there, and what it is doing.

#scafo fleet nodes

scafo fleet nodes [bucket flags] [--json]

List the machines in this fleet, and which are answering. Reads the bucket directly; no node has to be up. Every row is judged against one now, so nodes never appear to drift apart. Columns: NODE, STATE, SEEN, API, CELLD, SCAFO, LABELS; above the table, one line per binary counts nodes per version, newest first, and — while one stands — a line naming the deploy freeze, since when, by whom and why. --json carries the same rows, with versions: { scafo, celld } where the record has them, and no freeze line.

#scafo fleet freeze

scafo fleet freeze [remote flags] [--reason <line>]

Stop every deploy of this installation, leaving serving alone. Admin only. Talks to a node, on the authority of an operator key: freezing is an authorization the bucket cannot enforce, so there is no bucket path here. Without a node the refusal is invalid-input, No node to ask.

While it stands, every node refuses deploy intake with deploys-frozen (409) before anything is created. Serving, reconciliation, retirement and scafo app delete carry on untouched.

Freezing twice is one freeze: the first admin's record — stamp and reason — is the one that stands, and the command says so.

scafo: deploys are frozen since 2026-09-18T09:12:04.115Z by "op-9f3c": moving every node to a new Celld release — every deploy is refused with deploys-frozen until "scafo fleet unfreeze"
scafo: deploys were already frozen since 2026-09-18T09:12:04.115Z by "op-9f3c" — every deploy is refused with deploys-frozen until "scafo fleet unfreeze"

#scafo fleet unfreeze

scafo fleet unfreeze [remote flags]

Take deploys again after a freeze. Admin only, and reaches the installation the same way.

scafo: deploys are no longer frozen; nodes accept them again
scafo: deploys were not frozen

#scafo app

The things this installation hosts: list, inspect, place, retire and delete them. There is no create subcommand: an application comes into being on the first deploy that names it, and every verb here refuses a missing one with not-found.

Every subcommand takes the remote flags and names its target with --name and --env.

list, show, block, unblock and label are operator-key acts and have no bucket path: without a node the refusal is invalid-input, No node to ask. label replaces every label the application carries; passing no pairs clears them. A non-admin's view of an application omits the fleet-owned labels.

The rest also take the bucket flags and write the registry directly when no node is named. selector requires exactly one of --set and --clear; both, or neither, is invalid-input. delete prints the count and then every store key it removed, one per line — the record, its trust policy, its deployments, its deploys, its placement, its domain claims and the whole fleets/<name>/ prefix.

#scafo app domain

scafo app domain add    <host> --name <name> [--env <name>] [--wildcard] [--json]
scafo app domain remove <host> --name <name> [--env <name>] [--json]
scafo app domain list          --name <name> [--env <name>] [--json]

The custom hosts an application answers on, beside its platform host. Over a node, both writing subcommands are POST and DELETE /v1/applications/:name/domains/:host, which answer to an operator token alone — a workload token never reaches them.

The host is checked client-side before anything is contacted: it is lowercased, and anything that is no host to claim is invalid-input naming the rule it broke — a scheme, a path, a port, a *, a trailing dot, an empty or over-long label, a label outside letters, digits and inner hyphens, a name of one label only, or a last label of digits alone. A host equal to or under one of the installation's platform domains is invalid-input too, with the domain named. An application holds at most 64 of them.

A host another application holds is reference-held (409), and the detail names the holder only when the caller's own scope reaches it. Releasing a host this application does not hold is not-found, in the same words as one nobody claimed. Claiming for a blocked application is application-blocked; releasing stays open whatever state it is in.

--wildcard additionally requires a key whose scope reaches <name>-*, because the claim also decides what <name>-<env> answers on; a key that does not is auth-scope. Re-running add without the flag never takes the subdomains away, and remove drops the whole claim.

After a successful add, the CLI resolves the host and the application's platform hosts and says whether DNS already points here. It is never a refusal: the claim is already written and the command exits 0 whatever the answer. A host that resolves here is an acknowledgement on stdout; anything else is one scafo: warning: … line on stderr, naming a platform host to point a CNAME at. With --wildcard it asks a second time, under a label nothing is ever deployed at, and warns about what the ingress still needs for names it cannot approve a certificate for. SCAFO_SILENCE_WARNINGS=1 silences all of it.

list prints one host per line, sorted, each marked (+subdomains) when its claim covers them; scafo app show marks them the same way.

#scafo app lease

scafo app lease show [bucket flags] --name <name> [--env <name>] [--node <id>] [--json]
scafo app lease drop [bucket flags] --name <name> [--env <name>] --node <id> [--force] [--yes] [--dry-run] [--json]

Celld's own node leases of one application: look at them, and delete one the store will not read. Writes the bucket directly — fleets/<name>/nodes/<node>.json is a record Celld writes on its own schedule, no node holds this authority, and no node route offers it.

A Celld process must read or create its node lease before it has any authority, and Scafo names that process after the node — the same name on every start, deliberately, so an acknowledged write survives a restart. So when a store holds a lease key it will list and HEAD but never GET, every restart of that node's process wedges on the same key, forever; the process's own log says refusing to install a lease over an unrecovered predecessor log. No amount of restarting is a way out, and the only thing that is, is deleting that one object. Scafo never does that on its own: this command is the operator's hands on that single deletion.

#What a reading is

Every lease is judged on three reads laid side by side — what a listing of the fleet's nodes/ prefix says about the key, what a HEAD of it says, and what a GET of it says — and none of them may fail the reading: a store that raises on the very object being diagnosed is describing the problem, and that answer is printed as evidence.

A lease whose body names a different node than the key is filed under is reported as such: Celld's own reaper collects a lease only when the two agree, so that record is one nothing upstream will ever tidy away.

show prints one block per lease — the verdict and the key, then the three reads with the size, ETag and modification time each reported, then the sentence the verdict rests on — and a summary counting the verdicts. When one is unreadable, the summary ends with the exact drop command for the first of them. An application with no lease at all is one whose fleet never ran, or whose key prefix is not the one it was published under; the line says so.

#Dropping one

drop prints the reading first, because a lease is the one record whose deletion must be weighed against a process that may still be running, then asks:

Delete the unreadable node lease "fleets/shop/nodes/vps-a.json"? [y/N]

Only y or yes, in any casing, is consent. --yes answers ahead of the question. A dry run, and an absent key, ask nothing and delete nothing. A run whose input is not a terminal and that was not given --yes refuses with invalid-input, Nothing to answer with.

A held lease is refused with reference-held: an unexpired lease is one a running process believes is its own, and deleting it lets a second process take the node's cells while the first still serves them. Stop the process on that node, or wait for the lease to run out, and drop it then. --force deletes it anyway, and the question says so in as many words.

Exactly that key is deleted and never a prefix — the rest of the fleet's leases are other nodes' fences. The key is then read back rather than reported deleted: a store that answered a HEAD for an object it would not GET is not one to take a 204 from on trust. The closing line says either that the key is gone and the node's process writes its lease again the next time it starts, or that the store still answers for it, in which case take it up with the store before restarting the node.

#Only on verified Celld releases

Like scafo deployment prune, it reads inside Celld's own part of the bucket, so it runs only while a node is answering on a Celld release this build of scafo was verified against, and refuses with capability-missing otherwise — a --dry-run and a show included, with no flag that lifts it. The check is the one prune's release check describes.

#scafo deploy

scafo deploy [dir] [flags]

Deploy a built project directory to a node. Talks to the node API: POST /v1/applications/:name/deploys with the packed directory as the raw body, then polls the returned Location every second until the deploy settles in deployed or failed.

Without --name, the CLI reads name out of the project directory's wrangler.jsonc, then wrangler.json. It is read only and never written back, and the name the config carries reaches Celld exactly as written — --name and --env choose the Scafo application and edit nothing. A directory with no config, or one whose name is missing, blank or no application name at all, is refused with invalid-input, No application to deploy to, telling the caller to pass --name.

--replicas and --node-selector are sent only when given: a deploy that names neither leaves whatever the application already carries exactly as it is. Neither flag can lift a constraint — that is scafo app selector and scafo app replicas.

A node publishes one deploy at a time and queues the rest; a node with no room answers deploy-overloaded (429) with a retry-after. The command honours that number — backing off with jitter when the node named none, and never coming back sooner than it asked — until --queue-timeout has passed, printing one line when the waiting starts and one when it is admitted. The staged artifact is re-sent each time, never re-packed. A --queue-timeout that is not a non-negative number of seconds is invalid-input, Invalid queue timeout.

--var and --no-bundle edit the project's wrangler.jsonc or wrangler.json — the CLI reads it, applies the edit in memory, and packs the result into the archive; the file in the project directory is never written. A --var entry replaces the config's own vars entry of the same name and leaves every other entry as written; an empty value sets the variable to nothing; a name given twice is refused with invalid-input, as is a pair with no colon in it. Names are letters, digits and underscores, never beginning on a digit, and never __proto__, constructor or prototype. A config that already declares no_bundle: true needs no flag. With neither flag the archive carries the config byte for byte.

With no --node and no remote, the command refuses with invalid-input, No node to deploy to.

#scafo deployment

Manage what an application has published. One subcommand.

#scafo deployment prune

scafo deployment prune [bucket flags] --name <name> [--env <name>] [--keep] [--older-than] [--yes] [--dry-run]

Delete the old Celld deployments of one application. Writes the bucket directly — the deployments live in the application's Celld fleet, and no node holds this state.

#The two gates

Both are always weighed. A deployment goes only when it is past the count and older than the window; 0 lifts whichever gate it is given to, and neither can be lifted by leaving the flag out. A deployment scafo has no record of is weighed as the oldest thing in the fleet.

A pointer protects absolutely: what a pointer names is never a candidate, whatever the two gates say. A fleet whose fleet-wide pointer is missing or unreadable is refused outright with store-nonconforming rather than pruned against no protection at all.

#Asset blobs

Deployments share content-addressed asset blobs under the application's deploy-blobs/ prefix. After the deployments are weighed — and measured against the set that stays, not the one that goes — a blob no kept deployment's assets.json references is collected, once it is older than the same --older-than window. A blob whose age the store did not report is treated as too young to touch.

An assets.json that cannot be read, is not an object, has no entries, or names an unusable digest refuses the whole plan with store-nonconforming: scafo will not delete a blob beside a deployment whose references it cannot read.

#Container images

The container images Celld saved for the application's container classes are shared the same way, one <content key>.tar per image under deploy/images/. They are collected by the same rule, after the blobs: an image that neither containers[].image nor fence_image of any kept deployment's manifest.json names is deleted once it is older than the --older-than window. A deployment with no container names none, and neither does a version directory with no manifest yet.

A manifest whose containers is not a list, or whose image reference is not one Celld writes — celld-image: followed by a lowercase hexadecimal content key — refuses the whole plan with store-nonconforming: scafo will not delete an image beside a deployment whose references it cannot read. Anything under deploy/images/ that is not a <content key>.tar is left where it is.

#What it never touches

Prune weighs only what Celld wrote as a deployment: deploy/<script>/<version>/, with a script name Celld would have accepted and a hexadecimal version id. Anything else beneath deploy/ is left where it is, and two keyspaces are skipped by prefix rather than by the look of their names:

#Asking, and the answers

A real run prints the plan — one line per deployment, then the blobs, then the images — and then asks:

Delete 3 deployments (41 objects), 12 asset blobs and 2 container images of "shop"? [y/N]

Only y or yes, in any casing, is consent. --yes answers ahead of the question. A dry run and an empty plan ask nothing. A run whose input is not a terminal and that was not given --yes refuses with invalid-input, Nothing to answer with, rather than taking silence for consent.

Deletion order is the record before its objects, then the blobs, and the images last. The pointers are re-read before every deployment's deletion: a pointer that has moved onto a selected deployment refuses the run with cas-conflict, Deployment is in use again, and nothing of that deployment is deleted — plan the prune again.

#Verified Celld releases only

Prune reads and deletes inside Celld's own part of the bucket, in formats Celld owns and changes between releases. It therefore plans nothing — a --dry-run included — unless two checks hold, and there is no flag that lifts either:

Both are capability-missing: the detail names what was found, what this build is verified against, and that nothing was planned or deleted. A newer scafo, verified against that release, is what lifts it. A version directory with no manifest.json is a deploy in flight — Celld writes the manifest after the files — and is weighed by the age window like anything else.

#scafo trust

Manage which CI issuers may deploy an application. Writes the bucket directly, because a trust policy is usually set up before there is a node to ask — a policy may exist before its application does, and the first deploy creates the application under the name it names.

All subcommands take the bucket flags and name their target with --name and --env; --name is required.

#scafo metrics

scafo metrics [bucket flags] [--name] [--env] [--since] [--json]

What the fleet served, per application. Read straight out of the bucket: no node is asked and none has to be up.

The snapshots are monotonic totals per node, so a window is a subtraction. Three distinct silences are reported distinctly: nothing was ever written, something was written outside the window, or the nodes observe themselves and count no requests.

#scafo traces

scafo traces [bucket flags] [--name] [--env] [--since] [--limit] [--all] [--json]

What the nodes did, in order. Read straight out of the bucket.

Reconcile-pass events are held back by default so they cannot fill the window; how many were held back is always said.

#scafo wg

Set up and refresh this node's WireGuard tunnel. Reads and writes the bucket (publishes this node's public half, reads every peer's) and writes local files. It never brings the interface up: run wg-quick yourself.

Both subcommands take the same arguments.

With --stdout the configuration is the only thing on stdout; everything else goes to stderr, so --stdout > wg0.conf captures a file wg-quick can parse. Without it, the file is written owner-readable inside the state directory and the command prints the wg-quick up line to run.

A node whose transport is not wireguard is refused with invalid-input, This node runs no WireGuard tunnel.

#Environment variables read by the CLI

Configuration variables (SCAFO_S3_*, SCAFO_LISTEN, …) are documented at /config.