Command reference

Synopsis

The command-line interface (CLI) manages workspaces, fleets, access, secrets, and memory.

agentsfleet [GLOBAL_OPTIONS] <COMMAND>

<COMMAND> comes from the tables below. Run any command with --help to see its accepted values. Identifier placeholders come from the matching create or list command. You choose name, path, provider, message, and query values.

Example with output

agentsfleet --help

DESCRIPTION
  agentsfleet cli

USAGE
  agentsfleet <subcommand> [flags]

FLAGS
  --api <url>    API base URL
  --json         Machine-readable JSON output
<varies>
SUBCOMMANDS
  login        Authenticate via browser
<varies>
  chat         Create, resume, and review a private workspace chat
  fleet        Fleet management subcommands
<varies>

Options

Global options

<API_URL> is the API base URL for your deployment.

Option	Effect	Default	Unit or range
`-v`, `--version`	Prints the client version and exits.	`false`	Boolean
`--api <API_URL>`	Sends requests to this API URL.	`https://api.agentsfleet.net`	URL beginning with `http://` or `https://`
`--json`	Prints JSON when the command supports it.	`false`	Boolean
`-h`, `--help`	Prints help and exits.	`false`	Boolean

Write these after login. Only agentsfleet login reads them.

Option	Effect	Default	Unit or range
`--no-open`	Uses manual code entry and prints a URL you can open on another device.	`false`	Boolean
`--no-input`	Returns an error instead of asking a question.	`false`	Boolean
`--force`	Signs in again even when this computer already holds a credential.	`false`	Boolean
`--token-name <LABEL>`	Sets a label on this sign-in request.	The platform family name	1 to 64 characters from space through tilde

Browser on this computer

Start sign-in from an interactive terminal on the same computer as your browser.

agentsfleet login

Connect your terminal
Open this link on this computer:
login_url: <varies>
Check code: <varies>
Waiting for authorization… (Esc to cancel)
browser: opened
<varies>
Finalizing sign-in…
✓ signed in as <varies> — <varies>

Compare the check code in your browser with the code in your terminal.
Choose Authorize only if you started the sign-in and both codes match.

After approval, the client saves this computer’s credential and checks your identity. The terminal then shows your name and account. Choose Deny if you did not start the sign-in or the codes differ. Press Esc or Ctrl+C while waiting to cancel. The waiting request expires after five minutes. Once Finalizing sign-in… appears, cancellation is disabled until sign-in finishes. Keep the terminal open until it reports the result. If the browser does not open, open the printed login_url on this computer. If the browser cannot reach your terminal, cancel while waiting and restart with --no-open. Start a new sign-in if the request expires.

Browser on another device

Use manual code entry for a remote terminal, such as a Secure Shell (SSH) session, or a browser on another device.

Start manual sign-in in your interactive terminal.

agentsfleet login --no-open

Login session
session_id: <varies>
login_url: <varies>
browser: not opened (open URL manually)
Enter the 6-digit verification code shown in your browser: <varies>

Open the printed login_url in your browser.
Choose Authorize only if you started this sign-in.
Enter the browser’s six-digit verification code in the terminal that started sign-in.

The terminal reports signed in as with your name and account after sign-in succeeds. Manual sign-in requires terminal input, so omit --no-input.

Account and diagnosis

Command	Effect
`agentsfleet login`	Opens same-computer browser authorization and saves a credential after approval.
`agentsfleet logout`	Revokes this computer’s credential and any unfinished sign-in, then clears local credentials. Browser sessions stay signed in.
`agentsfleet whoami`	Shows who this terminal is signed in as, the credential’s source (`environment` or `file`), and the server it talks to.
`agentsfleet doctor`	Checks client settings, authentication, and API access.

Workspaces and access

Command	Effect
`agentsfleet workspace create <NAME>`	Creates a workspace and selects it. The name is required.
`agentsfleet workspace list`	Lists workspaces.
`agentsfleet workspace use <WORKSPACE_ID>`	Selects the active workspace on this computer.
`agentsfleet workspace show [WORKSPACE_ID]`	Shows one workspace.
`agentsfleet workspace secrets`	Prints the secret command and dashboard path.
`agentsfleet workspace delete <WORKSPACE_ID>`	Removes one workspace from local client state. Remote data remains.
`agentsfleet api-key create --name <NAME>`	Creates a tenant API key. `--name` is required, and the raw key appears once.
`agentsfleet api-key list`	Lists tenant API keys.
`agentsfleet api-key revoke <API_KEY_ID>`	Revokes a tenant API key. Calls using that key fail.
`agentsfleet api-key delete <API_KEY_ID>`	Deletes metadata for a revoked tenant API key.
`agentsfleet connector list`	Lists connector setup and connection state.
`agentsfleet connector show <PROVIDER>`	Shows one connector.
`agentsfleet grant list --fleet <FLEET_ID>`	Lists integration grants for one fleet.
`agentsfleet grant delete --fleet <FLEET_ID> <GRANT_ID>`	Revokes one grant. Later access through that grant fails.

Chat

agentsfleet chat creates, resumes, and reviews a private draft. It is the only way to create a fleet or a Library entry from the terminal. Only the person who starts a draft can read it.

Command	Effect
`agentsfleet chat --model <MODEL_REF>`	Starts a blank draft and opens an interactive chat.
`agentsfleet chat <DRAFT_ID>`	Resumes a draft and prints its earlier messages.
`agentsfleet chat --definition <PATH> --model <MODEL_REF>`	Starts a draft from a Definition JSON file, with no chat message.
`agentsfleet chat --library <LIBRARY_ID> --revision <REVISION_ID> --model <MODEL_REF>`	Starts a draft from one Library revision, with no chat message.
`agentsfleet chat --fleet <FLEET_ID> --setup-revision <SETUP_REVISION> --model <MODEL_REF>`	Starts a draft that improves an existing fleet, with no chat message.
`agentsfleet chat list`	Lists one page of your setup chats, most recently updated first.
`agentsfleet chat rename <DRAFT_ID> <TITLE>`	Renames an open, idle setup chat. The saved fleet keeps its name.
`agentsfleet chat delete <DRAFT_ID>`	Deletes a setup chat and its private messages after you confirm. Saved fleets keep running.

<MODEL_REF> is the ref of an authoring model from GET /v1/workspaces/{workspace_id}/models?purpose=authoring. <SETUP_REVISION> is the fleet’s setup_revision field from agentsfleet --json fleet show <FLEET_ID>. In an interactive chat, ordinary text is a message. These actions start with /:

Slash command	Effect
`/review [INSTANCE_NAME]`	Prints the full setup, its required access, its readiness checks, and its review digest. The name selects the fleet name.
`/save`	Saves the reviewed setup as a new fleet.
`/run <MESSAGE>`	Saves the reviewed setup and sends the fleet `<MESSAGE>` once.
`/publish <LABEL>`	Publishes the reviewed setup as a Library entry.
`/apply`	Applies the reviewed improvement to its source fleet.
`/model <MODEL_REF>`	Changes the authoring model for later messages.
`/stop`	Cancels every accepted message in the draft that has not finished. Ctrl+C stops the reply you are following.
`/retry`	Repeats the last action whose outcome was unknown.
`/delete`	Deletes the draft and its private messages.
`/quit`	Leaves the chat. The draft stays for `agentsfleet chat <DRAFT_ID>`.

Save, publish, and apply each use only the setup you last reviewed. A message after a review needs a new review first. Outside a terminal, add --no-input and name every action as a flag. This pair reviews a Definition, then saves it with the digest the review printed:

agentsfleet chat --definition <PATH> --model <MODEL_REF> --no-input --review --name <NAME>

✓ Draft <DRAFT_ID> created
Instance: <NAME>
<varies>
Review digest: <DIGEST>

agentsfleet chat <DRAFT_ID> --no-input --save --name <NAME> --review-digest <DIGEST>

<varies>
✓ Fleet <NAME>: active

Option	Effect	Default	Unit or range
`--model <MODEL_REF>`	Selects the authoring model for a new draft. Required unless you resume a draft.	None	Model reference
`--message <TEXT>`	Sends one chat message and follows its reply.	None	1 to 32,768 bytes
`--definition <PATH>`	Starts from a Definition JSON file.	None	Readable file, at most 128 KiB
`--library <LIBRARY_ID>`	Starts from a Library entry. Needs `--revision`.	None	Library identifier
`--revision <REVISION_ID>`	Selects the exact Library revision.	None	Revision identifier
`--fleet <FLEET_ID>`	Starts an improvement of an existing fleet. Needs `--setup-revision`.	None	Fleet identifier
`--setup-revision <SETUP_REVISION>`	Selects the fleet setup revision to improve.	None	Positive whole number
`--no-input`	Runs only the actions you name, with no prompt.	`false`	Boolean
`--review`	Prints the full setup, access, readiness, and review digest.	`false`	Boolean
`--name <NAME>`	Selects the fleet name before the review.	The draft’s current fleet name	Lowercase letters, digits, and hyphens
`--review-digest <DIGEST>`	The digest of the review you inspected. Required with `--save`, `--apply`, and `--publish`.	None	Digest text
`--save`	Saves the reviewed setup as a new fleet.	`false`	Boolean
`--run-now <TEXT>`	With `--save`, sends the new fleet this message once.	None	1 to 32,768 bytes
`--apply`	Applies the reviewed improvement to its source fleet.	`false`	Boolean
`--publish <LABEL>`	Publishes the reviewed setup as a Library entry with this label.	None	1 to 100 characters
`--publish-to <LIBRARY_ID>`	With `--publish`, adds a revision to this owned entry instead.	None	Library identifier
`--library-etag <ETAG>`	The entry tag you inspected. Required with `--publish-to`.	None	Entity tag
`--stop`	Cancels every accepted message in the draft that has not finished.	`false`	Boolean
`--operation-id <ID>`	Retries an action whose outcome was unknown, under its first identity.	None	Identifier the client printed, usable for 24 hours
`--candidate-id <ID>`	With `--operation-id`, names the setup the retried Save, Apply, or publish used.	None	Identifier the client printed
`--setup-etag <ETAG>`	With `--operation-id` and `--apply`, names the fleet setup tag you inspected.	None	Identifier the client printed

One invocation takes one source and at most one of --save, --apply, and --publish. A digest that does not match the current review is refused with exit code 4. A Save that leaves the fleet installing prints each waiting check and exits with code 1. A Save, Apply, or publish whose reply was lost prints the --operation-id and --candidate-id values to retry with.

List, rename, and delete setup chats

agentsfleet chat list reads one page per run, most recently updated first. It prints TITLE, CHAT, STATUS, VERSIONS, and UPDATED.

agentsfleet chat list --search "health check"

TITLE           CHAT        STATUS      VERSIONS                UPDATED
<varies>
More chats available. Repeat this list with --cursor <TOKEN> and the same filters.

STATUS reads In progress, Setup ready, Saving fleet, Fleet saved, or Chat closed. VERSIONS lists the recorded Proposed, Saved, and Published versions, such as Proposed v3 · Saved v2. To read the next page, run the same command with --cursor <TOKEN>. <TOKEN> is the value the previous page printed. A page with no rows reads No setup chats match this list.

Option	Effect	Default	Unit or range
`--search <TEXT>`	Matches your chat titles and message text, ignoring case. Leading and trailing spaces are trimmed.	None	1 to 200 characters, no null (NUL) character
`--limit <COUNT>`	Sets the page size.	`50`	Integer, 1 to 100
`--cursor <TOKEN>`	Reads the page after the one that printed this token. The token works only with the same filters.	None	Token the previous page printed
`--state <STATE>`	Lists only chats in this state.	All states	`editing`, `saving`, or `closed`
`--fleet <FLEET_ID>`	Lists only chats linked to this fleet.	None	Fleet identifier
`--workspace <WORKSPACE_ID>`	Targets a workspace other than the active one.	Active workspace	Workspace identifier

With --json, the command prints the server’s page as returned, with items and next_cursor. agentsfleet chat rename <DRAFT_ID> <TITLE> sets a new title. <TITLE> is trimmed and must hold 1 to 100 characters, with no NUL character. A busy or closed chat fails with UZ-AUTHOR-002, and nothing changes.

agentsfleet chat rename <DRAFT_ID> "Nightly health check"

✓ Renamed setup chat to Nightly health check

agentsfleet chat delete removes the chat’s private messages for good. It has no dry-run option.

agentsfleet chat delete <DRAFT_ID> asks Delete setup chat <DRAFT_ID>? Saved fleets keep running. [y/N] first. Pass --yes to skip the question. Without a terminal, or with --json, --yes is required.

agentsfleet chat delete <DRAFT_ID> --yes

✓ Deleted setup chat <DRAFT_ID>. Saved fleets keep running.

Both commands accept --workspace <WORKSPACE_ID>.

Fleets

Command	Effect
`agentsfleet library`	Lists the workspace gallery: every platform or account-owned entry this workspace can use.
`agentsfleet library list`	Lists only the entries your account owns.
`agentsfleet library delete <LIBRARY_ID>`	Removes one entry your account owns, with its revision history. Fleets saved from it keep running.
`agentsfleet fleet show <FLEET_ID>`	Shows one fleet.
`agentsfleet list`	Lists fleets in the active workspace. `--starting-after <CURSOR>` fetches the next page. With `--json`, it prints the server’s page as returned.
`agentsfleet status`	Shows every fleet in the active workspace, including how many approvals each one is waiting on. It takes no identifier — use `agentsfleet fleet show <FLEET_ID>` for one fleet.
`agentsfleet stop <FLEET_ID>`	Stops new work. You can resume the fleet.
`agentsfleet resume <FLEET_ID>`	Resumes a stopped or paused fleet. On an `installing` fleet, it checks setup again and activates the fleet when every check passes.
`agentsfleet kill <FLEET_ID>`	Marks a fleet as killed. This cannot be undone. On an `installing` fleet, it cancels setup and returns the draft to editing.
`agentsfleet delete <FLEET_ID>`	Deletes a killed fleet and its stored data. This cannot be undone.
`agentsfleet logs [FLEET_ID]`	Shows recent activity.
`agentsfleet events <FLEET_ID>`	Lists historical events with filters.
`agentsfleet steer <FLEET_ID> [MESSAGE]`	Sends a message and streams the response. If the stream drops, it reads that exact event for up to 60 seconds, until the event finishes.

agentsfleet delete has no dry-run option. Run agentsfleet kill first, then check the fleet identifier before deletion. agentsfleet library and agentsfleet library list answer different questions. The first lists everything this workspace can use, platform entries included. The second lists only what your account owns, which is the set agentsfleet library delete can act on. agentsfleet library delete removes an entry permanently. Removing a platform entry, another account’s entry, or one already gone answers UZ-AUTHOR-001 and exits with code 3. Fleets and Library entries come only from reviewed chat drafts. The file, GitHub, and template import commands, agentsfleet install, and agentsfleet fleet update were removed; agentsfleet chat replaces them.

Approvals

Command	Effect
`agentsfleet approvals list`	Lists the gates waiting for a decision in the active workspace.
`agentsfleet approvals list --fleet <FLEET_ID>`	Lists the waiting gates for one fleet.
`agentsfleet approvals show <GATE_ID>`	Shows one gate, including the reach an approval grants.
`agentsfleet approvals approve <GATE_ID>`	Approves the gate. The parked run continues.
`agentsfleet approvals deny <GATE_ID>`	Denies the gate. The parked run ends without the access it asked for.

Saving a fleet that declares a mintable credential opens an integration grant for approval. An approved grant covers repository writes until it is revoked. Rules declared under gates can also ask for approval during a run; a waiting gate parks that run until someone decides it. See Approvals for the scope of each decision and how to revoke a grant.

Schedules

Every subcommand takes the fleet identifier. The four that act on one schedule take its identifier after it.

Command	Effect
`agentsfleet schedule create <FLEET_ID> --cron <EXPRESSION> --message <TEXT>`	Creates a schedule that wakes a fleet on a cron expression.
`agentsfleet schedule list <FLEET_ID>`	Lists the schedules a fleet holds.
`agentsfleet schedule update <FLEET_ID> <SCHEDULE_ID>`	Changes an existing schedule.
`agentsfleet schedule delete <FLEET_ID> <SCHEDULE_ID>`	Deletes one schedule.
`agentsfleet schedule show <FLEET_ID> <SCHEDULE_ID>`	Shows one schedule and its state at the upstream scheduler.
`agentsfleet schedule sync <FLEET_ID> <SCHEDULE_ID>`	Re-sends the schedule to the upstream scheduler.

Run agentsfleet schedule sync <FLEET_ID> <SCHEDULE_ID> when the saved schedule reports an unconfirmed registration. A successful HTTP response can still carry a schedule whose synchronization failed; check its state and diagnostic message. Each option is accepted by the subcommands named beside it.

Option	Accepted by	Effect	Default	Unit or range
`--cron <EXPRESSION>`	`create`, `update`	Sets when the schedule fires.	Unset	Five-field cron expression
`--message <TEXT>`	`create`, `update`	Sets the message the fleet receives on each fire.	Unset	Text
`--timezone <TIMEZONE>`	`create`, `update`	Reads the cron expression in this zone.	`UTC` on `create`	Supported region name
`--status <STATE>`	`update`	Sets whether the schedule fires.	Unset	`active` or `paused`
`--workspace <WORKSPACE_ID>`	all six	Targets a workspace other than the active one.	Active workspace	Workspace identifier

A fleet holds at most 32 schedules. agentsfleet schedule list prints SCHEDULE_ID, SCHEDULE, STATUS, NEXT RUN, MESSAGE, and AGO. SCHEDULE is the server’s description of the expression with its zone, such as At 9:00 AM (UTC).

agentsfleet schedule list <FLEET_ID>

SCHEDULE_ID   SCHEDULE            STATUS      NEXT RUN    MESSAGE     AGO
<varies>

STATUS reads Scheduled, Paused, Activation pending, or Next run unavailable. NEXT RUN is a Request for Comments (RFC) 3339 time only for a scheduled row, and — otherwise. The server computes both. create, update, show, and sync print one line in the same terms.

✓ created <SCHEDULE_ID>: At 9:00 AM (UTC) · Scheduled · Next run: <varies>

With --json, or when standard output is not a terminal, schedule commands print the server’s JSON as returned. The exception is delete, which prints {"deleted":true,"schedule_id":"<SCHEDULE_ID>"} after the server confirms deletion. A schedule response missing a field the client reads fails with SCHEDULE_RESPONSE_INVALID and exit code 3.

Secrets and memory

Command	Effect
`agentsfleet secret create <NAME>`	Stores a JSON object in the workspace vault under a name that is free. A name already in use is reported as skipped, and nothing is written.
`agentsfleet secret create <NAME> --provider <ID> --api-key <KEY> --model <MODEL>`	Stores a model-provider credential. `--provider` and `--model` are both checked against the model catalogue your server serves — run `agentsfleet models` to list it. `--provider openai-compatible` adds a required `https` `--base-url`, makes `--api-key` optional, and accepts any `--model`.
`agentsfleet secret update <NAME>`	Replaces a stored secret without releasing its name. It accepts the same data and provider options as `agentsfleet secret create`.
`agentsfleet secret show <NAME>`	Confirms that a secret exists without showing its value.
`agentsfleet secret list`	Lists secret names, kinds, and creation times. Use `--json` for structured metadata.
`agentsfleet secret delete <NAME>`	Deletes a secret. Fleets using the secret fail on their next use.
`agentsfleet memory list --fleet <FLEET_ID>`	Lists memory entries newest first.
`agentsfleet memory search <QUERY> --fleet <FLEET_ID>`	Searches memory keys and content.

agentsfleet secret delete has no dry-run option. The deleted secret value cannot be recovered.

Model catalogue

Command	Effect
`agentsfleet models`	Lists regular models with names, providers, context windows, and input, cached-input, and output rates.
`agentsfleet models --provider <ID>`	Lists one provider’s models.
`agentsfleet models --advanced`	Includes advanced models. Defaults to `false`.

The table prints MODEL, NAME, PROVIDER, CONTEXT, IN/MTOK, CACHED/MTOK, and OUT/MTOK. Context windows show exact token counts. Rates show exact dollars per million tokens, including zero and fractions of a cent. The client reads every catalogue page before printing. Use --json for each model’s full price schedule, context source, and verification time. The dashboard’s model picker reads the same catalogue. Model rates apply when you use platform credentials. Your provider bills model usage when you supply your own credentials. If the catalogue is empty, ask an administrator to add models. During secret creation, an empty or unavailable catalogue skips the client’s provider check. The server still validates the credential.

Tenant settings

Command	Effect
`agentsfleet tenant provider show`	Shows the active model provider.
`agentsfleet tenant provider create --secret <NAME>`	Selects a self-managed provider secret.
`agentsfleet tenant provider delete`	Returns the tenant to the platform provider.
`agentsfleet billing show`	Shows the tenant balance, fleet-run costs, and settled setup-chat costs.

Billing includes paid failed setup attempts. The setup column shows these costs, with a work identifier for each setup attempt. --limit <COUNT> reads 1 to 100 charge records per page, with a default of 10. Any value that is not a whole number in that range is refused with exit code 4. Use the returned next_cursor as <TOKEN> in --cursor <TOKEN> to read the next page. Charges for the same fleet event group within each page. Every returned charge contributes to the displayed totals, including a repeated charge and a category the client cannot label. Totals add exact nanodollar amounts, so no charge is rounded away.

Errors

Exit code	Meaning
`0`	The command succeeded.
`1`	Authentication, session, or unexpected failure.
`2`	Network failure or rate limit.
`3`	The API returned a server failure.
`4`	The invocation was rejected: a missing argument, a missing or unrecognized flag, a value that failed validation, or an unknown command.
`5`	Local configuration is missing or invalid.
`130`	You interrupted the command.

Login reports network and API sign-in failures with exit code 1. A rejected invocation is answered before any request is sent. The form is always the same: what is wrong, then the command that puts it right. What is wrong may be an absent argument, a value that failed validation, or an unrecognized command.

$ agentsfleet events
✕ error: missing required argument 'fleet_id'
  Suggestion: usage: agentsfleet events [options] <fleet_id>

Under --json the same rejection is a parseable envelope on standard error, carrying a stable code you can switch on:

{
  "error": {
    "code": "MISSING_ARGUMENT",
    "message": "missing required argument 'fleet_id'"
  }
}

The codes are MISSING_ARGUMENT, MISSING_OPTION_VALUE, MISSING_REQUIRED_OPTION, UNKNOWN_COMMAND, UNKNOWN_OPTION, INVALID_ARGUMENT, and EXCESS_ARGUMENTS. API failures include a stable error code and request identifier when the server supplies them. Use both values when reporting a problem. A server failure is reported with the message the server wrote for a reader, not with its internal detail text. A Save refused after a setup change reads This setup changed. Review it before saving. in place of the server’s detail text. The error registry lists the message each code carries.

Command line

Tutorials

Synopsis

Example with output

Options

Global options

Browser on this computer

Browser on another device

Account and diagnosis

Workspaces and access

Chat

List, rename, and delete setup chats

Fleets

Approvals

Schedules

Secrets and memory

Model catalogue

Tenant settings

Errors

​Synopsis

​Example with output

​Options

​Global options

​Login options

​Browser on this computer

​Browser on another device

​Account and diagnosis

​Workspaces and access

​Chat

​List, rename, and delete setup chats

​Fleets

​Approvals

​Schedules

​Secrets and memory

​Model catalogue

​Tenant settings

​Errors

​Related pages

Synopsis

Example with output

Options

Global options

Login options

Browser on this computer

Browser on another device

Account and diagnosis

Workspaces and access

Chat

List, rename, and delete setup chats

Fleets

Approvals

Schedules

Secrets and memory

Model catalogue

Tenant settings

Errors

Related pages