CLI options¶

How the unified CAFleet CLI (cafleet) accepts configuration parameters.

Subcommand summary¶

One row per subcommand. "Identity flag" is the per-subcommand option naming the acting agent (--agent-id) or the target member (--member-id).

Option Source Matrix¶

Each parameter has exactly one input source:

Why --fleet-id is a literal CLI flag, not an environment variable. Claude Code's permissions.allow matches Bash invocations as literal command strings. A literal cafleet --fleet-id <int> ... invocation matches a single permissions.allow pattern of the same shape across every subcommand for that fleet. Shell-expansion patterns (export VAR=... followed by $VAR substitution) break that matching and force per-invocation permission prompts that interrupt agent work. Substitute the literal integer ids printed by cafleet fleet create and cafleet agent register — do not use shell variables to hold them.

Create a fleet first if you don't have one:

cafleet fleet create --label "my-project"
# → prints the fleet_id

Then pass the printed id as --fleet-id <id> on every client + member command.

Global Options¶

Placed before the subcommand:

--full semantics (cross-subcommand escape hatch)¶

--full is the global "give me every field cafleet has, untruncated, unfiltered" escape hatch. A single flag covers four overloaded surfaces:

Agent ID (--agent-id)¶

--agent-id is a per-subcommand option (not a global option). It identifies which agent is acting and must be specified on each invocation. It is typed int; a non-integer fails with Click's standard Error: Invalid value for '--agent-id': '<x>' is not a valid integer. (exit 2). The same type=int applies to every id option — --to, --id (agent show), --member-id, and --task-id — so each rejects a non-integer the same way. Ids are short by construction (DB-assigned integers, typically 1–4 digits), so they are pasted in full; there is no prefix resolution. Which subcommand takes which identity flag is in the Subcommand summary.

Message Body Truncation¶

The five subcommands that emit a user-supplied delivery body — cafleet message {send,poll,ack,cancel,show} — truncate the text body to the first CAFLEET_MAX_TEXT_LEN Unicode codepoints (default 200) plus a single … codepoint suffix by default. The truncation applies uniformly in both text and --json output.

The suffix is the single Unicode codepoint … (U+2026 HORIZONTAL ELLIPSIS) — exactly one codepoint with no count and no companion text_length field.

cafleet message broadcast is different — the broker returns a broadcast_summary task whose top-level text column is a broker-generated summary string (e.g. Broadcast sent to N recipients), not the original body. By default the summary renders as the one-line broadcast id=<id> recipients=<count> — see the --full semantics message broadcast row.

The table describes the resulting text value AFTER truncation. Text mode omits the text: line entirely when the resulting value is empty, while --json always includes it.

Length is measured in Python str codepoints, never bytes — multibyte characters are never split.

cafleet --fleet-id <fleet-id> message poll --agent-id <my-agent-id>          # default: text truncated to 200 cp + "…"
cafleet --fleet-id <fleet-id> message poll --agent-id <my-agent-id> --full   # full body

This applies to CLI emit sites only. FastAPI /api/* responses (see webui-api.md) are unchanged — the WebUI is human-facing and renders full bodies. agent.description, skills[].description, agent_card_json sub-fields, and member capture content are also untouched.

cafleet db — Schema Management¶

db init¶

No flags. Creates the database file if missing and applies Alembic migrations to the head revision; idempotent, so re-run it after every package upgrade. Prints which action was taken (created, upgraded, or already at head). Install-time usage and the upgrade warning for pre-integer-PK databases are canonical on the Install page.

cafleet fleet — Fleet Management¶

The cafleet fleet subgroup manages fleets. These commands write directly to SQLite — the broker server does not need to be running.

fleet create¶

There are no --name / --description flags. The root Director's name and description are hardcoded (name="Director", description="Root Director for this fleet").

Creates a new fleet with a DB-assigned integer identifier. Must be run inside a tmux session — outside tmux the command exits 1 with Error: cafleet fleet create must be run inside a tmux session and writes nothing to the DB. It creates the fleet, its root Director (and placement), and the built-in Administrator atomically (all-or-nothing) — see data-model.md for the Administrator's distinguishing agent_card_json.cafleet.kind flag.

Non-JSON output (default) — one compact line carrying the new fleet_id, the root Director's agent_id, and the built-in Administrator's agent_id:

<fleet_id> director=<director_agent_id> admin=<administrator_agent_id>

Non-JSON output (hidden --full flag) — line 1 is fleet_id, line 2 is the root Director's agent_id:

<fleet_id>
<director_agent_id>
label:            <label or empty>
created_at:       <iso8601>
director_name:    Director
pane:             <tmux_session>:<tmux_window_id>:<tmux_pane_id>
administrator:    <administrator_agent_id>

--json output — nested shape with administrator_agent_id at the top level alongside director:

{
  "fleet_id": 1,
  "label": "my-project",
  "created_at": "2026-04-15T10:00:00+00:00",
  "administrator_agent_id": 3,
  "director": {
    "agent_id": 2,
    "name": "Director",
    "description": "Root Director for this fleet",
    "registered_at": "2026-04-15T10:00:00+00:00",
    "placement": {
      "director_agent_id": null,
      "tmux_session": "main",
      "tmux_window_id": "@3",
      "tmux_pane_id": "%0",
      "coding_agent": "claude",
      "created_at": "2026-04-15T10:00:00+00:00"
    }
  }
}

placement.director_agent_id is null because the root Director has no parent. placement.coding_agent is the value of --coding-agent (default "claude"); operators running the codex CLI in the calling pane should pass --coding-agent codex so the placement metadata is accurate. cafleet does not spawn the root Director's coding-agent process and cannot auto-detect what is running in the calling pane.

Attempting cafleet --fleet-id <fleet_id> agent deregister --agent-id <director_agent_id> is rejected by the broker with Error: cannot deregister the root Director; use 'cafleet fleet delete' instead. and exits 1. Attempting cafleet --fleet-id <fleet_id> agent deregister --agent-id <administrator_agent_id> is rejected with Error: Administrator cannot be deregistered (exit 1).

fleet list¶

Lists all non-soft-deleted fleets with their director_agent_id, label, created_at, and active agent count. Soft-deleted fleets (fleets.deleted_at IS NOT NULL) are hidden.

Each row exposes the fleet's root director_agent_id so the Director's ID can be recovered from a list after fleet create output scrolls away. The --json output carries it as a director_agent_id field (integer). Text output renders it as a DIRECTOR column placed immediately after FLEET_ID:

FLEET_ID  DIRECTOR  LABEL       AGENTS  CREATED_AT
1         2         my-project  3       2026-04-15T10:00:00+00:00

fleet show¶

Shows details of a single fleet. Exits 1 with Error: fleet 'X' not found. if the row does not exist at all.

fleet show intentionally returns soft-deleted rows (to keep audit info reachable), so it succeeds on a soft-deleted fleet. When the row's deleted_at is non-NULL, the text output adds a deleted_at: line so callers can distinguish a soft-deleted fleet from an active one without parsing JSON:

fleet_id: <id>
label:      example
created_at: 2026-04-16T09:00:00+00:00
deleted_at: 2026-04-16T10:00:00+00:00

The --json output always includes deleted_at (null when active).

fleet delete¶

Soft-deletes a fleet in one transaction: it stamps the fleet as deleted, deregisters every agent that was active at the moment of deletion (root Director included), and removes their placement rows. Tasks are untouched — the message history remains queryable. Output:

Deleted fleet <fleet_id>. Deregistered N agents.

N counts every agent that was active at the moment of deletion (root Director included). On re-run against an already-deleted fleet, the command prints Deleted fleet <fleet_id>. Deregistered 0 agents. and exits 0 — the command is idempotent.

There is no --force flag. Calling fleet delete on an unknown fleet_id exits 1 with Error: fleet 'X' not found..

Member tmux panes spawned by cafleet member create are not automatically closed by fleet delete. For a clean teardown, call cafleet member delete per member first (which sends /exit to the pane). If a member pane refuses to close (e.g. blocked on a confirmation prompt), rerun cafleet member delete with --force, which kill-panes the target, sweeps the placement, and rebalances the layout.

cafleet doctor — Placement Diagnostics¶

Prints the calling pane's tmux session/window/pane identifiers (plus $TMUX_PANE) for operators diagnosing placement issues without reaching for raw tmux commands.

Environment requirements:

• TMUX env var must be set — the command rejects otherwise with Error: cafleet member commands must be run inside a tmux session (the same message used by cafleet member commands).
• TMUX_PANE env var must be set — already required for pane discovery.

Text output:

tmux:
  session_name:  main
  window_id:     @3
  pane_id:       %0
  TMUX_PANE:     %0

JSON output:

{
  "tmux": {
    "session_name": "main",
    "window_id": "@3",
    "pane_id": "%0",
    "tmux_pane_env": "%0"
  }
}

Exit codes:

cafleet server — Admin WebUI Server¶

Starts the admin WebUI FastAPI app (the same app served by mise //cafleet:dev) via uvicorn. CLI commands do not require this server to be running — it is only needed when a user wants to view the WebUI at / or hit the /api/* endpoints from a browser.

cafleet server does NOT require --fleet-id. Supplying --fleet-id is silently accepted and ignored, matching the db init / fleet * pattern.

Environment variables:

The CLI flag wins when both a flag and the matching env var are set; the env var wins when only it is set; the hardcoded default (127.0.0.1 / 8000) applies otherwise.

Behavior¶

• Runs uvicorn with its defaults — no reload, no custom workers, no custom log level.
• On startup, if the bundled WebUI dist directory does not exist, the app emits a one-line warning to stderr: warning: admin WebUI is not built. / will return 404. Run 'mise //admin:build'.. The warning fires from the app factory, so cafleet server, mise //cafleet:dev, and any direct uvicorn invocation all see it identically.
• Port-in-use errors are NOT wrapped — uvicorn's native OSError: [Errno 98] Address already in use (or the corresponding uvicorn traceback) propagates to the terminal.

No other flags¶

--reload, --workers, --log-level, and --webui-dist-dir are deliberately NOT exposed on cafleet server. Users who need them invoke uvicorn directly — which is exactly what mise //cafleet:dev does (it runs uv run --package cafleet uvicorn cafleet.webui.app:app --host 127.0.0.1 --port 8000 as an independent entry point, without delegating to cafleet server).

Examples¶

# Defaults: 127.0.0.1:8000
cafleet server

# Override via flags
cafleet server --host 0.0.0.0 --port 9000

# Override via env vars
CAFLEET_BROKER_HOST=0.0.0.0 CAFLEET_BROKER_PORT=9000 cafleet server

# --fleet-id is silently accepted and ignored
cafleet --fleet-id 1 server

cafleet agent — Agent Registry¶

All four subcommands require the global --fleet-id. The default-vs---full output projection shared by agent list and agent show is documented in --full semantics and is not restated per subcommand.

agent register¶

No identity flag — registering is how an agent obtains its id. Text output:

Agent registered successfully!
  agent_id:  <agent_id>
  name:      <name>

--json returns {"agent_id":<id>,"name":"<name>","registered_at":"<iso8601>"}.

agent deregister¶

Text output: Agent deregistered successfully.; --json returns {"status":"deregistered"}. The root Director and the Administrator are protected — see Error Messages.

agent list¶

No identity flag — the listing is scoped by the global --fleet-id alone. Default text output is one <agent_id> <name> <status> line per agent, blank-line separated; an empty fleet prints No agents found.:

2 Director active

3 Administrator active

4 demo-member active

agent show¶

Default text output is the same one-line <agent_id> <name> <status> row as agent list; the default --json projection additionally carries coding_agent when the target has a placement (see --full semantics).

cafleet message — Message Broker¶

All six subcommands require the global --fleet-id and act as --agent-id. The task envelope schema is canonical in Message envelope; body truncation and the --full / --quiet flags are canonical in Message Body Truncation — neither is restated per subcommand. The compact text render is [<id> | from:<from> | <ts>] on line 1 (plus kind / origin segments only when present) and the body on line 2.

message send¶

Text output is Message sent. followed by the compact rendered envelope; --quiet prints only the new task id.

message broadcast¶

Default text output is the one-line summary broadcast id=<task_id> recipients=<count>.

message poll¶

Returns only un-acked (input_required) deliveries addressed to the agent. Text output is the compact envelopes blank-line separated; an empty inbox prints No messages found..

message ack¶

Text output is Message acknowledged. followed by the compact envelope; --quiet prints only the task id.

message cancel¶

Text output is Task canceled. followed by the compact envelope.

message show¶

Text output is the compact envelope alone.

Member Commands¶

The cafleet member subgroup manages tmux-backed member agents and must be run inside a tmux session. member create takes --agent-id (the spawning Director's agent ID, validated to equal the fleet root); the other subcommands identify their target by --member-id, scoped to the global --fleet-id.

member create¶

Spawn command per backend¶

In all three modes the member's Bash tool is enabled and routine permission prompts auto-resolve — see Bash routing for the fallback protocol, and Codex members / Opencode members for backend-specific detail.

Spawn-prompt input modes¶

cafleet member create accepts the spawn prompt in three mutually exclusive shapes:

The substituted placeholders are fleet_id / agent_id / director_agent_id. For --prompt-file, relative paths, missing files, unreadable files, invalid UTF-8, and empty (zero-byte or whitespace-only) files all produce non-zero-exit errors — see the Error Messages table for the full surface. Inline prompts beyond a few KB exceed tmux's argv ceiling (tmux command failed: command too long rolls back the registration) — use --prompt-file for long prompts.

Focus behavior¶

The spawn always invokes tmux split-window with -d so the Director's pane and active window keep focus — the new member pane is created in the Director's window but is not made active.

Output format¶

Text (default) — one compact line; pane renders (pending) when the pane id has not been patched onto the placement yet:

<agent_id> <name> backend=<coding_agent> pane=<pane_id>

Text (hidden --full flag, accepted but not shown in --help) — 6-line block:

Member registered and spawned.
  agent_id:  <agent_id>
  name:      <name>
  backend:   <coding_agent>
  pane_id:   <pane_id>
  window_id: <window_id>

--json returns {"agent_id":<id>,"name":"<name>","registered_at":"<iso8601>","placement":{...}} where placement carries director_agent_id, tmux_session, tmux_window_id, tmux_pane_id, coding_agent, and created_at (the same shape as fleet create's director.placement).

member delete¶

The only boundary is fleet isolation: a --member-id that does not belong to --fleet-id resolves to None and exits 1 with Error: Agent <member-id> not found. There is no caller-auth check. Targeting the root Director is rejected early — before any tmux pane mutation — with Error: cannot deregister the root Director; use 'cafleet fleet delete' instead (exit 1); this prevents member delete --member-id <root-director-id> from injecting /exit into (or killing) the Director's own pane. Use cafleet fleet delete to tear down the fleet.

Polling contract (default path)¶

The default path sends /exit as two separate tmux send-keys invocations — literal /exit (-l), a 0.12 s gap, then Enter — because opencode's slash-command autocomplete popup needs the gap to settle before Enter submits. It then polls tmux list-panes -a -F "#{pane_id}" for the target pane every 500 ms until the pane disappears or a 15.0 s timeout elapses. A typical coding-agent /exit completes in 1–3 s; operators who need faster escalation pass --force. On timeout, the pane buffer tail (last 80 lines) is captured via tmux capture-pane and printed on stderr, followed by a recovery hint, and the command exits 2. The timeout output shape:

Error: pane %7 did not close within 15.0s after /exit.
--- pane %7 tail (last 80 lines) ---
<captured terminal buffer>
---
Recovery: inspect with `cafleet member capture`, answer any prompt with `cafleet member send-input`, then re-run `cafleet member delete`. Or re-run with `--force` to skip the wait and kill the pane.

Exit codes¶

member list¶

Lists every member of the fleet identified by the global --fleet-id. The root Director is never surfaced in the output.

member list --activity output¶

cafleet --fleet-id 1 member list --activity
3 members:
  agent_id        name      status  last_sent  last_recv  last_ack   idle
  --------------  --------  ------  ---------  ---------  ---------  -----
  4               alice     active  -          12:20:00   12:20:00   14m
  5               bob       active  12:30:11   12:33:02   12:33:02   2m
  6               carol     active  12:34:56   12:34:50   12:34:50   6s

last_sent is the member's most recent outgoing message; last_recv is its most recent delivery; last_ack is the most recent delivery it acknowledged (broadcast summaries excluded); idle is wall-time since the latest of last_sent / last_recv.

member capture¶

Member targeting and key delivery¶

member send-input, member exec, and member ping all target a member by --member-id (scoped to the global --fleet-id) and deliver keystrokes into that member's tmux pane. They share the resolution, key-delivery, and exit-code rules below; each subcommand's own section documents only its unique flags, key sequence, validation, and output.

Member resolution¶

1. Load the active in-fleet target. A cross-fleet, unknown, or inactive (deregistered) --member-id all resolve to "not found" and exit 1 with Error: Agent <member-id> not found. There is no caller-auth check beyond fleet membership.
2. If the agent has no placement row, exit 1 with Error: agent <member-id> has no placement row; it was not spawned via `cafleet member create`..
3. If the placement's pane id is None (pending placement), exit 1 — each subcommand uses its own "nothing to …" wording (see its section).

The only boundary is fleet isolation: any active in-fleet agent with a placement row (the root Director included) is a valid --member-id.

Literal key delivery¶

Each key sequence is delivered literally — shell meta ($VAR, backticks, $(...)), key names (Enter, C-c, Esc), backslash-escapes, and multi-byte characters all arrive as plain characters. The CLI runs each send-keys with shell=False, so no shell ever evaluates the text.

Common exit codes¶

member send-input¶

Forwards a restricted keystroke to a member's tmux pane. Two input modes, both AskUserQuestion-only — --freetext prepends the digit 4 (the "Type something" gate). For shell dispatch use member exec instead.

Exactly one of the two flags must be supplied.

Exactly one of --choice / --freetext must appear. Supplying zero or both exits 2 with Error: --choice and --freetext are mutually exclusive; supply exactly one..

Key sequence sent to the pane¶

Validation rules¶

Member resolution¶

Follows Member targeting and key delivery. On pending placement, exit 1 with Error: member <member_id> has no pane yet (pending placement) — nothing to send..

Output format¶

Text:

Sent choice 1 to member Claude-B (%7).
Sent free text to member Claude-B (%7).

JSON (cafleet --json ... member send-input ...):

{
  "member_agent_id": <id>,
  "pane_id": "%7",
  "action": "choice",
  "value": "1"
}

{
  "member_agent_id": <id>,
  "pane_id": "%7",
  "action": "freetext",
  "value": "<user text as-sent>"
}

Director-side usage pattern¶

The canonical three-beat workflow (member capture → AskUserQuestion → member send-input) lives in skills/cafleet/SKILL.md under "Answer a member's AskUserQuestion prompt". This page documents only the CLI surface.

member exec¶

Director-only shell-dispatch primitive. Keystrokes ! <command> + Enter into a member's pane so the coding agent's ! shortcut runs the command natively (bypassing the member's Bash tool permission system). All three backends (claude, codex, and opencode) honor the leading-! shortcut on their input line, so member exec works against any backend without modification. The fallback path for the bash-via-Director protocol — see Bash routing.

cafleet --fleet-id <fleet-id> member exec \
  --member-id <member-agent-id> "git log -1 --oneline"

Key sequence sent to the pane¶

Validation rules¶

(tmux-unavailable and binary-not-found errors are common — see Member targeting and key delivery.)

Member resolution¶

Follows Member targeting and key delivery. On pending placement, exit 1 with Error: member <member_id> has no pane yet (pending placement) — nothing to exec..

Output format¶

Text:

Sent bash command 'git log -1 --oneline' to member Claude-B (%7).

JSON (cafleet --json ... member exec ...):

{
  "member_agent_id": <id>,
  "pane_id": "%7",
  "command": "<command as-sent>"
}

Three keys: member_agent_id, pane_id, command.

Exit code summary¶

See Member targeting and key delivery for the common exit codes. The argument errors unique to member exec exit 2: missing positional COMMAND, command empty / whitespace-only, and command containing \n or \r.

member ping¶

Director-only manual inbox-poll nudge. Keystrokes cafleet --fleet-id <fleet-id> message poll --agent-id <member-id> + Enter into the member's pane so the member drains its inbox via a normal poll. This is the manual re-poke for a pane that missed the broker's automatic on-delivery notification — which keystrokes a 2-line inline preview (not a poll command) — so the two keystroke paths are distinct. As an operator-driven entry-point, failures surface as exit 1 (the auto-fire path swallows failures silently). The action is wholly determined by the subcommand name — there is no positional argument and no operator-controlled keystroke body, which is why this subcommand sits in permissions.allow while member exec stays in permissions.ask.

cafleet --fleet-id <fleet-id> member ping \
  --member-id <member-agent-id>

Key sequence sent to the pane¶

Validation rules¶

(tmux-unavailable and binary-not-found errors are common — see Member targeting and key delivery.)

The subcommand has no positional argument and no other flags.

Member resolution¶

Follows Member targeting and key delivery. On pending placement, exit 1 with Error: member <member_id> has no pane yet (pending placement) — nothing to ping..

Output format¶

Text:

Pinged member Claude-B (%7) — poll keystroke dispatched.

JSON (cafleet --json ... member ping ...):

{
  "member_agent_id": <id>,
  "pane_id": "%7"
}

Two keys: member_agent_id, pane_id. Failures surface via exit 1.

Exit code summary¶

See Member targeting and key delivery for the common exit codes. Unique to member ping: a missing --member-id exits 2, and a tmux send-keys failure exits 1 with Error: send failed: tmux send-keys did not deliver the poll-trigger keystroke to pane <pane>..

cafleet monitor — Supervision Scheduler¶

The cafleet monitor subgroup is the per-fleet scheduler that wakes due agents on a fixed cadence — the heartbeat behind a Director's supervision loop. All three subcommands require the global --fleet-id. start runs the loop in-process (a coding agent launches it as a background task and owns its lifetime); status and config view and edit the schedule. The conceptual model (heartbeat-vs-facilitation boundary, the director-vs-member ping split, the tick-precision floor, single-instance via the DB heartbeat) is canonical on the Monitoring concepts page; this page documents the CLI surface.

There is no monitor stop command and no detached process: the launching agent stops the loop by stopping its background task (or deleting the monitoring member), and the loop also self-terminates when the fleet is torn down. Launching/stopping the loop is CLI-only by nature; the schedule-view and schedule-edit surfaces are at WebUI/CLI parity (WebUI API).

monitor start¶

Runs the scan → ping due agents → heartbeat → sleep loop in-process via run_monitor_loop — a coding agent launches it as a background task (the loop blocks the task). On startup it runs the tmux precondition guard (the same TMUX-env check the member commands use), then atomically claims the single-instance monitor_runtime row, installs SIGTERM/SIGINT handlers (a clean stop clears the row), and loops until signalled or the fleet is torn down (monitor_tick returns STOP once the fleet is soft-deleted). There is no detached subprocess, no PID file, and no log file — the loop writes to the launching task's own stdout.

Every enrolled agent — Director and member alike — is pinged unconditionally once its interval has elapsed (the ping is not gated on the agent having pending inbox items; pending_count is informational, shown in status). The keystroke differs by role: the Director receives a bare cafleet … message poll, while a member receives a single-line resume nudge (the poll command plus a review-your-task-and-continue instruction), so a stopped member resumes rather than going idle on an empty inbox. Each dispatched ping is logged to stdout as <iso-ts> ping agent <id> (<name>), so the launching background task's output shows live heartbeat activity.

Exit codes: 0 clean exit (signalled, or the fleet was torn down); 1 already running (monitor already running for fleet N), unknown or soft-deleted fleet, or tmux unreachable; 2 click usage errors (e.g. --tick 0).

monitor status¶

No flags beyond the global --fleet-id. Reports runtime liveness derived from the DB heartbeat (true even when the process died silently) plus the per-agent schedule table.

Text output:

monitor: running (pid 4821, last tick 2s ago, tick 5s, started 2026-06-13T04:50:00+00:00)
  agent_id  name         role      interval  last_ping             enabled  pending
  --------  -----------  --------  --------  -------------------  -------  -------
  2         Director     director  60s       2026-06-13T04:51:00   yes      0
  4         alice        member    60s       -                    yes      2
  5         bob          member    30s       2026-06-13T04:50:30   no       0

When no monitor is running the first line reads monitor: stopped; the schedule table still renders. JSON output:

{
  "runtime": {"running": true, "pid": 4821, "tick_seconds": 5,
              "last_tick_at": "2026-06-13T04:51:02+00:00", "last_tick_age_seconds": 2,
              "started_at": "2026-06-13T04:50:00+00:00"},
  "agents": [
    {"agent_id": 4, "name": "alice", "role": "member", "interval_seconds": 60,
     "last_ping_at": null, "enabled": true, "pending_count": 2}
  ]
}

Exit 0 (2 for click usage errors). On an unknown or soft-deleted fleet, exit 1.

monitor config¶

With no edit flag, prints the agent's current config. With --interval / --enable / --disable, applies the update and prints the new config. Exits 1 if the agent is not in the fleet or not enrolled (the Administrator and card-only agents are never enrolled). --enable and --disable together exit 2.

Text output:

agent 4: interval 60s, enabled, last_ping 2026-06-13T04:51:00

JSON output: {"agent_id": 4, "interval_seconds": 60, "last_ping_at": "<iso8601>|null", "enabled": true}.

Error Messages¶