fleet reference

fleet (agentpod-fleet) acts on a fleet as a principal — a person or an agent — from a laptop, CI or an agent’s own workspace. It never uses a node’s credential; acting as a machine is apn’s job. For the reasoning behind the split, see apn and fleet.

This page is generated from the binary’s own command table and source, and a test fails when a verb or flag exists without an entry here. Unless a command says otherwise, every verb that talks to the hub prints the hub’s JSON response unchanged on stdout: it is the hub’s shape, not a summary of it, so scripts and agents can depend on it.

Commands

Signing in

Command	What it does
fleet login	Sign in once; this machine keeps a device credential.
fleet whoami	Who the token says you are, read locally.
fleet logout	Forget this machine’s token and device credential.
fleet devices	Where this machine’s device credentials are listed.

Reading the fleet

Command	What it does
fleet agents	The agents this token may dispatch.
fleet stats	Fleet totals.
fleet activity	Recent activity across your stations.

Nodes

Command	What it does
fleet nodes	The fleet’s nodes, with versions.
fleet invite	Mint the token a machine presents to apn enroll.
fleet runtimes	The substrate nodes run on: list, providers, create, start, stop, rm.

Stations

Command	What it does
fleet stations	Detect, adopt and unadopt stations; grant one push or forge API access.
fleet station	One station: lifecycle, cleanup, changeset, files.
fleet staff	Put an agent in a station, or take it out.
fleet config	Declare what a harness setting should be, and see what it is.
fleet mcp-proxy	Which stations each node’s loopback MCP proxy serves, and their secrets.

Skills and plugins

Command	What it does
fleet skills	Skill artifacts, releases, cohorts, canaries and placement.
fleet plugins	Review and apply harness plugin changes on a station.

Administration

Command	What it does
fleet settings	Hub-wide settings: signup, transcription, speech.
fleet bridge	The board roster: which agent claims from which board.
fleet principals	Identities, service principals and their credentials.
fleet grants	Dispatch authority, as a document (older hubs).
fleet users	People: list, show, ban, unban, role (older hubs).

This binary

Command	What it does
fleet update	Replace this binary with the newest release.
fleet skill	Print the skill that ships inside this binary.
fleet version	Print the version and platform.
fleet help	Print the verb list and how credentials work.

Environment

Variable	Meaning
$AGENTPOD_HUB	Hub base URL. Else the hub the stored login (token.json) was made against, else https://hub.agentpod.dev. Never taken from a node’s config.
$AGENTPOD_TOKEN	A principal’s token to use instead of the stored credential. Checked first; nothing is stored. When it has expired, commands say so rather than falling back.
$AGENTPOD_DEVICE_NAME	What fleet login names this machine in the device list. Default: the hostname.
$AGENTPOD_LOGIN_TIMEOUT	How long the older hub sign-in waits for the browser, as a Go duration (90s, 10m). Default 5m.
$BROWSER	The command fleet login opens the sign-in page with (it may carry arguments). none opens nothing; the URL is always printed.

Exit status

Unless a command says otherwise:

• 0 — the hub accepted the request.
• 1 — no usable credential, the hub could not be reached, or the hub refused or failed the request. Its status and body go to stderr: 401 means sign in again, 403 means this principal may not.
• 2 — a usage error: an unknown verb, or a missing flag or argument. Nothing was sent.

Credentials

fleet resolves a token in this order: $AGENTPOD_TOKEN; a cached token that has not expired; the stored device credential, exchanged for a fresh five-minute token. With none of those it prints how to sign in and exits 1. The files live under your user config directory (~/.config/agentpod/ on Linux, ~/Library/Application Support/agentpod/ on macOS): token.json and device.json. A device credential is only ever exchanged with the hub and account service that issued it.

Each command below says what it needs. The hub decides; fleet performs no permission check of its own and prints the hub’s refusal as it came.

fleet login

Sign in once; this machine keeps a device credential.

fleet login

Asks the hub how it signs people in. A current hub names its account service, and login runs that service’s device flow: it prints a page and a code, opens the page if it can, and waits while you confirm the code in a browser — any browser, so it works over SSH. Approval stores a long-lived device credential for this machine and a first five-minute token. Every later command exchanges the device credential for a fresh token, so the browser opens once, not once per lapse.

Against an older hub that issues its own tokens, login instead opens the hub’s sign-in page and receives the result on a local 127.0.0.1 callback (authorization code with PKCE), then registers this machine as a device at the hub. $AGENTPOD_LOGIN_TIMEOUT bounds that wait.

fleet login -h prints fleet help and opens nothing.

Needs: Nothing beforehand: this is how you get a credential. The sign-in itself is the account service’s.

Exit status: 0 once signed in. 1 when the hub or account service cannot be reached, the code was denied or expired, or a credential could not be stored.

fleet login
BROWSER=none fleet login   # on a server: print the page, open nothing

fleet whoami

Who the token says you are, read locally.

fleet whoami [--json]

Reads the token’s own claims — principal, kind, expiry — plus the hub it is for and where the token came from. It does not ask the hub, which is the point: it separates “not signed in” from “signed in, not permitted”. A 403 from another verb means the second; this answers the first.

Flag	Type	Default	Meaning
--json	bool	false	Print principal, kind, source, hub and expires as JSON.

Needs: Any token. It may still have to be resolved, which can exchange the device credential.

fleet whoami
fleet whoami --json | jq -r .principal

fleet logout

Forget this machine’s token and device credential.

fleet logout

Deletes both stored files. With a device credential from an account service, signing out is local only: the service owns the credential, so logout prints where to revoke it (its Devices page) and never sends it to the hub. With a credential an older hub issued, it first asks that hub to revoke it, and still signs out locally if the hub cannot be reached.

Needs: Nothing.

Exit status: 0 once both files are gone. 1 if a file could not be removed.

fleet logout

fleet devices

Where this machine’s device credentials are listed.

fleet devices

With a device credential from an account service, prints where the devices that may act as you are listed — the account service’s Devices page — and sends nothing to the hub. With a credential from an older hub, prints that hub’s list. With no device credential at all (a token in $AGENTPOD_TOKEN, say) it asks the hub, and a current hub answers 410, which exits 1.

Subcommands: revoke.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet devices

fleet devices revoke

Revoke one device credential (older hubs).

fleet devices revoke DEVICE_ID

With a device credential from an account service, revoking happens there: this prints its Devices page and exits 1, because nothing was revoked. Against an older hub it revokes one of your own devices; one that is not yours and one that does not exist are the same 404.

Argument	Meaning
DEVICE_ID	the device’s id, as fleet devices lists it

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

Exit status: 0 when revoked. 1 when the device is managed by an account service, or the hub refused. 2 without a DEVICE_ID.

fleet devices revoke dev_0123456789abcdef0123

fleet agents

The agents this token may dispatch.

fleet agents

Not every agent in the fleet: the ones the token’s signed grant lets it dispatch. The hub reads that from the token itself. Nothing granted is an empty list, not an error.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet agents | jq '.[].name'

fleet stats

Fleet totals.

fleet stats

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet stats

fleet activity

Recent activity across your stations.

fleet activity

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet activity

fleet nodes

The fleet’s nodes, with versions.

fleet nodes

Subcommands: update, telemetry, rm.

fleet nodes -h prints:

Usage: fleet nodes [update|telemetry|rm]

  fleet nodes                               the fleet's nodes, with versions
  fleet nodes update [--node NAME|ID …] [--force]
  fleet nodes rm NAME|ID [--force]          remove a retired machine from the fleet
  fleet nodes telemetry                     each node's OpenTelemetry setting
  fleet nodes telemetry [--node NAME|ID …] --endpoint <url> | --off

update asks the hub to roll the newest release to your nodes, one at a time,
and prints what happened to each. With --node it touches only those nodes
(repeatable; a name or an ID from `fleet nodes`). --force re-applies the current
release to a node that already has it — the escape hatch for a corrupt binary.

rm removes an enrolled node: its stations are unregistered and its credential is
revoked, so the machine cannot reconnect; to rejoin it needs a fresh
`fleet invite` token. A connected node is refused unless --force, which
disconnects it. A provisioned runtime's node is removed with `fleet runtimes rm`.

Only the node-agent restarts; the harnesses it serves keep running. The exit
status is 1 if any node was asked and did not update.

telemetry (admin role required) reads or sets the OTLP endpoint each node-agent
exports traces to, with no SSH. Without flags it lists the setting per node
(offline nodes are shown and do not fail the exit status). --endpoint takes an
http or https URL; --off disables export. A node restarts itself only if its
setting changed. A node too old to know the verb says "unsupported" until
`fleet nodes update`. The exit status is 1 if any node failed, was
unsupported, or (when setting) was offline and so did not apply the change.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet nodes

fleet nodes update

Roll the newest release to every node, or to --node ones.

fleet nodes update [--node NAME|ID ...] [--force]

The hub updates one node at a time, in name order, waits for each to answer, and skips nodes whose binary comes from an image. Only the node agent restarts; the harnesses it serves keep running. Names are resolved to ids before anything is sent, and an unknown name updates nothing. Waits up to 15 minutes for the whole rollout.

Flag	Type	Default	Meaning
--node NAME|ID	string	—	Node name or ID (repeatable).
--force	bool	false	Re-apply the current release.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

Exit status: 0 when every node asked updated. 1 if any did not (the per-node results are printed first). 2 for an unknown --node name or a stray argument.

fleet nodes update
fleet nodes update --node build-01 --node build-02

fleet nodes telemetry

Read or set each node’s OpenTelemetry endpoint, with no SSH.

fleet nodes telemetry [--node NAME|ID ...] [--endpoint URL | --off]

Without --endpoint or --off, lists one line per node: name, status, the configured endpoint, the one it is running with when they differ, and the state of its service unit. With one of them, sets it on every node, or only the --node ones; a node restarts itself only if its setting changed. A node too old to know the verb reports unsupported until fleet nodes update. On the node itself this is apn telemetry.

Flag	Type	Default	Meaning
--node NAME|ID	string	—	Node name or ID; needs --endpoint or --off. Repeatable.
--endpoint URL	string	—	OTLP/HTTP endpoint URL (http or https).
--off	bool	false	Disable telemetry export.

fleet nodes telemetry -h prints:

Usage: fleet nodes telemetry [--node NAME|ID …] [--endpoint <url> | --off]

With no flags, lists each node's telemetry setting. With --endpoint <url> (http
or https) or --off, sets it on every node, or only the --node ones. Admin role
required. Exit 1 if any node failed, was unsupported, or (when setting) offline.

Needs: A workspace admin’s token. Anyone else is refused with 403.

Exit status: 0 when every node reported (or applied) the setting. 1 if any failed or was unsupported, or — when setting — was offline. 2 for --endpoint with --off, --node alone, or an invalid URL.

fleet nodes telemetry
fleet nodes telemetry --endpoint https://otel.example.com:4318
fleet nodes telemetry --node build-01 --off

fleet nodes rm

Remove a retired machine from the fleet.

fleet nodes rm NAME|ID [--force]

Unregisters every station on the node, the way fleet stations unadopt does, and revokes the node’s credential: a machine that dials back is refused, and rejoining takes a fresh fleet invite token. Workspace files, agent identities and Matrix rooms are kept. A connected node is refused unless --force, which disconnects it. A provisioned runtime’s node is refused with the fleet runtimes rm that removes both, and a node with a bridge-roster row on one of its stations is refused until fleet bridge rm removes the row. A name is resolved from fleet nodes; anything else is sent as an id, so a node that is not there, or not yours, is the hub’s 404.

Argument	Meaning
`NAME	ID`

Flag	Type	Default	Meaning
--force	bool	false	Disconnect and remove a node that is connected.

fleet nodes rm -h prints:

Usage: fleet nodes rm NAME|ID [--force]

Removes an enrolled node from the fleet. Its stations are unregistered (as
`fleet stations unadopt` would), and its credential is revoked, so the machine
cannot reconnect; to rejoin it must be enrolled again with a fresh
`fleet invite` token. Workspace files on the machine are not touched, and the
node-agent keeps running until it is uninstalled there.

A connected node is refused unless --force, which disconnects it. A provisioned
runtime's node is refused: `fleet runtimes rm` removes the runtime and its node.

Needs: The node’s owner. Where the workspace enforces who may grow the fleet, also a workspace admin — the same authority fleet invite needs.

Exit status: 0 when the node was removed. 1 when the hub refused (the reason is printed; for a connected node, with the --force command) or answered 404. 2 without exactly one node.

fleet nodes rm build-01
fleet nodes rm build-01 --force

fleet invite

Mint the token a machine presents to apn enroll.

fleet invite [--label TEXT] [--ttl-minutes N]

Creates no node: it authorises one to appear. An unredeemed invitation looks exactly like no invitation in fleet nodes. The response carries the one-time token; hand it to apn enroll --token.

Flag	Type	Default	Meaning
--label TEXT	string	—	What this token is for, recorded with it.
--ttl-minutes N	int	0	Minutes until it expires (hub default when unset).

fleet invite -h prints:

usage:
  fleet invite [--label TEXT] [--ttl-minutes N]

Needs: A person’s token. When the hub enforces dispatch grants, a workspace admin’s.

fleet invite --label "build runner" --ttl-minutes 30

fleet runtimes

The substrate nodes run on: list, providers, create, start, stop, rm.

fleet runtimes <list|providers|create|start|stop|rm>

The hub treats a runtime’s state as evidence, not as a request’s outcome: stop writes stopping, and only the provider reporting the container down writes stopped. A stop that returns cleanly means “asked”; read the state afterwards.

Subcommands: list, providers, create, start, stop, rm.

fleet runtimes -h prints:

usage:
  fleet runtimes list
  fleet runtimes providers
  fleet runtimes create --file PATH|-
  fleet runtimes start ID
  fleet runtimes stop ID
  fleet runtimes rm ID

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

Exit status: As below for each verb; with no verb, prints the usage and exits 2.

fleet runtimes list

fleet runtimes list

Every runtime.

fleet runtimes list

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet runtimes list

fleet runtimes providers

The providers this hub can provision on.

fleet runtimes providers

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet runtimes providers

fleet runtimes create

Provision a runtime from a request document.

fleet runtimes create --file PATH|-

The request is a JSON document the hub validates; take its shape from fleet runtimes providers.

Flag	Type	Default	Meaning
--file PATH|-	string	—	Provision request, or - for stdin. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet runtimes create --file runtime.json

fleet runtimes start

Ask a runtime to start.

fleet runtimes start ID

Argument	Meaning
ID	the runtime’s id

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet runtimes start rt_123

fleet runtimes stop

Ask a runtime to stop; its state says when it has.

fleet runtimes stop ID

Argument	Meaning
ID	the runtime’s id

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet runtimes stop rt_123

fleet runtimes rm

Delete a runtime.

fleet runtimes rm ID

Argument	Meaning
ID	the runtime’s id

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet runtimes rm rt_123

fleet stations

Detect, adopt and unadopt stations; grant one push or forge API access.

fleet stations <verb> [flags]

Acts on the fleet’s shape. For one station’s contents — lifecycle, disk, diffs, files — see fleet station. Every verb here parses the same flags; each lists the ones it reads.

Subcommands: detected, list, adopt, unadopt, git-identity, grant-push, revoke-push, forge-api.

fleet stations -h prints:

Usage: fleet stations <verb>

  fleet stations detected --node NODE_ID     what the node reports right now
  fleet stations list --node NODE_ID         adopted stations, with their IDs
  fleet stations adopt --node NODE_ID --key KEY [--key KEY …]
  fleet stations unadopt --station STATION_ID

  fleet stations git-identity --station STATION_ID   what it can push to forge as
  fleet stations grant-push   --station STATION_ID   give it a forge push key
  fleet stations revoke-push  --station STATION_ID   take that key away

  fleet stations forge-api <verb> --station STATION_ID …   forge API access through the
                                                     station's broker (operator only;
                                                     see fleet stations forge-api --help)

A detected station is not an agent until it is adopted. Adopting re-detects on
the node first, so a key that has gone away is not adopted from a stale list.

Push access is granted per station and never by adopting one: most stations
never touch git, and a forge key for every station is an account nobody uses
and a key nobody revokes. The keypair is generated ON THE NODE and the private
half never leaves it — grant-push asks for the public half and registers that.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

Exit status: As below for each verb; with no verb, prints the usage and exits 0.

fleet stations list --node node_123

fleet stations detected

What the node reports right now, adopted or not.

fleet stations detected --node NODE_ID

Flag	Type	Default	Meaning
--node NODE_ID	string	—	Node ID. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet stations detected --node node_123

fleet stations list

Adopted stations on a node, with the ids other verbs need.

fleet stations list --node NODE_ID

Flag	Type	Default	Meaning
--node NODE_ID	string	—	Node ID. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet stations list --node node_123

fleet stations adopt

Make detected stations into agents.

fleet stations adopt --node NODE_ID --key KEY [--key KEY ...]

Re-detects on the node first, so a key that has gone away is not adopted from a stale list. Several keys are one reviewed call.

Flag	Type	Default	Meaning
--node NODE_ID	string	—	Node ID. Required.
--key KEY	string	—	Station key to adopt, as fleet stations detected reports it. Required. Repeatable.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet stations adopt --node node_123 --key hermes:default

fleet stations unadopt

Stop treating a station as an agent.

fleet stations unadopt --station STATION_ID

Flag	Type	Default	Meaning
--station STATION_ID	string	—	Station ID. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet stations unadopt --station stn_123

fleet stations git-identity

What a station can push to the forge as.

fleet stations git-identity --station STATION_ID

Shows the forge account, its key id, and authorName/authorEmail — who the station’s commits are by (GIT_AUTHOR_* and GIT_COMMITTER_* in its harness and terminal environment). The author is null for an identity provisioned before authors existed, until its node next connects.

Flag	Type	Default	Meaning
--station STATION_ID	string	—	Station ID. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet stations git-identity --station stn_123

fleet stations grant-push

Give a station a forge push key.

fleet stations grant-push --station STATION_ID

The keypair is generated on the node and the private half never leaves it; the hub registers the public half for the station’s occupying agent. Push access is never granted by adopting a station. A hub with no forge configured answers 503.

Flag	Type	Default	Meaning
--station STATION_ID	string	—	Station ID. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet stations grant-push --station stn_123

fleet stations revoke-push

Take a station’s forge push key away.

fleet stations revoke-push --station STATION_ID

Flag	Type	Default	Meaning
--station STATION_ID	string	—	Station ID. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet stations revoke-push --station stn_123

fleet stations forge-api

Give a station’s agent scoped forge API access through its broker (operator only).

fleet stations forge-api <verb> --station STATION_ID [flags]

The station’s broker (stk) holds the credential and injects it into requests the policy allows; the agent never sees it. Every verb but list is an operator action: the hub operator seat AND the control pair’s reach over the station’s agent (the owner alone is refused with 403). Three credential modes: minted (the hub mints a scoped token on its configured forge for the occupying agent), supplied (an operator-provided token) and app (a GitHub App’s id, installation id and private key). A supplied or app credential is read from stdin, sealed on this machine to the station’s handover key (fetched from the hub once, before anything is created), and only the sealed envelope is sent. There is no flag that takes a credential. Output is the hub’s sanitised grant view; it never contains a token. See Stations for the limits.

Subcommands: list, grant, verify, rotate, secret, policy, revoke, confirm-revoked.

fleet stations forge-api -h prints:

Usage: fleet stations forge-api <verb> --station STATION_ID [flags]

  list            --station ID                       grants: state, mode, account, isolation
  grant           --station ID --provider P --instance https://… --repo owner/name …
                  [--preset read|issues|pull-requests|maintain|none]
                  [--rule 'allow: METHOD /path']… [--rules-file FILE]
                  [--mode minted|app|supplied] [--expect-login LOGIN] [--allow-graphql]
                  [--acknowledge-same-user]
  verify          --station ID --grant GRANT_ID      re-check the credential on the node
  rotate          --station ID --grant GRANT_ID      minted: a new token, the old one revoked
  secret          --station ID --grant GRANT_ID      re-supply a credential (stdin); add --mode app for an App
  policy          --station ID --grant GRANT_ID --preset P [--rule …]… [--rules-file FILE] [--allow-graphql]
                  [--acknowledge-same-user]
                  replaces the whole policy: omitting --allow-graphql turns GraphQL OFF
  revoke          --station ID --grant GRANT_ID
  confirm-revoked --station ID --grant GRANT_ID      supplied: you revoked it at the provider

Granting an agent forge API access is an OPERATOR action (hub operator seat and the
control pair's reach). An agent must not try to grant itself access.

A supplied or app credential is read from STDIN, never from a flag: a token for
--mode supplied; for --mode app the lines app_id=…, installation_id=… and
private_key=… (the PEM may continue over the following lines). The CLI fetches
the station's handover key and seals the credential to it on this machine; the
hub only ever sees the sealed envelope. A minted grant needs no credential.

A write grant (any preset except read, or an allow rule for a write method) on a
station whose broker runs in same-user mode is refused until the operator passes
--acknowledge-same-user: the agent could then read the broker's store. Today every
station reports same-user. The hub records who acknowledged.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

Exit status: 0 on success; 2 when a flag or the stdin credential is refused before any request; 1 when the hub refuses (its status and fixed message are printed, never the request).

fleet stations forge-api list --station stn_123

fleet stations forge-api list

A station’s forge API grants: state, mode, account, isolation.

fleet stations forge-api list --station STATION_ID [--json]

Prints only known fields (id, state, mode, account, isolation, provider, instance, preset, repositories); --json prints the same fields as JSON. Readable by the station’s owner as well as an operator.

Flag	Type	Default	Meaning
--station STATION_ID	string	—	Station ID. Required.
--json	bool	false	List: print the same fields as JSON.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet stations forge-api list --station stn_123

fleet stations forge-api grant

Grant a station API access to named repositories on one forge.

fleet stations forge-api grant --station STATION_ID --provider forgejo|github|gitea|bitbucket \
    --instance https://HOST --repo OWNER/NAME [--repo …] [--preset read|issues|pull-requests|maintain|none] \
    [--rule 'allow: METHOD /path']… [--rules-file FILE] [--mode minted|app|supplied] [--expect-login LOGIN] [--allow-graphql] \
    [--acknowledge-same-user]

Refused before any request: no --repo, an --instance that is not https, an unknown provider, preset or mode, a malformed --rule, or --mode supplied|app without --expect-login (for an app, its slug). --rule is allow: METHOD /path or deny: METHOD /path; a rule with a when condition goes in --rules-file, a JSON array of {allow|deny, when} objects. minted (the default) sends one request. supplied reads one token from stdin; app reads app_id=…, installation_id=… and private_key=… lines (the PEM may continue over the following lines). For those the CLI fetches the station’s key, seals, creates the grant, then posts the envelope; if that last step fails, re-send with secret. What the hub accepts today: Forgejo minted (the hub’s configured forge only) and supplied; GitHub app and supplied. Gitea and Bitbucket are refused until their adapters exist. A write grant (any preset except read, or an allow rule for a write method) on a station whose broker runs in same-user mode (today: every station) is refused (409 same-user-acknowledgement-required) unless the operator passes --acknowledge-same-user; the hub records who acknowledged. Agents must never pass it.

Flag	Type	Default	Meaning
--station STATION_ID	string	—	Station ID. Required.
--provider PROVIDER	string	—	Forgejo, github, gitea or bitbucket. Required.
--instance URL	string	—	The forge’s https origin. Required.
--repo OWNER/NAME	string	—	Owner/name (repeatable). Required.
--preset PRESET	string	read	Read, issues, pull-requests, maintain or none.
--rule RULE	string	—	‘allow: METHOD /path’ or ‘deny: METHOD /path’ (repeatable).
--rules-file FILE	string	—	A JSON array of rules ({allow|deny, when}), added after --rule.
--mode MODE	string	minted	Minted, app or supplied.
--expect-login LOGIN	string	—	The account the credential must belong to (app: the App’s slug).
--allow-graphql	bool	false	Let the station use the GraphQL endpoint.
--acknowledge-same-user	bool	false	Operator only: accept a write grant in same-user mode.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet stations forge-api grant --station stn_123 --provider forgejo --instance https://forge.example \
    --repo org/repo --preset issues
pbpaste | fleet stations forge-api grant --station stn_123 --provider github --instance https://github.com \
    --repo org/repo --mode supplied --expect-login octo-bot

fleet stations forge-api verify

Re-check a grant’s credential on the node.

fleet stations forge-api verify --station STATION_ID --grant GRANT_ID

Flag	Type	Default	Meaning
--station STATION_ID	string	—	Station ID. Required.
--grant GRANT_ID	string	—	Grant ID, as fleet stations forge-api list shows it. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet stations forge-api verify --station stn_123 --grant fag_123

fleet stations forge-api rotate

Mint a minted grant a new token; the previous one is revoked.

fleet stations forge-api rotate --station STATION_ID --grant GRANT_ID

Flag	Type	Default	Meaning
--station STATION_ID	string	—	Station ID. Required.
--grant GRANT_ID	string	—	Grant ID, as fleet stations forge-api list shows it. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet stations forge-api rotate --station stn_123 --grant fag_123

fleet stations forge-api secret

Re-supply a supplied or app grant’s credential from stdin, sealed.

fleet stations forge-api secret --station STATION_ID --grant GRANT_ID [--mode app]

Reads a token from stdin, or with --mode app the App’s three field lines; fetches the station’s key once, seals, and posts only the envelope.

Flag	Type	Default	Meaning
--station STATION_ID	string	—	Station ID. Required.
--grant GRANT_ID	string	—	Grant ID, as fleet stations forge-api list shows it. Required.
--mode MODE	string	minted	App to read an App’s fields instead of a token.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

pbpaste | fleet stations forge-api secret --station stn_123 --grant fag_123

fleet stations forge-api policy

Replace a grant’s preset, rules and GraphQL setting.

fleet stations forge-api policy --station STATION_ID --grant GRANT_ID --preset PRESET [--rule RULE]… [--rules-file FILE] [--allow-graphql] [--acknowledge-same-user]

Replaces, not merges: rules not given are removed, and GraphQL is off unless --allow-graphql is given. Moving a same-user grant to a write policy needs --acknowledge-same-user (operator only).

Flag	Type	Default	Meaning
--station STATION_ID	string	—	Station ID. Required.
--grant GRANT_ID	string	—	Grant ID, as fleet stations forge-api list shows it. Required.
--preset PRESET	string	—	Read, issues, pull-requests, maintain or none. Required.
--rule RULE	string	—	‘allow: METHOD /path’ or ‘deny: METHOD /path’ (repeatable).
--rules-file FILE	string	—	A JSON array of rules ({allow|deny, when}), added after --rule.
--allow-graphql	bool	false	Let the station use the GraphQL endpoint.
--acknowledge-same-user	bool	false	Operator only: accept a write policy in same-user mode.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet stations forge-api policy --station stn_123 --grant fag_123 --preset issues --rule 'deny: DELETE /repos/**'

fleet stations forge-api revoke

Remove a grant from the station (and, when minted, revoke the token at the forge).

fleet stations forge-api revoke --station STATION_ID --grant GRANT_ID

agentpod cannot revoke a supplied token at its provider: revoke it there, then run confirm-revoked.

Flag	Type	Default	Meaning
--station STATION_ID	string	—	Station ID. Required.
--grant GRANT_ID	string	—	Grant ID, as fleet stations forge-api list shows it. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet stations forge-api revoke --station stn_123 --grant fag_123

fleet stations forge-api confirm-revoked

Record that you revoked a supplied credential at its provider.

fleet stations forge-api confirm-revoked --station STATION_ID --grant GRANT_ID

Flag	Type	Default	Meaning
--station STATION_ID	string	—	Station ID. Required.
--grant GRANT_ID	string	—	Grant ID, as fleet stations forge-api list shows it. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet stations forge-api confirm-revoked --station stn_123 --grant fag_123

fleet station

One station: lifecycle, cleanup, changeset, files.

fleet station <lifecycle|cleanup|changeset|fs> ...

The same operations as the console’s panels, each gated on a capability the station declares — see What you can do to a station. Every verb is a round trip to the node through the hub, so an offline node answers 409. Nothing is retried: whether a write that may have landed should be repeated is the caller’s decision.

Subcommands: lifecycle, cleanup, changeset, fs.

fleet station -h prints:

usage:
  fleet station lifecycle --station ID --action start|stop|restart
  fleet station cleanup plan --station ID
  fleet station cleanup apply --station ID --path P [--path P …]
  fleet station changeset status --station ID [--base REF]
  fleet station changeset diff --station ID --side uncommitted|committed [--path P] [--base REF]
  fleet station fs write  --station ID --path P --from FILE|- [--base64] [--backup]
  fleet station fs mkdir  --station ID --path P
  fleet station fs move   --station ID --from P --to P
  fleet station fs delete --station ID --path P [--recursive]

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

Exit status: As below for each verb; with no verb, prints the usage and exits 2.

fleet station lifecycle --station stn_123 --action restart

fleet station lifecycle

Start, stop or restart a station’s harness.

fleet station lifecycle --station ID --action start|stop|restart

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.
--action start|stop|restart	string	—	Start, stop or restart. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet station lifecycle --station stn_123 --action restart

fleet station cleanup

Find and reclaim disk a station no longer needs.

fleet station cleanup <plan|apply> --station ID ...

Subcommands: plan, apply.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet station cleanup plan --station stn_123

fleet station cleanup plan

List what could be reclaimed, and how much.

fleet station cleanup plan --station ID

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet station cleanup plan --station stn_123

fleet station cleanup apply

Reclaim the named paths.

fleet station cleanup apply --station ID --path P [--path P ...]

At least one --path is required: an empty apply is far more likely a shell glob that matched nothing than a deliberate no-op.

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.
--path P	string	—	A path to reclaim (repeatable). Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet station cleanup apply --station stn_123 --path .cache/pip

fleet station changeset

What the agent changed in the station’s git checkout.

fleet station changeset <status|diff> --station ID ...

Subcommands: status, diff.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet station changeset status --station stn_123

fleet station changeset status

Changed files, committed and uncommitted.

fleet station changeset status --station ID [--base REF]

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.
--base REF	string	—	Ref to compare against.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet station changeset status --station stn_123 --base origin/main

fleet station changeset diff

The diff itself, one side at a time.

fleet station changeset diff --station ID --side uncommitted|committed [--path P] [--base REF]

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.
--side uncommitted|committed	string	—	Uncommitted or committed. Required.
--path P	string	—	Limit the diff to one path.
--base REF	string	—	Ref to compare against.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet station changeset diff --station stn_123 --side uncommitted --path README.md

fleet station fs

Write, create, move and delete files in a station.

fleet station fs <write|mkdir|move|delete> --station ID ...

Subcommands: write, mkdir, move, delete.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet station fs mkdir --station stn_123 --path notes

fleet station fs write

Write a local file (or stdin) to a path in the station.

fleet station fs write --station ID --path P --from FILE|- [--base64] [--backup]

Sent as UTF-8 by default. A file that is not valid UTF-8 is refused rather than corrupted; send it with --base64.

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.
--path P	string	—	Path on the station. Required.
--from FILE|-	string	—	Local file to send, or - for stdin. Required.
--base64	bool	false	Send the file as base64 rather than utf8.
--backup	bool	false	Keep a backup of what was overwritten.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet station fs write --station stn_123 --path notes/todo.md --from todo.md
echo hello | fleet station fs write --station stn_123 --path hello.txt --from -

fleet station fs mkdir

Create a directory.

fleet station fs mkdir --station ID --path P

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.
--path P	string	—	Path on the station. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet station fs mkdir --station stn_123 --path notes

fleet station fs move

Move or rename a path.

fleet station fs move --station ID --from P --to P

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.
--from P	string	—	Source path on the station. Required.
--to P	string	—	Destination path (move). Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet station fs move --station stn_123 --from draft.md --to final.md

fleet station fs delete

Delete a file, or a directory with --recursive.

fleet station fs delete --station ID --path P [--recursive]

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.
--path P	string	—	Path on the station. Required.
--recursive	bool	false	Delete a directory and its contents.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet station fs delete --station stn_123 --path scratch --recursive

fleet staff

Put an agent in a station, or take it out.

fleet staff <options|create|assign|unassign>

Start with options: it says which harnesses, models and profiles this hub accepts, and every other verb here fails on a value it did not get from there.

Subcommands: options, create, assign, unassign.

fleet staff -h prints:

usage:
  fleet staff options
  fleet staff create --file PATH|-
  fleet staff assign --station ID --file PATH|-
  fleet staff unassign --station ID

Needs: A workspace admin’s token. Anyone else is refused with 403.

Exit status: As below for each verb; with no verb, prints the usage and exits 2.

fleet staff options

fleet staff options

The harnesses, models and profiles this hub accepts.

fleet staff options

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet staff options

fleet staff create

Create an agent from a definition document.

fleet staff create --file PATH|-

Flag	Type	Default	Meaning
--file PATH|-	string	—	Agent definition, or - for stdin. Required.

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet staff create --file agent.json

fleet staff assign

Put an agent in a station.

fleet staff assign --station ID --file PATH|-

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.
--file PATH|-	string	—	Assignment document, or - for stdin. Required.

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet staff assign --station stn_123 --file assignment.json

fleet staff unassign

Take the agent out of a station.

fleet staff unassign --station ID

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet staff unassign --station stn_123

fleet config

Declare what a harness setting should be, and see what it is.

fleet config <verb> ...

set records a declaration and writes nothing to a station; plan, inspect and apply are the reviewed trio that writes. See Declared harness settings.

Subcommands: settings, show, set, unset, drift, opt-out, opt-in, plan, inspect, apply.

fleet config -h prints:

usage:
  fleet config settings                                         every setting the fleet can declare
  fleet config show   [--node ID]                               the declarations themselves, as stored
  fleet config show   --station ID                              one station: declared vs observed, with state
  fleet config set    SETTING_ID --value V [--value V ...] [--station ID | --node ID]
  fleet config set    SETTING_ID --json  JSON          [--station ID | --node ID]
  fleet config unset  SETTING_ID [--station ID | --node ID]
  fleet config drift                                            every station whose value differs
  fleet config opt-out SETTING_ID [--station KEY | --node ID] [--reason TEXT]
  fleet config opt-in  SETTING_ID [--station KEY | --node ID]
  fleet config opt-out SETTING_ID [--station KEY | --node ID] --clear
  fleet config opt-out                                          what is exempt, and where
  fleet config plan    --station ID [--setting SETTING_ID]      narrow the plan to one setting
  fleet config inspect --station ID --operation ID              a plan already made, as it was reviewed
  fleet config apply   --station ID --operation ID --plan-digest SHA256

`set` records a DECLARATION; it does not write to a station. `apply` is the
verb that writes, and it refuses to run without --plan-digest: that digest
must be the one `plan` printed for this operation, so a human reviewed the
exact edit being written rather than whatever the current plan happens to
be by the time apply runs.

Only `show --station` and `drift` compare anything. Without --station, `show`
returns the declaration rows and contacts no station: no observed value, no
state. A fleet- or node-level declaration is one row that may apply to many
stations, so comparing it means naming which station you mean.

--station is accepted for any setting. A setting whose registered scope is
not `profile` is NOT refused here; it is stored, and reported `out-of-scope`
when the declaration is read back.

A single --value is always declared as a STRING. A setting whose value is a
list — every `additive-only` setting is one, a command allowlist being the
first — is declared either by repeating --value once per entry:

  fleet config set hermes.approvals.command_allowlist \
      --value "git status" --value "ls"

or with --json, which takes the value exactly as JSON and is the way to
declare a ONE-entry list, a number or a boolean:

  fleet config set hermes.approvals.command_allowlist --json '["git status"]'
  fleet config set hermes.approvals.timeout --json 900

--value and --json are mutually exclusive, and `set` needs one of them: a
declaration with no value is not a declaration. A list-valued setting given
a single --value is stored as the string it is, and every later plan for that
station is refused SHAPE_UNEXPECTED by the node, so the shape matters here
rather than at write time.

`opt-out` stops this system writing a setting; it does not change what is already in the file.
An exemption is not an undo — a station that was already drifted, or
already carries a value written before the exemption existed, stays
exactly as it is.

`opt-in` is not the same as `--clear`. `opt-in` records "this station is
NOT exempt", which overrides a node-level exemption for that one station.
`--clear` forgets the exemption row entirely, so the station falls back to
whatever the node says — if the node is exempt, the station is exempt
again too. Use `opt-in` to pin a station in despite its node; use --clear
to stop having an opinion at the station level at all.

A station-level row always beats a node-level one — `opt-in` at the
station overrides `opt-out` at the node, never the other way around.

--station names a station by its stationKey, not its row id: a stationKey
survives unadopt and re-adopt, so an exemption recorded against it still
applies after the station is re-adopted, which a row id would not.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

Exit status: As below for each verb; with no verb, prints the usage and exits 2.

fleet config settings

fleet config settings

Every setting the fleet can declare.

fleet config settings

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet config settings

fleet config show

The declarations as stored, or one station’s declared-against-observed.

fleet config show [--node ID]
fleet config show --station ID

Only --station contacts a station and reports observed values and state; without it this returns the declaration rows.

Flag	Type	Default	Meaning
--station ID	string	—	Station ID.
--node ID	string	—	Node ID.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet config show --station stn_123

fleet config set

Declare a setting’s value, fleet-wide or for a node or station.

fleet config set SETTING_ID --value V [--value V ...] [--station ID | --node ID]
fleet config set SETTING_ID --json JSON [--station ID | --node ID]

One --value declares a string; several declare a list of strings, in order. --json takes any JSON value, and is the only way to declare a one-entry list, a number or a boolean. Exactly one of them is required. With neither scope flag the declaration is fleet-wide.

Argument	Meaning
SETTING_ID	a setting from fleet config settings

Flag	Type	Default	Meaning
--value V	string	—	The declared value; repeat for a list.
--json JSON	string	—	The declared value, exactly as JSON.
--station ID	string	—	Station ID.
--node ID	string	—	Node ID.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet config set hermes.approvals.command_allowlist --value "git status" --value ls
fleet config set hermes.approvals.timeout --json 900 --node node_123

fleet config unset

Remove a declaration at one level.

fleet config unset SETTING_ID [--station ID | --node ID]

Argument	Meaning
SETTING_ID	the declared setting

Flag	Type	Default	Meaning
--station ID	string	—	Station ID.
--node ID	string	—	Node ID.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet config unset hermes.approvals.timeout --node node_123

fleet config drift

Every station whose value differs from its declaration.

fleet config drift

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet config drift

fleet config opt-out

Exempt a station or node from a setting, or list exemptions.

fleet config opt-out [--station KEY | --node ID]
fleet config opt-out SETTING_ID (--station KEY | --node ID) [--reason TEXT]
fleet config opt-out SETTING_ID (--station KEY | --node ID) --clear

Without a SETTING_ID, lists what is exempt and where. With one, records an exemption (exactly one of --station or --node); --clear forgets the row instead, so the station falls back to its node. An exemption stops this system writing the setting; it does not change what is already in the file.

Argument	Meaning
SETTING_ID	the setting to exempt; omit it to list

Flag	Type	Default	Meaning
--station KEY	string	—	Station key (survives unadopt/re-adopt; not a row id).
--node ID	string	—	Node ID.
--reason TEXT	string	—	Why this station or node is exempt.
--clear	bool	false	Forget the exemption row instead of recording one; the station then falls back to the node level.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet config opt-out hermes.approvals.timeout --station hermes:default --reason "tuned by hand"

fleet config opt-in

Record that a station or node is not exempt, overriding its node.

fleet config opt-in SETTING_ID (--station KEY | --node ID)

Not the same as opt-out --clear: this pins a station in despite a node-level exemption; a station-level row always beats a node-level one.

Argument	Meaning
SETTING_ID	the setting

Flag	Type	Default	Meaning
--station KEY	string	—	Station key (survives unadopt/re-adopt; not a row id).
--node ID	string	—	Node ID.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet config opt-in hermes.approvals.timeout --station hermes:default

fleet config plan

Derive the edit that would make a station match its declarations.

fleet config plan --station ID [--setting SETTING_ID]

Prints the plan with its operation id and digest. Without --setting it plans every setting declared for the station at any level.

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.
--setting SETTING_ID	string	—	Narrow the plan to one setting.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

Exit status: As above; also 1 when nothing is declared for the station.

fleet config plan --station stn_123

fleet config inspect

A plan already made, exactly as it was reviewed.

fleet config inspect --station ID --operation ID

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.
--operation ID	string	—	Operation ID. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet config inspect --station stn_123 --operation op_123

fleet config apply

Write a reviewed plan to the station.

fleet config apply --station ID --operation ID --plan-digest SHA256

Refuses to run without the digest plan printed, so what is written is exactly what a person reviewed, never a plan re-derived at apply time.

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.
--operation ID	string	—	Operation ID. Required.
--plan-digest SHA256	string	—	Reviewed plan digest. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet config apply --station stn_123 --operation op_123 --plan-digest 3f2a…

fleet mcp-proxy

Which stations each node’s loopback MCP proxy serves, and their secrets.

fleet mcp-proxy <list|enable|disable|rotate> ...

The proxy gives a station’s harness sessions the hub’s and SuperLibrary’s MCP tools as the station’s own agent, through a loopback URL and a per-station secret that never leave the node. A change is written to the node’s config (mcpProxy.stations) and applied without a restart; every change and rotation leaves an audit row per station. The hub records what was declared here; list compares it with what each node serves. With nothing declared, whatever the node’s config says stands, so a hand-edited config needs no migration. Needs a node at v0.1.96 or later; an older one answers unknown. The node side is apn mcp-proxy.

Subcommands: list, enable, disable, rotate.

fleet mcp-proxy -h prints:

usage:
  fleet mcp-proxy list [--node ID]                            every station: declared, served, state
  fleet mcp-proxy enable STATION_ID...                        serve these stations
  fleet mcp-proxy enable --all-eligible [--node ID]           serve every station whose harness can use it
  fleet mcp-proxy disable STATION_ID...                       stop serving these stations
  fleet mcp-proxy rotate STATION_ID... | --node ID            new secrets; sessions holding old ones are refused

The node's loopback MCP proxy gives a station's harness sessions the hub's and
SuperLibrary's MCP tools, as the station's own agent. Only Hermes, Claude Code,
Codex, opencode, Muse and Kilo stations can use it: OpenClaw's and Pi's ACP adapters take
no HTTP MCP servers in session/new, and enabling one is refused.

A change is written to the node's config and applied without a restart, and
leaves an audit row per station. A state of "drifted" means what was declared
here and what the node serves disagree — re-run enable or disable to settle it.
Secrets never leave the node.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

Exit status: As below for each verb; with no verb, prints the usage and exits 2.

fleet mcp-proxy list

fleet mcp-proxy list

Every station: eligible, declared, served, and its state.

fleet mcp-proxy list [--node ID]

state is on or off; drifted when the declaration and the node disagree (a hand edit, a reset config); ineffective when a station is served but its harness takes no HTTP MCP servers; unknown when the node could not be asked. unadoptedStations are ids the node’s config names that are not adopted stations of that node. drifted at the top counts all three kinds.

Flag	Type	Default	Meaning
--node ID	string	—	Only this node.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet mcp-proxy list --node node_123

fleet mcp-proxy enable

Serve the named stations, or every eligible one.

fleet mcp-proxy enable STATION_ID...
fleet mcp-proxy enable --all-eligible [--node ID]

Only Hermes, Claude Code, Codex, opencode, Muse and Kilo stations are eligible. Naming an OpenClaw or Pi station refuses the whole request (422) and changes nothing: their ACP adapters take no HTTP MCP servers in session/new. --all-eligible skips them and lists them under skipped. A station already served keeps its secret, so its open sessions keep working.

Argument	Meaning
STATION_ID	a station id from fleet stations; several may be named

Flag	Type	Default	Meaning
--all-eligible	bool	false	Every adopted station whose harness takes HTTP MCP servers (Hermes, Claude Code, Codex, opencode, Muse, Kilo).
--node ID	string	—	With --all-eligible: only this node’s stations.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

Exit status: 0 when every station is served; 1 otherwise — 404 an unknown station, 422 an ineligible one, 409 a node offline or too old, 502 a node that failed.

fleet mcp-proxy enable stn_123 stn_456
fleet mcp-proxy enable --all-eligible

fleet mcp-proxy disable

Stop serving the named stations.

fleet mcp-proxy disable STATION_ID...

Applied at once: the station’s next proxied request is refused, and its next session gets no proxied servers.

Argument	Meaning
STATION_ID	a station id; several may be named

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

Exit status: As enable.

fleet mcp-proxy disable stn_123

fleet mcp-proxy rotate

New secrets for the named stations, or every station a node serves.

fleet mcp-proxy rotate STATION_ID...
fleet mcp-proxy rotate --node ID

Secrets otherwise persist across node restarts, so a session kept open across one keeps working. Rotate when that is not wanted: a session holding an old secret is refused (401) from its next request, and new sessions get the new one. The secrets are never sent to the hub.

Argument	Meaning
STATION_ID	a served station’s id; several may be named

Flag	Type	Default	Meaning
--node ID	string	—	Every station this node’s proxy serves.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

Exit status: As enable; 409 also when the node’s proxy does not serve a named station.

fleet mcp-proxy rotate stn_123
fleet mcp-proxy rotate --node node_123

fleet skills

Skill artifacts, releases, cohorts, canaries and placement.

fleet skills <verb> ...

Every mutation prints the hub’s reviewed record; read it before the matching apply. No plan here ever turns into an implicit apply. The workflow is on Managed skills.

Subcommands: artifacts, artifact, releases, cohorts, upload, release, cohort, canary, station, native.

fleet skills -h prints:

Usage: fleet skills <verb>

  fleet skills artifacts
  fleet skills artifact delete --id ARTIFACT_ID
  fleet skills releases
  fleet skills cohorts
  fleet skills upload --harness H --profile P ARCHIVE.tgz
  fleet skills release import RELEASE.json
  fleet skills cohort create --release ID --digest SHA256 --station ID
  fleet skills canary plan --cohort ID --release ID --digest SHA256 --station ID
  fleet skills canary inspect --cohort ID --release ID --digest SHA256 --station ID --operation ID
  fleet skills canary apply --cohort ID --release ID --digest SHA256 --station ID --operation ID --plan-digest SHA256
  fleet skills station plan --station ID --artifact ARTIFACT_ID
  fleet skills station verify --station ID --profile PROFILE
  fleet skills station rollback-plan --station ID --profile PROFILE
  fleet skills station inspect --station ID --operation ID
  fleet skills station apply --station ID --operation ID --plan-digest SHA256
  fleet skills native plan --station ID --profile PROFILE --action activate|deactivate|rollback
  fleet skills native inspect --station ID --operation ID
  fleet skills native apply --station ID --operation ID --plan-digest SHA256
  fleet skills native verify --station ID --profile PROFILE

Every mutation returns the hub's reviewed record. Read that response before an
apply command; this CLI never turns a plan into an implicit apply.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

Exit status: As below for each verb; with no verb, prints the usage and exits 0.

fleet skills artifacts

fleet skills artifacts

Uploaded skill archives.

fleet skills artifacts

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet skills artifacts

fleet skills artifact

Act on one uploaded artifact.

fleet skills artifact delete --id ARTIFACT_ID

Subcommands: delete.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet skills artifact delete --id art_123

fleet skills artifact delete

Delete an uploaded artifact.

fleet skills artifact delete --id ARTIFACT_ID

Flag	Type	Default	Meaning
--id ARTIFACT_ID	string	—	Artifact ID. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet skills artifact delete --id art_123

fleet skills releases

Imported catalog releases.

fleet skills releases

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet skills releases

fleet skills cohorts

Canary cohorts.

fleet skills cohorts

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet skills cohorts

fleet skills upload

Upload a skill archive for one harness and profile.

fleet skills upload --harness H --profile P ARCHIVE.tgz

Argument	Meaning
ARCHIVE.tgz	the gzipped skill archive

Flag	Type	Default	Meaning
--harness H	string	—	Target harness. Required.
--profile P	string	—	Skill profile. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet skills upload --harness hermes --profile default skills-hermes.tgz

fleet skills release

Import a release record.

fleet skills release import RELEASE.json

Subcommands: import.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet skills release import release.json

fleet skills release import

Import a six-harness release, pinning each archive to an uploaded artifact.

fleet skills release import RELEASE.json

Every archive the record names must already be uploaded, matched by harness, profile and SHA-256; a missing one stops the import before anything is sent.

Argument	Meaning
RELEASE.json	a complete release record covering all six harnesses

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet skills release import release.json

fleet skills cohort

Create a canary cohort.

fleet skills cohort create --release ID --digest SHA256 --station ID

Subcommands: create.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet skills cohort create --release rel_123 --digest 3f2a… --station stn_123

fleet skills cohort create

Create a cohort of one canary station for a release.

fleet skills cohort create --release ID --digest SHA256 --station ID

Flag	Type	Default	Meaning
--release ID	string	—	Release ID. Required.
--digest SHA256	string	—	Release digest. Required.
--station ID	string	—	Canary station ID. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet skills cohort create --release rel_123 --digest 3f2a… --station stn_123

fleet skills canary

Plan, inspect and apply a release on a cohort’s canary.

fleet skills canary <plan|inspect|apply> --cohort ID --release ID --digest SHA256 --station ID ...

Subcommands: plan, inspect, apply.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet skills canary plan --cohort coh_123 --release rel_123 --digest 3f2a… --station stn_123

fleet skills canary plan

Plan the canary install.

fleet skills canary plan --cohort ID --release ID --digest SHA256 --station ID

Flag	Type	Default	Meaning
--cohort ID	string	—	Cohort ID. Required.
--release ID	string	—	Release ID. Required.
--digest SHA256	string	—	Release digest. Required.
--station ID	string	—	Station ID. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet skills canary plan --cohort coh_123 --release rel_123 --digest 3f2a… --station stn_123

fleet skills canary inspect

Read a canary operation.

fleet skills canary inspect --cohort ID --release ID --digest SHA256 --station ID --operation ID

Flag	Type	Default	Meaning
--cohort ID	string	—	Cohort ID. Required.
--release ID	string	—	Release ID. Required.
--digest SHA256	string	—	Release digest. Required.
--station ID	string	—	Station ID. Required.
--operation ID	string	—	Operation ID. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet skills canary inspect --cohort coh_123 --release rel_123 --digest 3f2a… --station stn_123 --operation op_123

fleet skills canary apply

Apply the reviewed canary plan.

fleet skills canary apply --cohort ID --release ID --digest SHA256 --station ID --operation ID --plan-digest SHA256

Flag	Type	Default	Meaning
--cohort ID	string	—	Cohort ID. Required.
--release ID	string	—	Release ID. Required.
--digest SHA256	string	—	Release digest. Required.
--station ID	string	—	Station ID. Required.
--operation ID	string	—	Operation ID. Required.
--plan-digest SHA256	string	—	Reviewed plan digest. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet skills canary apply --cohort coh_123 --release rel_123 --digest 3f2a… --station stn_123 --operation op_123 --plan-digest 9c1e…

fleet skills station

Managed skill installs on one station.

fleet skills station <plan|verify|rollback-plan|inspect|apply> --station ID ...

Subcommands: plan, verify, rollback-plan, inspect, apply.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet skills station verify --station stn_123 --profile default

fleet skills station plan

Plan installing an uploaded artifact on a station.

fleet skills station plan --station ID --artifact ARTIFACT_ID

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.
--artifact ARTIFACT_ID	string	—	Uploaded artifact ID. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet skills station plan --station stn_123 --artifact art_123

fleet skills station verify

Check a profile’s installed skills against the record.

fleet skills station verify --station ID --profile PROFILE

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.
--profile PROFILE	string	—	Profile. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet skills station verify --station stn_123 --profile default

fleet skills station rollback-plan

Plan rolling a profile back to its previous install.

fleet skills station rollback-plan --station ID --profile PROFILE

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.
--profile PROFILE	string	—	Profile. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet skills station rollback-plan --station stn_123 --profile default

fleet skills station inspect

Read a station skill operation.

fleet skills station inspect --station ID --operation ID

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.
--operation ID	string	—	Operation ID. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet skills station inspect --station stn_123 --operation op_123

fleet skills station apply

Apply a reviewed station skill plan.

fleet skills station apply --station ID --operation ID --plan-digest SHA256

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.
--operation ID	string	—	Operation ID. Required.
--plan-digest SHA256	string	—	Reviewed plan digest. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet skills station apply --station stn_123 --operation op_123 --plan-digest 9c1e…

fleet skills native

Native placement: skills in the harness’s own skill directory.

fleet skills native <plan|inspect|apply|verify> --station ID ...

Refused unless the node’s operator enabled it with apn native-skills enable.

Subcommands: plan, inspect, apply, verify.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet skills native verify --station stn_123 --profile default

fleet skills native plan

Plan activating, deactivating or rolling back native placement.

fleet skills native plan --station ID --profile PROFILE --action activate|deactivate|rollback

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.
--profile PROFILE	string	—	Profile. Required.
--action activate|deactivate|rollback	string	—	Native placement action. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet skills native plan --station stn_123 --profile default --action activate

fleet skills native inspect

Read a native placement operation.

fleet skills native inspect --station ID --operation ID

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.
--operation ID	string	—	Operation ID. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet skills native inspect --station stn_123 --operation op_123

fleet skills native apply

Apply a reviewed native placement plan.

fleet skills native apply --station ID --operation ID --plan-digest SHA256

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.
--operation ID	string	—	Operation ID. Required.
--plan-digest SHA256	string	—	Reviewed plan digest. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet skills native apply --station stn_123 --operation op_123 --plan-digest 9c1e…

fleet skills native verify

Check a profile’s natively placed skills.

fleet skills native verify --station ID --profile PROFILE

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.
--profile PROFILE	string	—	Profile. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet skills native verify --station stn_123 --profile default

fleet plugins

Review and apply harness plugin changes on a station.

fleet plugins <plan|show|inspect|apply|history|inventory> --station ID ...

The node plans, you read the plan, and apply sends only the digest you reviewed. Nothing here restarts a station. Refused unless the node’s operator enabled it with apn plugin-management enable.

Subcommands: plan, show, inspect, apply, history, inventory.

fleet plugins -h prints:

usage:
  fleet plugins plan --station ID --action enable|disable
  fleet plugins show --station ID --operation ID
  fleet plugins inspect --station ID --operation ID
  fleet plugins apply --station ID --operation ID --plan-digest SHA256
  fleet plugins history --station ID
  fleet plugins inventory --station ID

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

Exit status: As below for each verb; with no verb, prints the usage and exits 2.

fleet plugins inventory --station stn_123

fleet plugins plan

Plan enabling or disabling the live-streaming plugin.

fleet plugins plan --station ID --action enable|disable

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.
--action enable|disable	string	—	Enable or disable. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet plugins plan --station stn_123 --action enable

fleet plugins show

Read a plugin operation.

fleet plugins show --station ID --operation ID

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.
--operation ID	string	—	Operation ID. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet plugins show --station stn_123 --operation op_123

fleet plugins inspect

Ask the node to re-check a planned operation against the profile now.

fleet plugins inspect --station ID --operation ID

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.
--operation ID	string	—	Operation ID. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet plugins inspect --station stn_123 --operation op_123

fleet plugins apply

Apply the reviewed plan.

fleet plugins apply --station ID --operation ID --plan-digest SHA256

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.
--operation ID	string	—	Operation ID. Required.
--plan-digest SHA256	string	—	Reviewed plan digest. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet plugins apply --station stn_123 --operation op_123 --plan-digest 9c1e…

fleet plugins history

Past plugin operations on a station.

fleet plugins history --station ID

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet plugins history --station stn_123

fleet plugins inventory

What the station’s harness has installed.

fleet plugins inventory --station ID

Flag	Type	Default	Meaning
--station ID	string	—	Station ID. Required.

Needs: A person’s token: $AGENTPOD_TOKEN, or the credential fleet login stored. The hub refuses an agent’s token on these routes, and answers only about what the signed-in person owns.

fleet plugins inventory --station stn_123

fleet settings

Hub-wide settings: signup, transcription, speech.

fleet settings <show|signup|transcription|speech> ...

Subcommands: show, signup, transcription, speech.

fleet settings -h prints:

usage:
  fleet settings show
  fleet settings signup [enable|disable]
  fleet settings transcription [show|set --file PATH|- |test]
  fleet settings speech [show|set --file PATH|- |test]

Needs: A workspace admin’s token. Anyone else is refused with 403.

Exit status: As below for each verb; with no verb, prints the usage and exits 2.

fleet settings show

fleet settings show

Every hub-wide setting.

fleet settings show

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet settings show

fleet settings signup

Whether new people may sign up (older hubs).

fleet settings signup [enable|disable]

With no argument it reads; each direction has to be named, so a forgotten word never reopens signup. On a hub that signs in through an account service (every current hub), this record is managed there: the hub answers 410 managed_by_org_plane with the account service’s URL, which this prints, and the command exits 1. It works as described only against an older hub that still issues its own tokens.

Subcommands: enable, disable.

Needs: A workspace admin’s token. Anyone else is refused with 403.

Exit status: As above; 2 for any word other than enable or disable.

fleet settings signup

fleet settings signup enable

Open signup (older hubs).

fleet settings signup enable

On a hub that signs in through an account service (every current hub), this record is managed there: the hub answers 410 managed_by_org_plane with the account service’s URL, which this prints, and the command exits 1. It works as described only against an older hub that still issues its own tokens.

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet settings signup enable

fleet settings signup disable

Close signup (older hubs).

fleet settings signup disable

On a hub that signs in through an account service (every current hub), this record is managed there: the hub answers 410 managed_by_org_plane with the account service’s URL, which this prints, and the command exits 1. It works as described only against an older hub that still issues its own tokens.

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet settings signup disable

fleet settings transcription

The voice-note transcription default. Bare, it shows the setting.

fleet settings transcription [show|set --file PATH|-|test]

See Voice notes.

Subcommands: show, set, test.

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet settings transcription

fleet settings transcription show

The transcription setting.

fleet settings transcription show

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet settings transcription show

fleet settings transcription set

Replace the transcription setting with a document.

fleet settings transcription set --file PATH|-

Flag	Type	Default	Meaning
--file PATH|-	string	—	Settings document, or - for stdin. Required.

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet settings transcription set --file transcription.json

fleet settings transcription test

Ask the hub to try the configured transcription service.

fleet settings transcription test

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet settings transcription test

fleet settings speech

The spoken-reply default. Bare, it shows the setting.

fleet settings speech [show|set --file PATH|-|test]

See Voice notes.

Subcommands: show, set, test.

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet settings speech

fleet settings speech show

The speech setting.

fleet settings speech show

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet settings speech show

fleet settings speech set

Replace the speech setting with a document.

fleet settings speech set --file PATH|-

Flag	Type	Default	Meaning
--file PATH|-	string	—	Settings document, or - for stdin. Required.

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet settings speech set --file speech.json

fleet settings speech test

Ask the hub to try the configured speech service.

fleet settings speech test

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet settings speech test

fleet bridge

The board roster: which agent claims from which board.

fleet bridge <list|add|set|rm|related-work> ...

This table is the gate on an agent doing anything at all: a staffed, online agent claims no card until a row points it at a board. No verb here prints a credential. See Working a board.

Subcommands: list, add, set, rm, related-work.

fleet bridge -h prints:

usage:
  fleet bridge list
  fleet bridge add --key K --board B --station S --token T [--mcp-token M]
                   [--mode M] [--concurrency N] [--profile P] [--wait-ms N] [--enabled true|false]
  fleet bridge set KEY [--board B] [--station S] [--mode M] [--enabled true|false]
                   [--token T] [--mcp-token M] [--concurrency N] [--profile P] [--wait-ms N]
  fleet bridge rm KEY
  fleet bridge related-work BOARD on|off

Needs: A workspace admin’s token. Anyone else is refused with 403.

Exit status: As below for each verb; with no verb, prints the usage and exits 2.

fleet bridge list

fleet bridge list

Every roster row.

fleet bridge list

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet bridge list

fleet bridge add

Add a roster row.

fleet bridge add --key K --board B --station S --token T [--mcp-token M]
                 [--mode M] [--concurrency N] [--profile P] [--wait-ms N] [--enabled true|false]

The four required flags are reported together when missing.

Flag	Type	Default	Meaning
--key K	string	—	Roster key (add). Required.
--board B	string	—	SuperPipeline board id. Required.
--station S	string	—	Station id the work runs on. Required.
--token T	string	—	SuperPipeline agent token (claims). Required.
--mcp-token M	string	—	Run-scoped token the harness spends.
--mode M	string	—	Permission mode.
--concurrency N	int	0	Max cards at once; 0 leaves the hub’s value.
--profile P	string	—	Profile key.
--wait-ms N	int	0	How long a permission request waits for an answer, in ms; 0 leaves the hub’s value.
--enabled true|false	string	—	True or false.

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet bridge add --key reviewer --board brd_123 --station stn_123 --token "$SP_TOKEN"

fleet bridge set

Change some fields of a roster row; the rest stay.

fleet bridge set KEY [--board B] [--station S] [--mode M] [--enabled true|false]
                 [--token T] [--mcp-token M] [--concurrency N] [--profile P] [--wait-ms N]

Refuses a change with no fields, which the hub would otherwise answer 200 for and change nothing.

Argument	Meaning
KEY	the roster key

Flag	Type	Default	Meaning
--board B	string	—	SuperPipeline board id.
--station S	string	—	Station id the work runs on.
--token T	string	—	SuperPipeline agent token (claims).
--mcp-token M	string	—	Run-scoped token the harness spends.
--mode M	string	—	Permission mode.
--concurrency N	int	0	Max cards at once; 0 leaves the hub’s value.
--profile P	string	—	Profile key.
--wait-ms N	int	0	How long a permission request waits for an answer, in ms; 0 leaves the hub’s value.
--enabled true|false	string	—	True or false.

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet bridge set reviewer --board brd_456

fleet bridge rm

Remove a roster row.

fleet bridge rm KEY

Argument	Meaning
KEY	the roster key

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet bridge rm reviewer

fleet bridge related-work

Switch a board’s Related prior work section on or off.

fleet bridge related-work BOARD on|off

The earlier work SuperLibrary finds for a claimed card, put into the card’s prompt as reference material. On for every board until switched off; the next claim on the board reads the new value. Anything but on or off exits 2 without calling the hub.

Argument	Meaning
BOARD	a SuperPipeline brd_ id
STATE	on or off

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet bridge related-work brd_0000000000000001 off

fleet principals

Identities, service principals and their credentials.

fleet principals <verb> ...

Only list works against a current hub; the rest are managed by the account service.

Subcommands: list, suspend, restore, add-service, add-credential, revoke-credential.

fleet principals -h prints:

usage:
  fleet principals list
  fleet principals suspend ID
  fleet principals restore ID
  fleet principals add-service HANDLE --client CLIENT --scope SCOPE[,SCOPE]
  fleet principals add-credential PRN_ID --client CLIENT
  fleet principals revoke-credential SVC_ID

Needs: A workspace admin’s token. Anyone else is refused with 403.

Exit status: As below for each verb; with no verb, prints the usage and exits 2.

fleet principals list

fleet principals list

Who exists in this workspace, read through the account service.

fleet principals list

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet principals list

fleet principals suspend

Suspend a principal, reversibly (older hubs).

fleet principals suspend ID

On a hub that signs in through an account service (every current hub), this record is managed there: the hub answers 410 managed_by_org_plane with the account service’s URL, which this prints, and the command exits 1. It works as described only against an older hub that still issues its own tokens.

Argument	Meaning
ID	a prn_ id

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet principals suspend prn_123

fleet principals restore

Undo a suspension (older hubs).

fleet principals restore ID

On a hub that signs in through an account service (every current hub), this record is managed there: the hub answers 410 managed_by_org_plane with the account service’s URL, which this prints, and the command exits 1. It works as described only against an older hub that still issues its own tokens.

Argument	Meaning
ID	a prn_ id

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet principals restore prn_123

fleet principals add-service

Create a service principal with its first credential (older hubs).

fleet principals add-service HANDLE --client CLIENT --scope SCOPE[,SCOPE]

The response carries the credential’s secret once; it cannot be read again. On a hub that signs in through an account service (every current hub), this record is managed there: the hub answers 410 managed_by_org_plane with the account service’s URL, which this prints, and the command exits 1. It works as described only against an older hub that still issues its own tokens.

Argument	Meaning
HANDLE	the service’s handle

Flag	Type	Default	Meaning
--client CLIENT	string	—	The HUB_OAUTH_CLIENTS id whose audiences its tokens carry. Required.
--scope SCOPE[,SCOPE]	string	—	Comma-separated grant scopes, e.g. evidence:read. Required.

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet principals add-service evidence-reader --client superwitness --scope evidence:read

fleet principals add-credential

Add a credential to a service principal: the first half of a rotation (older hubs).

fleet principals add-credential PRN_ID --client CLIENT

The old credential keeps working until revoke-credential, so the consumer can switch with no gap. On a hub that signs in through an account service (every current hub), this record is managed there: the hub answers 410 managed_by_org_plane with the account service’s URL, which this prints, and the command exits 1. It works as described only against an older hub that still issues its own tokens.

Argument	Meaning
PRN_ID	the service principal’s id

Flag	Type	Default	Meaning
--client CLIENT	string	—	The HUB_OAUTH_CLIENTS id whose audiences its tokens carry. Required.

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet principals add-credential prn_123 --client superwitness

fleet principals revoke-credential

Revoke one service credential (older hubs).

fleet principals revoke-credential SVC_ID

On a hub that signs in through an account service (every current hub), this record is managed there: the hub answers 410 managed_by_org_plane with the account service’s URL, which this prints, and the command exits 1. It works as described only against an older hub that still issues its own tokens.

Argument	Meaning
SVC_ID	the credential’s svc_ id

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet principals revoke-credential svc_123

fleet grants

Dispatch authority, as a document (older hubs).

fleet grants <list|show|set|rm> ...

On a hub that signs in through an account service (every current hub), this record is managed there: the hub answers 410 managed_by_org_plane with the account service’s URL, which this prints, and the command exits 1. It works as described only against an older hub that still issues its own tokens. See Dispatch and grants.

Subcommands: list, show, set, rm.

fleet grants -h prints:

usage:
  fleet grants list
  fleet grants show PRINCIPAL_ID
  fleet grants set PRINCIPAL_ID --file PATH|-
  fleet grants rm PRINCIPAL_ID

Needs: A workspace admin’s token. Anyone else is refused with 403.

Exit status: As below for each verb; with no verb, prints the usage and exits 2.

fleet grants list

fleet grants list

Every grant.

fleet grants list

On a hub that signs in through an account service (every current hub), this record is managed there: the hub answers 410 managed_by_org_plane with the account service’s URL, which this prints, and the command exits 1. It works as described only against an older hub that still issues its own tokens.

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet grants list

fleet grants show

One principal’s grant.

fleet grants show PRINCIPAL_ID

On a hub that signs in through an account service (every current hub), this record is managed there: the hub answers 410 managed_by_org_plane with the account service’s URL, which this prints, and the command exits 1. It works as described only against an older hub that still issues its own tokens.

Argument	Meaning
PRINCIPAL_ID	a prn_ id

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet grants show prn_123

fleet grants set

Replace a principal’s grant with a document.

fleet grants set PRINCIPAL_ID --file PATH|-

On a hub that signs in through an account service (every current hub), this record is managed there: the hub answers 410 managed_by_org_plane with the account service’s URL, which this prints, and the command exits 1. It works as described only against an older hub that still issues its own tokens.

Argument	Meaning
PRINCIPAL_ID	a prn_ id

Flag	Type	Default	Meaning
--file PATH|-	string	—	Grant document, or - for stdin. Required.

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet grants set prn_123 --file grant.json

fleet grants rm

Remove a principal’s grant.

fleet grants rm PRINCIPAL_ID

On a hub that signs in through an account service (every current hub), this record is managed there: the hub answers 410 managed_by_org_plane with the account service’s URL, which this prints, and the command exits 1. It works as described only against an older hub that still issues its own tokens.

Argument	Meaning
PRINCIPAL_ID	a prn_ id

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet grants rm prn_123

fleet users

People: list, show, ban, unban, role (older hubs).

fleet users <list|show|ban|unban|role> ...

On a hub that signs in through an account service (every current hub), this record is managed there: the hub answers 410 managed_by_org_plane with the account service’s URL, which this prints, and the command exits 1. It works as described only against an older hub that still issues its own tokens.

Subcommands: list, show, ban, unban, role.

fleet users -h prints:

usage:
  fleet users list
  fleet users show ID
  fleet users ban ID --reason "why" [--expires RFC3339]
  fleet users unban ID
  fleet users role ID --role ROLE

Needs: A workspace admin’s token. Anyone else is refused with 403.

Exit status: As below for each verb; with no verb, prints the usage and exits 2.

fleet users list

fleet users list

Every account.

fleet users list

On a hub that signs in through an account service (every current hub), this record is managed there: the hub answers 410 managed_by_org_plane with the account service’s URL, which this prints, and the command exits 1. It works as described only against an older hub that still issues its own tokens.

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet users list

fleet users show

One account.

fleet users show ID

On a hub that signs in through an account service (every current hub), this record is managed there: the hub answers 410 managed_by_org_plane with the account service’s URL, which this prints, and the command exits 1. It works as described only against an older hub that still issues its own tokens.

Argument	Meaning
ID	the user’s id

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet users show usr_123

fleet users ban

Ban an account, with a recorded reason.

fleet users ban ID --reason "why" [--expires RFC3339]

A reason is required: a ban nobody can review later is one the next person cannot lift with confidence. On a hub that signs in through an account service (every current hub), this record is managed there: the hub answers 410 managed_by_org_plane with the account service’s URL, which this prints, and the command exits 1. It works as described only against an older hub that still issues its own tokens.

Argument	Meaning
ID	the user’s id

Flag	Type	Default	Meaning
--reason TEXT	string	—	Why, recorded with the ban. Required.
--expires RFC3339	string	—	RFC3339 instant the ban lifts itself.

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet users ban usr_123 --reason "shared credentials" --expires 2026-12-01T00:00:00Z

fleet users unban

Lift a ban.

fleet users unban ID

On a hub that signs in through an account service (every current hub), this record is managed there: the hub answers 410 managed_by_org_plane with the account service’s URL, which this prints, and the command exits 1. It works as described only against an older hub that still issues its own tokens.

Argument	Meaning
ID	the user’s id

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet users unban usr_123

fleet users role

Set an account’s role.

fleet users role ID --role ROLE

On a hub that signs in through an account service (every current hub), this record is managed there: the hub answers 410 managed_by_org_plane with the account service’s URL, which this prints, and the command exits 1. It works as described only against an older hub that still issues its own tokens.

Argument	Meaning
ID	the user’s id

Flag	Type	Default	Meaning
--role ROLE	string	—	The role to set. Required.

Needs: A workspace admin’s token. Anyone else is refused with 403.

fleet users role usr_123 --role admin

fleet update

Replace this binary with the newest release.

fleet update [--check] [--force]

Fetches the agentpod-fleet asset for this platform and verifies it against the release’s SHA256SUMS. There is no service to restart: the next invocation is the new binary.

Flag	Type	Default	Meaning
--check	bool	false	Resolve and report current/latest version, no changes.
--force	bool	false	Update even when already on the latest version.

Needs: Nothing from the hub. Network access to GitHub releases, and write access to the binary’s own path.

Exit status: 0 when up to date, updated, or (with --check) reported. 1 when the release could not be fetched or verified.

fleet update --check
fleet update

fleet skill

Print the skill that ships inside this binary.

fleet skill
fleet skill install [--dir DIR] [--json]

Prints a SKILL.md for agents: what fleet is, how to sign in, every verb, and which verbs change shared state and so need an operator’s say-so. It is written from this binary’s own verbs and stamped with its version, and a test fails when a verb exists that it does not mention. Not to be confused with fleet skills, which manages skill artifacts on the fleet.

Subcommands: install.

Needs: Nothing. Runs without a credential or a hub.

Exit status: 0. 2 for an unknown subverb.

fleet skill | less

fleet skill install

Write the skill where an agent will find it.

fleet skill install [--dir DIR] [--json]

Writes DIR/agentpod-fleet/SKILL.md atomically (a staged file in the same directory, then a rename) and prints the path. Running it again rewrites only that file. DIR defaults to ~/.claude/skills. fleet update refreshes a copy at the default directory and never creates one.

Flag	Type	Default	Meaning
--dir DIR	string	—	The skills directory to install under (default ~/.claude/skills).
--json	bool	false	Print the path written as JSON.

Needs: Nothing. Runs without a credential or a hub.

Exit status: 0 once written. 1 when the file could not be written. 2 for a bad flag.

fleet skill install
fleet skill install --dir ./skills --json

fleet version

Print the version and platform.

fleet version

Needs: Nothing. Runs without a credential or a hub.

Exit status: 0.

fleet version   # agentpod-fleet v0.1.90 darwin/arm64

fleet help

Print the verb list and how credentials work.

fleet help
fleet -h
fleet

All three print the same text. A group’s own usage is fleet <verb> -h; for verbs with flags, fleet <verb> <subverb> -h prints them with their defaults.

Needs: Nothing. Runs without a credential or a hub.

Exit status: 0.

fleet help