Command Reference
Generated from the live Typer registry by scripts/gen_cli_docs.py — do not hand-edit. Regenerate with uv run python scripts/gen_cli_docs.py after changing any CLI help string; scripts/gen_cli_docs.py --check fails CI on drift.
Complete reference for all docket commands, rendered from each command's own --help text so the CLI and this document can never drift apart.
Table of Contents
- Lifecycle Commands
- Session and Context Management
- Pod Coordination
- Telegram Integration
- Keys and Authentication
- Utility Commands
- Security and Audit
- Observability Commands
- Global Options
- Exit Codes
- Environment Variables
- Tips and Tricks
- Next Steps
Lifecycle Commands
list
Usage: docket list
List all project agents.
Shows every registered agent -- pod members for each project and the shared
org specialists (manager, knowledge, security) -- with role/pod, model and
its source, Telegram binding, and last activity. Telegram status reflects
docket's own channel bindings (~/.docket/fleet.json); the session column
shows the agent's current project key. --json emits the same listing as
one JSON document instead of the Rich table, for scripting.
init
Usage: docket init
Initialize the current project with its minimum isolated pod.
Creates a new project pod -- an isolated team of project-scoped agents that owns one codebase. The default pod is lean: a Lead + an Implementer. The first invocation also creates docket's shared workstation foundation (fleet registry, org specialists, policies, default gates) -- there is no separate setup step. See docs/AGENT-TEAMS.md.
With no arguments, docket derives the project id, path, and stack from the
current directory (non-interactive, deterministic). Member ids are
predictable: <project>-lead, <project>-implementer, <project>-reviewer,
<project>-tester (duplicated roles get -2, -3 suffixes). A pod
always has exactly one Lead. Resize a pod later with docket pod; tear
the whole pod down with docket delete.
Flags (parsed from the extra CLI args, not fixed Typer options):
--pod full provision Lead, Implementer, Reviewer, and Tester.
Only applies to the default software blueprint;
ignored (with a warning) for any other blueprint,
which provisions its own fixed roster.
--with software-only restriction as --pod full.
--blueprint software) provision a named pod
blueprint instead of the plain lean/full pod --
software (codebase, lead+implementer), research
(workdir, lead/researcher/analyst/writer/critic,
$20 default budget, Critic gates the final step
with one rework cycle), content (workdir,
lead/writer/critic, $15), ops (workdir,
lead/operator/monitor, $30, Operator gated on its
own verifyCmd, Monitor is a human-approval gate),
agentic-product (codebase, full software
roster). A codebase blueprint treats the location
argument as an existing, never-auto-created
codebase path and auto-detects its stack; a
workdir blueprint treats it as the pod's one
shared working directory instead -- no stack is
auto-detected. docket init always passes the
cwd (or an explicit --codebase/path) as the
location, so it never hits the auto-provisioned
~/.docket/workspaces/pods/<project>/ default;
that path is only reached via --from entries
that omit workDir or POST /pods calls that
omit path. Unknown
name errors with "unknown blueprint 'X'; valid
blueprints: software, research, content, ops,
agentic-product" and exits 1 before any prompt.
Only the five built-ins exist today -- there is
no docket blueprints add <file> to register a
custom one. See
specs/functional/pod-blueprints.spec.md.
--codebase path positional; supplying it
up front skips its interactive prompt.
--name .yaml/.yml needs PyYAML), the same
mechanism a CI job or fleet-bootstrap script would
use. The file is a bare list, {"agents": \[...\]},
or one entry object. Each entry needs an id; an
entry with a blueprint field provisions a pod
(fields: codebase/workDir, stack,
description, projectKey, budgetUsd,
telegram); an entry with no blueprint
provisions a single flat agent the same shape
docket add always has (fields: name,
codebase, stack, model, description,
telegram, budgetUsd, projectKey). Mutually
exclusive with every other flag/prompt. An entry
whose id already exists, or names an unknown
blueprint, is skipped with a warning rather than
failing the rest of the file -- the command
always exits 0, so check the printed summary
rather than only the exit code in a script.
--recipe docket recipes list
shows all of them). An unresolvable
name errors naming the shipped recipe names and
exits 1 before any provisioning. Mutually
exclusive with a present <location>/.docket/ --
giving both errors naming both sources and exits
1 before any provisioning.
--no-apply provision the pod only, skipping the apply step
for a present .docket/ or a resolved --recipe;
prints the docket pod <p> apply <dir> command
that would apply it.
A repository's own <location>/.docket/ -- the same directory shape
docket pod <p> apply reads (roles/.yaml, policies/.json,
pipeline.yaml, pod.yaml) -- is discovered automatically: every document
under it is validated before anything is provisioned, and applied after
(unless --no-apply) through that same command's plan/apply path. A
validation error exits 1 naming the file and field, with nothing
provisioned. See specs/functional/pod-blueprints.spec.md, "Pod manifests:
apply".
Every project is a repo -- a pod tied to a codebase, defaulting to the cwd
(or the path argument / --codebase, in which case you are not
re-prompted); the project name is suggested from that directory's name.
add
Usage: docket add
Add role agents to an existing project pod. Never creates a project.
Pod inferred from the current directory, or given explicitly with
--project <pod> when running outside the project's configured
codebase/workDir. Docket chooses the most-specific registered pod
containing the cwd and fails clearly when there is no match or the result
is ambiguous.
Flags (parsed from the extra CLI args, not fixed Typer options):
--project
status
Usage: docket status
Show current-project status, or every project with --all.
The current-project view shows state without mixing in the global agent
inventory or workstation health: configured path, readiness, pod roles,
and task counts. docket list remains the detailed global agent
inventory; docket doctor remains the global technical health check.
info
Usage: docket info
Detailed status of one agent.
Shows identity, codebase/stack, model and its source, session/project
keys, creation time, workspace path, and Telegram binding for one agent --
pulled from .docket-meta.json. With no agent id given, shows a numbered
picker.
delete
Usage: docket delete
Remove a project agent or a whole pod, and optionally its workspace.
Given a pod id, lists every member and (in an interactive terminal) requires typing the exact pod id to confirm, then removes every member's registration, binding, conversation-registry entry, workspace/worktree, pod runtime directory, durable session history, and traces. The global audit record is preserved. Given a legacy flat agent id, separately asks whether to also remove its workspace.
Cannot be undone -- back up first if unsure. Org specialists (manager, knowledge, security) cannot be removed this way -- the command errors outright rather than deleting a shared, fleet-wide agent. A deleted member's git worktree is removed, but its dedicated branch remains in the source repository so committed code is not silently destroyed; remove that branch separately after reviewing it.
maintain
Usage: docket maintain
Maintain an agent workspace (check/clean/reset/rebuild/sessions/distill).
Subcommands:
check (default) health check and auto-fix -- permissions (700/600),
missing workspace files, session-key sync between
.docket-meta.json and SOUL.md, memory directory,
and a per-turn context-footprint estimate (warns if
SOUL/AGENTS/TOOLS/HEARTBEAT/MEMORY together exceed
the configured token budget)
clean clear memory logs only (memory/*.md) -- distills
first by default (see below)
reset clear memory + MEMORY.md + HEARTBEAT.md -- distills
first by default
rebuild deep rebuild -- regenerate SOUL.md, AGENTS.md,
TOOLS.md from .docket-meta.json. Refuses a pod
member outright (its files are pod-provisioning's,
not this command's); never touches memory/
sessions report per-session message counts, on-disk size,
and last-active time for this agent -- sizes only,
no trimming or archiving
distill summarize memory/*.md into MEMORY.md via one
driver-backed turn, then archive the originals under
memory/<archive-dir>/
--no-distill-first (clean/reset only) skips the automatic pre-delete
distillation and deletes/clears memory undistilled.
Memory is never bare-deleted: before clean deletes memory/*.md, or reset
clears memory + HEARTBEAT.md, docket runs one driver-backed turn that
summarizes pending logs into MEMORY.md and archives the originals -- the
same work distill does standalone. A failed distillation aborts the
delete outright; nothing is touched. failure_kind (timeout,
daemon_error, invalid_output) tells you whether to just retry or
whether the model's output needs a closer look (daemon_error means the
turn didn't complete cleanly). When a reset runs a real distillation, MEMORY.md is
left freshly distilled rather than immediately cleared again in the same
breath.
Preserves identity (.docket-meta.json, fleet registration). clean/
reset/rebuild prompt for confirmation and require a TTY -- a
non-interactive call is cancelled, not silently applied.
Session and Context Management
scope
Usage: docket scope
Manage session scope / project isolation key.
Subcommands: show (default) prints the current scope and session key;
set <project-key> changes it; reset restores default. The session
key has the form agent:<id>:<project> and prevents cross-project
contamination between parallel work on the same agent; changing it
updates .docket-meta.json only -- it prints a reminder to update
SOUL.md yourself, it does not rewrite the file.
context
Usage: docket context
Agent context views (show/project) -- read-only.
There is no separate semantic memory index: docket's own turn loop has no
memory_search tool, so an agent (and this command) reads memory files
the same way it reads any other file -- context is just two dashboards.
Subcommands: show (default) the last 3 memory-log files (last 5 lines each), active tasks parsed from HEARTBEAT.md, and quick stats (memory-log count, session size from docket's own durable per-session storage, last-active timestamp) project a project-metadata-focused view -- codebase path, stack, model, session key, active tasks, and MEMORY.md section headers
Both subcommands are read-only and touch only the named agent's own
workspace; any other action exits 2. Use docket snapshot for a
whole-fleet JSON export.
persona
Usage: docket persona
Set/clear an agent's optional display persona (docket-owned; rendered into SOUL.md).
Identity of record is the agent's role; a persona is only a display skin docket controls -- never a self-authored IDENTITY.md.
Subcommands: (show, default) current persona + role; set "<label>"
assigns a display name; clear removes it (back to role/name).
Stored in .docket-meta.json (persona) and rendered into SOUL.md;
survives maintain rebuild. Use this command to give an agent a
friendly name.
Pod Coordination
pod
Usage: docket pod
Manage a project's pod: list members, add/remove a role, set an implementer's verify command, and run its dispatch pipeline.
A pod is the isolated team of project-scoped agents created by
docket init; pod <project> add <role> extends an existing one. Every
member has its own permission-locked workspace, so no role is ever
shared between projects. See docs/AGENT-TEAMS.md.
Subcommands:
list (default) show the pod's members and their roles
add docket roles), not a hardcoded
implementer|reviewer|tester list -- a blueprint role
or any user-defined archetype works too. The Lead
is unique and cannot be added this way. Duplicated
roles get -2, -3 ids. --count/-n adds several
at once. --verify "<cmd>" sets the mechanical
verification gate dispatch runs after that member's
hop -- written into the new member's
.docket-meta.json (verifyCmd) and documented in
its TOOLS.md; passing it for a non-implementer role
is silently ignored with a warning, since only an
Implementer hop is verify-gated. A new member
inherits the pod's workspaceKind/workDir/blueprint
from its existing members.
remove pod.set-verify); runs at dispatch
time in the Implementer's git worktree when one
exists, falling back to the pod's shared codebase
root, then the member's own workspace dir.
config [get|set core.pod.PodSettings): budgetUsd, maxReworkCycles,
turnTimeoutS, verifyTimeoutS. get (default) shows
each key's effective value and whether it is set or
default; --json emits the same as a bare object --
see cli-json-shapes.spec.md. set validates before
writing (an invalid value exits 1, nothing persisted)
and audit-logs pod.config; unset removes an
override, falling back to the built-in default. A
stored value that fails validation (e.g. a hand-edited
.docket-meta.json) refuses config get and
dispatch alike, naming the key, instead of silently
substituting the default.
delegate dispatch.
queue [--retry --retry moves one blocked task back
to pending -- the explicit, single-task way around a
reached budget cap (docket profile <lead-id>
--budget/--resume un-blocks every task in the pod
at once instead).
dispatch [--resume] [--timeout --resume also reclaims any task
a prior dispatcher left failed with a stale claim
or as dispatch_refused (a deterministic refusal
settled mid-task), and counts a still-running
task as work so the stale-claim sweep can judge it,
continuing from its last persisted hop. --timeout
overrides both the agent-turn timeout and the
verifyCmd timeout for this run only (otherwise each
falls back to the pod's own configured timeouts,
then a 300s default).
sync [--dry-run]. Re-render SOUL.md/AGENTS.md/TOOLS.md for
every member whose managed files have drifted from
the current archetype and stored metadata (a
template bump, or a role's own archetype content
changing). --dry-run prints the diff without
writing; without it, each stale member is rewritten
and its metadata restamped (audit-logged as
pod.sync). INSTRUCTIONS.md is operator-owned and
is never read, written, or diffed by this command --
an already-current pod changes nothing.
apply [pipeline.yaml, and a small
pod.yaml naming members/settings/pipeline) to
this pod in one command, composing the same writers
roles add/add <role>/config set pipeline/
config set <key> <value> already use. A directory
path if one exists there, else a shipped recipe name
(docket recipes list) as
init --recipe resolves it; default <codebase>/.docket. Validates
everything -- roles, the roster the pipeline would
resolve against once members join, and every
setting -- before writing anything; an invalid
manifest exits 1 naming the problem with nothing
written. Idempotent: applying the same directory
twice plans every item skip the second time and
writes nothing. --dry-run prints the plan without
writing. Audit-logged once as pod.apply, only when
something actually changed.
export [roles/*.yaml, this pod's own policies/*, a
bound pipeline.yaml copy (if any), and a pod.yaml
naming non-Lead members and every non-default
setting -- into <dir>, the same shape apply
reads back. <dir> defaults to <codebase>/.docket,
like apply. Global scope (the operator's own role
overlay, fleet-wide policies, other pods) is never
exported. Refuses a non-empty <dir> unless
--force, which overwrites any same-named file
already there. Audit-logged as pod.export.
Dispatch guarantees: budget-gated with real auto-pause (checked before
each hop against the Lead's cap; over budget leaves the task blocked and
pauses the pod's Lead until docket profile <project>-lead --resume); a
timed-out or daemon-error hop retries in place (linear backoff, small
per-role budget) before failing, a real non-zero exit or bad verdict is
never retried; a Reviewer's REQUEST-CHANGES sends the task back to the
Implementer for one rework cycle (default) before a second rejection
fails it; a set verifyCmd runs in the Implementer's git worktree when one
exists; every hop/retry/gate outcome/claim/sweep event is traced
(docket trace) on a per-task session; every invocation creates a
queryable docket runs record; dispatch only ever targets the project's
own pod -- there is no cross-pod dispatch path. See
specs/functional/pod-dispatch.spec.md.
pipeline
Usage: docket pipeline
Validate, plan, and run a docket-native pipeline -- the one dialect docket actually executes.
A pipeline file declares a pod's hop order, gates, and rework edges instead of relying on the built-in default order.
Subcommands:
validate run/docket pod <p> dispatch
use internally, not a second pretty-printer. Never
executes anything or spends tokens. Without --file,
resolves the pod's zero-migration default order
(lead -> implementer -> reviewer -> tester,
whichever roles the pod has).
run docket pod <project> dispatch, so it is equally
budget-gated, verify/Reviewer/Tester-gated, traced,
and recorded in docket runs. --resume/--timeout
behave identically to pod dispatch. Repeatable --var
key=value supplies the pipeline's variable
namespace (the same one a webhook dispatch resolves
from its JSON body); a step's own instructions may
reference ${key}, and a missing required
variable or an unresolved ${key} reference
refuses the run before any hop. --follow tails the
run's trace events live in the foreground (Ctrl-C
stops watching, not the dispatch itself, which
keeps running).
Pipeline file schema (YAML or JSON; unknown keys rejected): name
(required), description, variables (a name->{default, description,
required} map, resolved at dispatch time against --var/a webhook body);
steps: each has id (unique), exactly one of role (a role-archetype
slug) or agent (a specific member id), optional retries, timeout
(seconds), optional instructions (overrides the target role's own hop
instruction for this step; may reference ${var}), optional gate, or
a parallel list of child steps (one nesting level). gate.type:
mechanical (a command, or null to defer to the target's own
verifyCmd), verdict (a pattern regex, passValues, optional
rework: {to, when, maxCycles} edge back to an earlier step), or
approval (a human sign-off message).
A pod with no pipeline file runs the built-in default order -- declaring
a pipeline is opt-in. archetype references inside a step are
shape-validated only, never checked against the live role registry. See
specs/functional/pipeline-format.spec.md.
roles
Usage: docket roles
Manage declarative role archetypes: list/show/add/validate.
A role archetype is the data-driven definition behind every pod role
(lead, implementer, reviewer, tester, and the blueprint-only roles
researcher, analyst, writer, critic, operator, monitor) -- SOUL/AGENTS
templates, model class, gate contract, token budget -- not a hardcoded
branch, so docket pod <p> add <role> accepts any name in this registry.
Subcommands:
list (default) all archetypes (built-in + user-defined) with source,
scope, model class, gate, and description
show ~/.docket/docket-roles.json)
-- built-ins are never edited, only shadowed by name
validate [file] structural field validation (closed enums, name
regex, non-blank templates) plus a dry-run render of
both templates against a representative variable set
-- catches a template referencing an unknown ${var}
before add persists it. With no file argument,
validates every entry in the merged live registry
instead.
Built-ins and the 6-role starter library are Python literals, never
loaded from files; a user archetype in ~/.docket/docket-roles.json
overlays by name, and a malformed overlay entry is skipped rather than
crashing a live fleet. See specs/functional/role-archetypes.spec.md.
recipes
Usage: docket recipes
List and inspect the recipe library.
Subcommands: list \[--json\] prints every recipe reachable by name --
the operator's own ~/.docket/recipes/<name>/ before the shipped
library, nearest scope wins -- with its derived kind (team/policies/
pipeline/mixed) and description. show <name|dir> \[--json\] prints one
recipe's description, scope, directory, derived summary, and README
body. Installs, removes, or fetches nothing; docket pod <p> apply/
docket init --recipe remain the only writers.
Telegram Integration
wire
Usage: docket wire
Wire or update a channel group binding (Telegram by default).
Inbound only: the binding authorizes a chat to send /approve, /deny, /status and /delegate; docket never messages the group on its own -- there is no notification on a pending approval and no report when a task finishes, you poll with /status.
With TELEGRAM_BOT_TOKEN configured, docket shows a one-time command such
as /wire A1B2C3 -- send it in the Telegram group, return to the
terminal, and press Enter, and docket discovers and binds that group
automatically. You can paste a numeric group ID instead; manual entry is
also the fallback when the bot token is missing, Telegram cannot be
reached, or no matching message is found.
--channel <name> (default telegram) selects which channel to wire; the
flag exists so additional channels can be added without a breaking
change to this command's syntax, though Telegram is the only one shipped
today.
Updates docket's own fleet registry (~/.docket/fleet.json) bindings,
and seeds an entry in the conversation registry (docket conversations).
The binding is the entire authorization boundary once
docket serve --telegram is running: anyone who can post in that chat
can act as this agent. Guided discovery reads the matching one-time
/wire message without advancing the Telegram poller's durable offset or
processing unrelated messages -- if docket serve --telegram is already
polling, stop it during setup so it does not receive the one-time
command first.
unwire
Usage: docket unwire
Remove a channel binding (Telegram by default).
--channel <name> (default telegram) selects which channel binding to
remove. Removes the entry from docket's own fleet registry
(~/.docket/fleet.json); the agent can still function without it, but
approvals then require CLI, HTTP, or MCP interaction.
conversations
Usage: docket conversations
Inspect and resume the conversation registry (list/show/resume/set/prune).
docket's durable index of channel threads: docket's own turn loop keeps no durable transcript of its own, so this registry tracks which agent handles each thread, its topic, status, and a resume pointer.
Subcommands: list (default) all tracked conversations; show <id|
agent-id> full detail for one; resume <id|agent-id> marks it
in_progress and prints a resume brief; set <agent-id> <peer-id>
\[--topic\] \[--status\] \[--last\] \[--task\] edits an entry directly;
prune \[--dry-run\] \[--days N\] deletes done conversations past the
retention window (default TRACE_RETENTION_DAYS) -- the same pruning
docket serve's periodic sweep already does.
Auto-seeded when you docket wire an agent to a channel; cleaned up on
docket delete. status is one of active | in_progress | waiting |
done. Durable conversation content lives in the agent's HEARTBEAT.md +
memory/ (resumed on its next turn via the durability contract); this
registry tracks state only.
Keys and Authentication
keys
Usage: docket keys
API key management (add/list/remove/rotate/validate/export/setup).
Docket's model client reads keys centrally.
Subcommands:
list (default) masked table of stored keys with a format badge and
the date added
add sk-ant- and be >= 40 chars); no name
validates everything; exit 1 on any failure
export prints export NAME='value' lines (unmasked,
shell-quoted) for every stored key, for
eval "$(docket keys export)"
setup interactive wizard (requires a TTY) through
every credential the provider catalog declares,
in catalog order, one at a time
Stored in ~/.docket/secrets.json (values, 0600) and
secrets.meta.json (added/rotated timestamps) -- docket-owned JSON,
written through edges/store.py. Recognized provider keys:
ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_AI_API_KEY, OPENROUTER_API_KEY,
AI_GATEWAY_API_KEY, VERCEL_OIDC_TOKEN, GROQ_API_KEY, MISTRAL_API_KEY,
XAI_API_KEY, CEREBRAS_API_KEY, HUGGINGFACE_TOKEN. The runtime reads a
selected provider's stored credential directly -- exporting is optional.
Under DOCKET_SECRETS_BACKEND=keyring, add/rotate store the value in the
OS keyring (secret-tool) instead of secrets.json, which then keeps only
a name index; remove clears the keyring entry too.
Utility Commands
logs
Usage: docket logs
View an agent's latest memory log.
Prints the most recent memory/YYYY-MM-DD.md file's first 40 lines (with
a note if there are more). Memory logs are the durable, docket-owned
activity record. For active tasks, read
HEARTBEAT.md directly (docket edit <id>) or use
docket context <id> show. Shows the single latest file only, not a
rolling tail across days -- use tail -f on the file directly for live
monitoring. Memory logs rotate daily.
edit
Usage: docket edit
Open agent workspace files in $EDITOR.
Opens SOUL.md (identity and session key), AGENTS.md (delegation rules),
TOOLS.md (project commands), HEARTBEAT.md (active tasks), and
.docket-meta.json (metadata). Respects $EDITOR, falling back to vi if
unset. Be careful editing .docket-meta.json by hand -- use
docket maintain <id> check to fix drift afterward.
profile
Usage: docket profile
Pin or unpin an agent's model; set a budget cap; resume from auto-pause.
Every agent follows its role's policy model by default
(modelSource: policy). Pinning (modelSource: pinned) detaches it --
policy and preset changes will no longer touch it.
With no model argument, shows the current model, role, source, and
budget. A provider/model argument pins it; default re-attaches it to
the role policy. --budget <USD> sets a per-agent spend cap (0 = none).
--resume clears an auto-pause (e.g. a reached budget cap) -- when the
target is a pod's Lead it also un-blocks that pod's blocked tasks so
dispatch can claim them again, and writes a profile.resume audit entry.
A model argument must be a full provider/model id; docket models
shows and sets the role policy.
models
Usage: docket models
View and edit the role->model policy -- the single place that decides which model each kind of agent runs on.
Built-in defaults put high-volume/low-reasoning roles (manager, reviewer, tester, knowledge) on the cheap model class and reasoning-dense roles (programmer, security, repo) on the strong class.
Subcommands: (bare) show the role->model policy with pricing and why;
set <role> <provider/model> change one role's model, or
set default <provider/model> the fallback; preset \[name\] list or
apply a provider preset from the catalog (anthropic (default), openai,
google, openrouter-free (experimental zero-cost router), openrouter,
ai-gateway (Vercel), local (no API key, priced at $0 (local)) among
others) -- a built-in hosted preset needs only its credential, never a
separate registration; reset restore built-in defaults (asks for
confirmation); provider <action> manage the provider catalog: add
<file.yaml> a kind: provider document, or the shortcut add <name>
<base-url> \[--model ID\] \[--ctx N\] \[--max-tokens N\] \[--credential NAME\]
(registration verifies <base-url>/models with the resolved credential
and classifies the result -- only a transport failure refuses; every
HTTP status registers, with a warning when it is not a clean 200);
list every provider (name, scope, dialect, base URL, credential);
show <name> \[--json\] one entry; remove <name> a global override
(a built-in with none refuses); export <name> \[<file>\] its document.
Policy changes are live: every policy-following agent is re-resolved
immediately; pinned agents (docket profile <id> <model>) are never
touched. Overrides persist in ~/.docket/docket-models.json (roles:
map); delete it or run reset to restore built-ins -- reset prompts
Continue? \[y/N\] and a non-interactive call that can't answer aborts
rather than silently resetting the fleet. Applying a preset also writes
its own economy/standard/premium anchors, re-resolves every
policy-following agent, and prints a readiness line naming the preset's
credential as present or missing. Unknown models are accepted if
well-formed (provider/model) -- an id absent from the catalog only
surfaces the first time an agent actually calls the endpoint; pricing
shows n/a (or "n/a (bring your own)" for an OpenRouter/AI Gateway route
other than the explicit free router, and "$0 (local)" for a
local/ollama/lmstudio provider -- never a fabricated dollar figure).
An invalid model prints the current role policy table alongside the
error.
cost
Usage: docket cost
Token usage and cost breakdown, with per-agent budget caps and runaway-session detection.
With no agent id, aggregates all agents; with one, shows its own
breakdown. --json emits machine-readable output for either form.
--history shows a per-day cost breakdown instead of the current
totals; --days N (default 0 = no limit) restricts --history to the
last N days.
Token counts (input/output/cache read/cache write, turns) are real and
measured -- reported by the model endpoint per call and accumulated by
docket's own session storage. The dollar total is not: docket's own turn
loop (DocketDriver) reports no billed spend at all, so Total cost
always reads as "none recorded for these sessions" rather than a dollar
figure -- a known, plainly-stated gap, not a bug, because converting a
token count into a dollar figure is exactly the estimate-to-billing-claim
conversion docket refuses to make inside this command. See
docket models for a comparative, clearly-labelled estimate (never
presented as billed spend), and the same estimate's use by the
budget-auto-pause gate. docket does not print a projected "savings if
you switched models" figure either -- that would compound one estimate
on top of another. --history/--days currently return no rows against
the production driver: per-day breakdowns aren't tracked by docket's own
session store (a session's usage is one running total for its lifetime,
not timestamped per turn) -- a documented, known limitation. The pricing
table (docket models) is a manual snapshot, not a live feed, and is
not surfaced inside this command. Useful for detecting runaway sessions
by turn count; budget management works off the token-based estimate the
pod-dispatch gate itself computes, not this command's dollar column.
doctor
Usage: docket doctor
System-wide health check and diagnostics, with an optional auto-fix pass.
--json emits a machine-readable health probe instead of the Rich
report; --fix applies auto-fixes for detected drift (permission
repairs, missing workspace files, session-key resync) -- this mutates
state.
Runs (in order): required dependencies (python3); per-project agent
workspace/registration/binding checks; model validity across every
registered agent; the dispatch task ledger (TASK_LIST.json vs. the pod Lead's
HEARTBEAT.md dispatch ledger must agree -- a mismatch prints exactly
which task ids are missing/stale, and --fix re-syncs the ledger, always
safe since TASK_LIST.json is dispatch's own source of truth); budget-cap
sanity and runaway-session detection; key hygiene and provider coverage;
security-gate configuration; template/runtime-contract version (reseeds
a missing or stale WORKFLOW_AUTO.md).
doctor is diagnostic-only by default; --fix is not read-only -- it
mutates workspace files and permissions to correct detected drift.
Review its findings before running with --fix on a workspace you
haven't backed up.
config
Usage: docket config
Read-only inspection of an agent's effective configuration.
Subcommands:
explain
serve
Usage: docket serve
Local HTTP endpoints: /status.json /metrics /health.
Binds to 127.0.0.1 (loopback-only) -- not reachable off this host. With
--dispatch, each refresh also runs every pod's queue through the
Lead->Implementer->Reviewer->Tester pipeline. Each hop is a real agent
turn and is budget-gated; leave it off for a read-only monitor. With
--telegram, also polls docket's own Telegram bot so a chat bound via
docket wire can /approve, /deny, /status, /delegate or /answer -- idle until a
bot token is stored.
-p/--port <N> (default 7331) binds a port -- 127.0.0.1 only, never
reachable off the host. -i/--interval <seconds> (default 30) sets
the sweep refresh interval. --token-file <path> writes the bearer
token needed for /approvals, /dispatch, and /runs to a 0600 file instead
of printing it to stdout.
HTTP endpoints while running: GET /status.json, /metrics, /health (no
auth); GET /approvals, POST /approvals/ , GET
/runs/ Plain Usage: Shell completion helpers. Prints a shell-completion script for bash or zsh. With no argument,
prints usage/install instructions. Only bash and zsh are supported (no
fish) -- an unknown shell name errors with exit 1. The top-level command-name list is generated live from the real Typer
command registry, so it can never drift from Usage: Validate role, pipeline, policy, and pod configuration documents. With no argument, validates Usage: Export system state snapshot as JSON. Every project agent and specialist, its model, registration/binding
status, last activity, and measured cost, plus the channel list. Usage: Expose the control plane as an MCP server ( "Rent the protocol": external tools are configuration, not code. Subcommands:
serve expose docket's own control plane as an MCP server over
stdio, so an external MCP client (an IDE, another agent
runtime) can inspect and drive the fleet through typed
tool calls instead of shelling out to the CLI. Requires
the optional [mcp] extra ( Its tools are reachable from a live turn: the client namespaces them
Usage: Show docket's tool-call gate and manage workspace isolation. The tool-call gate itself -- the policy engine plus the argument-aware
high-risk command classifier, both evaluated in Subcommands:
status (default) reports that the tool-call gate is always active,
plus the workspace-isolation mode
isolate on|off records whether tool execution runs inside a
sandbox (opt-in, off by default). Any other subcommand prints usage and exits 2. Approvals are answerable
headlessly via Usage: Show the audit log, or verify its tamper-evidence chain. A durable, append-only, tamper-evident record of docket-initiated
mutations (key changes, gate toggles, profile pins, scope changes,
agent/pod add/delete, persona changes, etc.). With no argument, shows the last 20 entries (human-readable); Stored at Usage: Manage tool-approval policies. Manages declarative guardrail policies evaluated on each agent turn. Subcommands: A policy file that fails validation is never silently skipped: every
call it could have governed fails closed ( Usage: List predicate plugins an operator has applied. Subcommand: Usage: Approve a pending tool-action. Grants a pending HITL approval token from docket's own approval store
($APPROVALS_DIR). With no token, lists pending approvals; with a token,
grants it. Token format: apr-. Returns exit 1 if the token is not
found, or if you resolve it to the opposite verdict from what it already
has; re-resolving to the same verdict it already has is treated as an
idempotent no-op -- a warning, but exit 0. An apr- token is created by
docket itself, from an in-turn Usage: Deny a pending tool-action. Denies a pending HITL approval token from docket's own approval store
($APPROVALS_DIR). With no token, lists pending approvals; with a token,
denies it. Same token format, idempotency, and provenance rules as
Usage: List everything across every pod that needs you: waiting/blocked tasks and pending
approvals, plus failed/done/running context. Usage: See and answer one task's parked question. Usage: Inspect the dispatch run registry (list/show/cancel/prune) -- one record per invocation. One persisted record per pod-dispatch invocation, whatever triggered it
(the CLI, the Subcommands: A run record's Usage: View agent execution traces. Every dispatch hop emits a JSONL trace event; use this to inspect them.
Subcommands: Traces are stored at Usage: Show session success-rate and drift metrics. Computes success rate, latency, cost, and guardrail trip counts from
trace data. Usage: Run one agent, one turn, to completion, for a caller-owned workspace and home. Refuses (exit 2, one Usage: Observability export destinations: list, inspect, and enable by authenticating. Subcommands: Usage: Notification/conversation/decision destinations: list, inspect, and enable. Subcommands: Usage: Flush operator events to every enabled channel. Show Typer's auto-generated help for Syntax: Show help. With no topic, docket's full hand-written command reference (common
commands and the current role->model policy) -- richer than
Syntax: Aliases: None Show the installed docket version. Syntax: No command emits any other exit code today. There is no environment kill switch for the audit log — a prior If you have fzf installed, omit the agent-id for fuzzy search: Use bash loops for batch operations: Track daily costs: Regular backups:docket runs show <id>) for the outcome.docket serve never dispatches and never polls Telegram; both are
opt-in. Read-only by default, so it's safe to leave running for
monitoring. --dispatch spends real budget; over-budget tasks are left
blocked, not run. Per-task dispatch is traced (docket trace) for
auditability.
completions
docket completionsdocket --help.
Second-level subcommand words (e.g. gates status isolate
classes) are hand-maintained in the completion templates, since those
subcommands are parsed manually rather than being Click subgroups --
only the top-level command list is regression-tested against drift, so
hand-maintained subcommand words for pipeline, conversations,
runs, and persona can and have drifted out of sync with their real
subcommands.
validate
docket validate<cwd>/.docket if it exists, else the current
directory. A directory argument validates every roles/*.yaml|yml|json,
policies/*.yaml|yml|json, pipeline.yaml, and pod.yaml found under it;
a file argument validates that one file. Prints one line per file -- ok
<file> (<kind> <name>) or its error -- with invalid files listed first,
plus a note: line for a file loaded without a top-level kind: key.
Exits 1 if any file is invalid.
snapshot
docket snapshot-o/
--output <path> writes the JSON to a file instead of stdout.
costUsd/totalCostUsd are 0.0 for the same reason docket cost shows
no recorded spend today:
this is a snapshot of measured-token agents, not of billed dollars.
Useful for backups, dashboards, or feeding fleet state into another
tool.
mcp
docket mcpmcp serve), or configure external MCP tool servers (mcp servers).pip install 'docket\[mcp\]' or
uv sync --extra mcp) -- prints an install hint to stderr
and exits 1 if missing. Transport: newline-delimited
JSON-RPC 2.0 on stdin/stdout -- no HTTP, no bind address,
no bearer token; the trust boundary is whoever can spawn
the process. Exposes 13 tools (every call audit-logged as
mcp.<tool>): status, pods, queue, delegate, dispatch,
runs, approvals_list, approvals_grant, approvals_deny,
task_answer, task_pregrant, inbox, cost -- each mirrors the
equivalent CLI/HTTP path through the exact same core/ function, no
parallel logic, no auto-approve. dispatch creates a run
record and returns its id immediately, then runs the
pipeline in the background -- poll runs for the outcome.
servers list/add/remove external MCP tool servers (stdio transport)
so their tools become available to an agent's turn, gated
by the same pre_tool_call policy and dispatch_tool
chokepoint as any built-in -- a remote server can never
shadow bash/read/write/edit/glob/grep. add <name>
\[--env K=V ...\] \[--timeout S\] \[--kind read|write\]
\[--tools NAME,NAME,...\] \[--no-isolate\] -- <command>
\[args...\]: everything after -- is passed to the server
verbatim as its launch command and arguments; the options
must come before --. Tools register as
mcp__<name>__<tool>. --kind declares the server's
trust level (default: write) -- a role that denies write
gets no tools from a server left at the default, but does
get tools from one declared --kind read, since docket's
role narrowing excludes by tool kind, not by name.
--tools restricts registration to a comma-separated
allow-list of that server's own tool names (default: all).
A stdio server starts inside the turn's sandbox (its
roots and network mode) while isolation is on;
--no-isolate is the audited assertion that it must run
on the host.mcp__<server>__<tool>, and the turn loop folds them into the registry
before gating and before per-role narrowing, so a Reviewer (or any role
that denies write) never gets a write-capable MCP tool no matter what a
configured server advertises. docket mcp alone prints usage and exits
0; an unrecognized subcommand exits 1. A tool call's own success/failure
is expressed inside the MCP protocol (isError), never as a process exit
code. Configured servers persist in
~/.docket/docket-mcp-servers.json (docket-owned JSON); env values are
masked when listed. Every mcp servers add/remove is audit-logged.
See specs/functional/mcp-client.spec.md and specs/api/mcp-server.spec.md.
Security and Audit
gates
docket gatescore/tools.py's
dispatch_tool chokepoint on every call docket's turn loop makes -- is
always active and cannot be turned off. An "ask" verdict sits in
docket's own approval store, answerable identically by the CLI, HTTP,
MCP, and Telegram channels.on needs
bubblewrap (Linux) or a running docker; it probes
bwrap, then docker -- errors, exit 1, if neither is
usable. Enforced on the live
turn: with isolation on, DocketDriver runs tools
sandboxed (bwrap or docker), and refuses the whole
turn -- audited as isolation.refused -- when no
backend is usable, rather than running it
unsandboxed.
network none|open records whether jailed tool calls may reach the
network (default open). none drops bwrap's
--share-net / adds docker's --network none, and
refuses any turn that would run with isolation
off -- audited as network.refused. A pod's
network setting can only narrow it. fetch
is untouched (its domain allowlist stays).
classes lists the built-in high-risk action classes
(HIGH_RISK_PATTERNS in core/security.py) --
money-movement, prod-deploy, and secret-access --
wired onto every bash call docket's turn loop
dispatches: the whole command line, including
every segment behind a ;/&&/||/pipe, is
classified before a call is allowed to run, so
git push origin production asks even though
git itself stays on the curated allowlist
(git status does not). A pod's verifyCmd
separately refuses a matching command outright
before the shell starts; a hop's real output is
scanned for a match on the way through the
pipeline (flagged, not blocked, by itself).
Read-only; the pattern list is not yet
user-configurable.docket approve/docket deny or POST
/approvals/<token> (docket serve), or MCP, in addition to Telegram --
all four channels are audit-logged. See
specs/functional/security-gates.spec.md.
audit
docket audit\[N\]
shows the last N; --json dumps the raw audit.log JSONL file verbatim;
verify walks the hash chain and reports the first broken link (exit 1)
or that it verified clean (exit 0).~/.docket/audit.log -- one JSON object per line (seq, ts
(millisecond resolution), user, pid, action, detail, prev_hash), never
containing secret values. Every line chains to the previous one via a
SHA-256 prev_hash (stdlib hashlib, no new dependency); verify detects a
hand-tampered line, and a line without seq/prev_hash is a break.
Rotates to a single-generation audit.log.1 backup once past
AUDIT_LOG_MAX_BYTES (default 5 MiB, env-overridable); the first entry
after a rotation claims continuity, and verify checks that claim
against the backup. Best-effort and never raises; there
is no environment kill switch -- recording cannot be silently disabled.
Always exits 0 for the listing forms (malformed lines are skipped, not
fatal); verify exits 1 on a detected broken chain link.
policies
docket policieslist installed policies; show <name> prints one
policy's JSON; init copies the 6 baseline templates
(block-destructive, prompt-injection, secret-pii-redact, and the three
high-risk-action-class policies: high-risk-payment, high-risk-deploy,
high-risk-credentials); validate \[id|file.json\] schema-checks one (or
every) installed policy, including that its regex compiles; test <hook>
<role> <text> \[--tool <name>\] dry-runs the evaluator, emitting no
traces. Valid <hook> values for test are pre_input, pre_tool_call,
and pre_output -- a policy can fire at enqueue time, before a tool call,
or on a hop's output. For pre_tool_call, --tool (default bash) names
the built-in tool being simulated: an exec tool is judged by the command
classifier plus the policy hook, exactly like the live gate; any other
kind is judged by the policy hook alone, because the live gate
classifies exec commands only.block, attributed to the
file) until it is fixed or removed, and docket doctor reports it.
plugins
docket pluginslist \[--pod <p>\] prints every predicate a policy's when:
{plugin: ...} can reach -- global (~/.docket/plugins/) then that
pod's own config/plugins/, each with its scope, file and sha256.
Docket never loads a plugin from a codebase; docket pod <p> apply is
what copies a recipe's plugins/*.py into pod scope.
approve
docket approveask verdict on a tool call
(dispatch_tool, blocking that call until answered), a pod-dispatch hop
held on a requireApprovalRoles/pipeline approval step, or a task a
guardrail policy flagged at enqueue. This store is the only approval
mechanism, and
docket approve/docket deny (plus the HTTP and MCP equivalents, and a
Telegram reply in a wired chat) are the only ways to answer it, each
audit-logged with the channel that answered. See also docket deny.
deny
docket denydocket approve -- see its help for the full contract.
inbox
docket inboxdocket inbox \[--json\] \[--since <iso>\] \[--peek\]. A plain call advances a durable cursor so a
repeat call's Done section only shows newly-terminal tasks; --peek reads without
advancing it, and --since <iso> overrides the stored cursor for one call without touching
it either. --json emits the same shape docket serve's GET /inbox returns.
chat
docket chatdocket chat <task-id> \[--pod <project>\] -- searches every pod for task-id (or just
pod when given), then shows its brief, its pending question (if any) and its earlier
answers. On a TTY, a pending question is followed by one prompt per schema property and
then answered through the same core.answers.answer_task every other surface calls
(channel="cli", actor=<OS user>). Off a TTY, or with no pending question, this only
ever displays -- use docket pod <p> answer to answer non-interactively.
Observability Commands
runs
docket runsdocket serve webhook, a due schedule, or the sweep loop).
Answers "is it done, did it fail, or did it never run" for background
dispatch, whose failures are otherwise invisible.list \[--project <project>\] \[--json\]; show <run-id>
\[--json\]; cancel <run-id> persists one cancellation request and
signals every in-flight hop process group -- queued work is terminal
immediately, a running record stays "running (cancel requested)" until
the executor observes the request and fully stops, then the task and run
become cancelled; writes one audit entry; in-process backend work
already executing returns to a safe checkpoint, where its late response
is discarded before any tool or later pipeline hop can start. prune
\[--dry-run\] \[--days N\] deletes terminal (succeeded/failed/cancelled)
records past the retention window (default TRACE_RETENTION_DAYS) --
the same pruning docket serve's periodic sweep already does; queued
and running records are never touched.source is one of cli|webhook|schedule|sweep|mcp;
state is one of queued|running|succeeded|failed|cancelled. A failed
run carries the exception text in error. Persisted to
~/.docket/docket-runs.json. show and both JSON read surfaces expose
cancellation requestedAt/observedAt/stoppedAt; a missing stop timestamp
means the executor has not fully returned yet. POST /dispatch/<project>
(see docket serve) returns {"run": "GET /runs/<id> and GET /runs?project=
mirror this command over HTTP (Bearer-authed, same as /approvals).
trace
docket trace<session-id> renders one session human-readable; tail
<project> follows the latest open session live; export <project>
\[--since DATE\] is a raw JSONL passthrough; ingest <project> projects
docket's own session store into the trace store.~/.docket/traces/<project>/<session-id>.jsonl.
Each dispatch hop writes events such as tool_call, cost_charged,
approval_requested.
metrics
docket metrics-r/--role filters to a specific agent role; -p/
--project to a specific project; -w/--window N (default 50,
METRICS_WINDOW env-overridable) sets the rolling window size in
sessions. Output: success rate, duration (mean/p95), cost (total/mean),
and guardrail trip counts.--escalation prints escalation metrics instead: task starts (dispatch claims),
operator questions by kind and outcome, and decision latency.
harness
docket harnessrun --workspace DIR (--task TEXT | --task-file PATH) --model
PROVIDER/ID \[--role implementer\] \[--timeout S\] \[--agent-id ID\] executes
synchronously and streams newline-delimited JSON events on stdout,
finishing with exactly one versioned result object -- see
docs/adr/0001-harness-mode.md and specs/api/harness-mode.spec.md for
the full wire contract. stdout carries only that NDJSON; every log goes
to stderr.result with status: refused) unless DOCKET_HOME
is set to a caller-owned directory (never the operator's own default
home), DOCKET_LLM_BASE_URL is set, DOCKET_NO_TRACE is unset, and
--workspace is a real directory -- this command never touches the
operator's own approvals or audit log. Approval mode is fixed to
non-interactive refusal: a tool call that would otherwise wait for a
human is denied immediately as blocked rather than hanging for up to
two minutes. On SIGTERM it persists a cancellation request, kills any
in-flight tool subprocess's process group, and exits with a cancelled
result. Exit codes: 0 the run's result is ok; 1 it ended failed,
blocked, or cancelled; 2 refused before any run started -- the one
named exception to this CLI's flat 0/1 convention.status TOKEN reports whether a run token from a prior run invocation
is live, finished (with a best-effort reconstructed result), or
unknown.
exporters
docket exporterslist \[--json\] prints every catalog exporter's dialect,
activation state, credential names and its privacy level (SHARES). show
<name> \[--json\] prints one exporter's effective document, source, state,
health counters and a "Leaves this host" disclosure of every content
class. enable <name> \[--endpoint URL\] \[--privacy <level>|--share a,b\]
\[--events ...\] \[--no-verify\] \[--yes\] prompts for a missing credential on
a TTY (else names docket keys add and exits), probes the endpoint, and
writes only the enabled flag plus the overrides given. disable <name>
turns it back off; stored keys are kept. test <name> re-probes without
changing anything. add <file.yaml> \[--no-verify\] \[--yes\] and remove
<name> manage a full document; export <name> \[<file>\] prints or writes
one back out. privacy <name> \[<level>|--share a,b\] \[--max-chars N\]
\[--yes\] shows or changes what an exporter shares beyond bare structure;
widening the shared classes prints what is newly granted and the
destination host, then asks for confirmation on a TTY or refuses off one
without --yes -- narrowing never asks. preview <name> \[--session <id>\] \[--level
<level>|--share a,b\] \[--json\] projects a local session through the
exporter's policy and prints what it would send -- no network call, no
write.
channels
docket channelslist \[--json\] prints every catalog channel's dialect,
enabled state, capabilities and content level. show <name> \[--json\]
prints one channel's effective document and scope. enable <name> \[--set
k=v ...\] writes only the enabled flag plus the overrides given (--set
actors=a,b sets the actors list, --set secret=NAME sets the credential
name, anything else lands in config); it refuses without writing when a
required field the built-in names is still empty (ntfy needs a
non-empty topic, telegram needs a non-empty actors). disable
<name> turns it back off. add <file.yaml> and remove <name> manage a
full document; export <name> \[<file>\] prints or writes one back out.
content <name> \[<level>\] \[--yes\] shows or changes how much a delivery
carries (minimal < actions < conversation); widening prints the change
and asks for confirmation on a TTY or refuses off one without --yes --
narrowing never asks. test <name> sends one synthetic
dev.docket.channel.test event through that one channel and reports
success or failure -- useful to verify a webhook URL or a command binary
before relying on it. Every other subcommand here only edits the catalog;
test and docket notify are the only things in this command group that
ever send anything.
notify
docket notifydocket serve's sweep and docket pod <p> dispatch already flush after every real
state change; this command forces one in between, or previews it. docket notify
flush \[--dry-run\] -- with no --dry-run, diffs the inbox against the last flush,
delivers each new event (dev.docket.task.*/approval.*) to every enabled channel
whose on matches, and prints the counts; --dry-run prints what would be sent
without delivering or advancing the dedupe snapshot.
Global Options
--help / -h
docket or any subcommand.docket --help
docket -h
docket <command> --help
help
docket --help's auto-generated command list; always exits 0. With a
topic, that command's own usage text (exit 0), or an unknown-command
error naming it (exit 1).docket help
--version / -V
docket --version
docket -V
Exit Codes
Code
Meaning
0
Success (includes
approve/deny re-resolving a token to the verdict it already has)
1
Error (generic; also used by
approve/deny on an unknown token or one being flipped to the opposite verdict, and docket init's missing-dependency check)
2
Usage/refusal error: Typer's own automatic response to a missing or invalid argument,
docket harness run's --workspace/--task/preflight refusal, or an unrecognized flag or subcommand on a manually parsed command (e.g. gates, context, maintain)
Environment Variables
Variable
Description
Default
DOCKET_HOMERoot of everything docket owns — the only state root; no external daemon directory exists
~/.docket
TRACES_DIRRoot of per-session trace JSONL files (
docket trace)$DOCKET_HOME/traces
POLICIES_DIRRoot of installed/edited policy JSON (
docket policies, docket gates)$DOCKET_HOME/policies
PLUGINS_DIRRoot of operator-applied predicate plugins (
docket plugins, a policy's when.plugin)$DOCKET_HOME/plugins
SKILLS_DIRThe operator's own Agent Skills, the outermost of the three scopes
core.skills.discover_skills reads$DOCKET_HOME/skills
APPROVALS_DIRWhere
docket approve/deny's approval-token store lives$DOCKET_HOME/approvals
CORRECTIONS_DIRPer-pod append-only ledger of operator decisions and rejections (
docket pod <p> corrections)$DOCKET_HOME/corrections
SCHEDULE_FILEThe persisted pod schedules (
docket pod <p> config set schedule)$DOCKET_HOME/docket-schedules.json
RUNS_FILEThe persisted dispatch-run registry — one record per
dispatch_pod invocation$DOCKET_HOME/docket-runs.json
SESSIONS_DIRRoot of durable per-session turn history (
core/session.py)$DOCKET_HOME/sessions
MCP_SERVERS_FILERegistry of configured external MCP tool servers (
docket mcp servers)$DOCKET_HOME/docket-mcp-servers.json
PROVIDERS_FILEGlobal provider catalog scope (
docket models provider add, core/provider.py)$DOCKET_HOME/docket-providers.json
EXPORTERS_FILEGlobal exporter catalog scope (
core/exporter.py)$DOCKET_HOME/docket-exporters.json
EXPORTERS_HEALTH_FILEPer-exporter delivery counters and last-error state (
core/exporter.py::read_health)$DOCKET_HOME/exporters-health.json
CHANNELS_FILEGlobal channel catalog scope (
core/channel.py)$DOCKET_HOME/docket-channels.json
NOTIFY_STATE_FILEcore/notify.py::flush's dedupe snapshot, so two flushes over the same state deliver each event once$DOCKET_HOME/notify-state.json
CHANNELS_HEALTH_FILEPer-channel delivery counters and last-error state (
core/notify.py::flush)$DOCKET_HOME/channels-health.json
FLEET_FILEAgent registration, channel bindings, gate/isolation flags, org default model
$DOCKET_HOME/fleet.json
AUDIT_LOG_MAX_BYTESAudit-log rotation threshold (
docket audit)5242880 (5 MiB)
SESSION_TIMEOUTAge past which an expired approval is denied (fail-closed)
3600
APPROVAL_TIMEOUTThe async approval-gate window (
core/dispatch.py's require_approval) — a task waits waiting_approval; no process or turn is blocked on it900
TOOL_APPROVAL_TIMEOUTThe in-turn approval wait (
core/approval.py's wait_for_approval) — blocks a live tool call, so it is far shorter than APPROVAL_TIMEOUT120
TOOL_APPROVAL_POLL_INTERVAL_SHow often the in-turn approval wait re-checks the record while blocked
2
CLAIM_STALE_TIMEOUTA pod task claimed longer than this without finishing is presumed crashed and failed by the dispatch sweep
1800
METRICS_WINDOWRolling terminal-session count for
docket metrics50
RUNAWAY_TURNS_THRESHOLDPast this many turns,
docket doctor/docket cost flag a session as runaway200
RUNAWAY_COST_THRESHOLDPast this estimated USD,
docket doctor/docket cost flag a session as runaway20
DOCKET_KEY_MAX_AGE_DAYSdocket doctor's key-hygiene report flags a stored secret STALE past this age — a rotation nudge, never an expiry90
TRACE_RETENTION_DAYSHow long a terminated trace file survives before
docket trace expire deletes it30
EXPORT_QUEUE_MAXBound on the in-memory span queue the background exporter sender drains
1000
EXPORT_FLUSH_TIMEOUT_SPer-flush wall-clock bound for the background exporter sender
5.0
TEMPLATE_VERSIONWorkspace-prompt schema version;
docket doctor flags older agents for rebuild past a bump4
CONTEXT_BYTES_PER_TOKENBytes-per-token estimator behind the static-context guards in
docket maintain check4
CONTEXT_TOKEN_BUDGETSoft cap on the static per-turn context (SOUL+AGENTS+TOOLS+HEARTBEAT+MEMORY.md);
docket maintain check warns past this6000
DISTILL_TIMEOUT_SWall-clock bound on
docket maintain distill's one driver-backed turn120
DISTILL_MAX_INPUT_BYTESHow much daily-log content goes into a distillation turn's prompt
49152 (48 KiB)
DISPATCH_RETRIES_DEFAULTRetry attempts after the first try for a retryable dispatch-hop failure (timeout/
daemon_error only), for any role with no per-role override2
DISPATCH_RETRIES_LEAD, DISPATCH_RETRIES_IMPLEMENTER, DISPATCH_RETRIES_REVIEWER, DISPATCH_RETRIES_TESTERPer-role override of
DISPATCH_RETRIES_DEFAULTsame as
DISPATCH_RETRIES_DEFAULT
DISPATCH_RETRY_BACKOFF_SLinear backoff base between retries — attempt N waits N times this many seconds
2
DISPATCH_RETRY_MAX_WAIT_SCeiling on a retry's sleep, whichever of the linear backoff or the endpoint's own
Retry-After asked for longer60
DISPATCH_TURN_TIMEOUT_Sdocket serve-only ceiling on a dispatch hop's turn timeout, overriding a pod's own Lead-meta value for serve-triggered dispatchesunset (no serve-wide override)
DISPATCH_SWEEP_WORKERSdocket serve --dispatch: how many pods one sweep tick runs at once (1 is serial)4
DISPATCH_VERIFY_TIMEOUT_SSame as
DISPATCH_TURN_TIMEOUT_S, for the verify stepunset (no serve-wide override)
AGENT_LOOP_MAX_ITERATIONSHard cap on model round-trips within one turn
20
AGENT_LOOP_MAX_TOOL_CALLSHard cap on total tool calls dispatched across one turn
40
AGENT_LOOP_NO_PROGRESS_ROUNDSStops a turn after this many consecutive tool rounds that only repeat earlier results;
0 disables3
AGENT_LOOP_MAX_CONSECUTIVE_TOOL_DENIALSStops a denial-only loop before it consumes the iteration/tool/token limits
3
DOCKET_TOOL_MAX_OUTPUT_CHARSCeiling on one tool result's text before it is visibly truncated — tune down for a small-context endpoint
30000
AGENT_LOOP_WALL_CLOCK_TIMEOUT_SDefault overall wall-clock budget for one turn with no explicit
LoopConfig300
AGENT_LOOP_TOKEN_BUDGETHard cap on one turn's cumulative measured token usage
100000
AGENT_LOOP_REQUEST_TIMEOUT_SPer-HTTP-call timeout passed to the chat backend
120
MCP_CLIENT_TIMEOUT_SDefault per-call bound for an MCP server with no timeout of its own
10
MCP_CLIENT_MAX_TIMEOUT_SHard ceiling every server-specified MCP timeout is clamped to
60
FETCH_ALLOWED_DOMAINSComma-separated exact hostnames the
fetch tool may reachempty (nothing allowed until opted in)
FETCH_MAX_RESPONSE_BYTESResponse-body cap for the
fetch tool before truncation200000
FETCH_TIMEOUT_SDefault per-call wall-clock bound for the
fetch tool15
TELEGRAM_POLL_TIMEOUT_SThe Telegram-side long-poll wait passed to
getUpdates25
TELEGRAM_REQUEST_TIMEOUT_SThis process's own socket timeout for Telegram calls — must exceed
TELEGRAM_POLL_TIMEOUT_S35
DOCKET_SECRETS_BACKENDStored-secret backend:
file (default, secrets.json) or keyring (secret-tool/libsecret)file
DOCKET_KEYRING_SERVICEThe libsecret service name secrets are stored under when
DOCKET_SECRETS_BACKEND=keyringdocket-cli
DOCKET_NO_TRACESet to
1 to disable trace-store writesunset (tracing on)
DOCKET_NO_EXPORTSet to
1 to disable every export queue/flush actionunset (export on)
DOCKET_SANDBOX_IMAGEImage for the Docker exec-jail (
docket gates isolate on)alpine:3.20
DOCKET_SANDBOX_BACKENDForce or disable the sandbox backend (
docker/bwrap/none) regardless of what is actually installedauto-detected (docker > bwrap > none)
EDITORText editor for
docket edit, checked before VISUALnano
VISUALFallback text editor for
docket edit when EDITOR is unsetnano
DOCKET_SERVE_TOKENFix
docket serve's bearer token instead of generating one per rununset (random)
DOCKET_LLM_BASE_URLProcess-wide override that points every model at one endpoint (local dev, tests without stored config)
unset
DOCKET_LLM_API_KEYProcess-wide API key override, paired with
DOCKET_LLM_BASE_URLunset
ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_AI_API_KEY, OPENROUTER_API_KEY, AI_GATEWAY_API_KEY, VERCEL_OIDC_TOKEN, GROQ_API_KEY, MISTRAL_API_KEY, DEEPSEEK_API_KEY, XAI_API_KEY, CEREBRAS_API_KEY, TOGETHER_API_KEYPer-provider API key, named by a built-in provider document's
auth.credentials (core/provider.py's catalog), checked when neither DOCKET_LLM_API_KEY nor a catalog-resolved credential is already present; also checked against docket's own secret store (docket keys add). A provider absent from the catalog falls back to <PROVIDER>_API_KEYunset
DOCKET_CLI_ROOTRepo root override used by the
bin/docket launcher to select which project to uv run againstpackage/launcher location
DOCKET_PYTHONExplicit interpreter for
bin/docket to exec (e.g. a Homebrew venv)unset (auto-resolved)
DOCKET_NO_AUDIT escape hatch was removed because it let anyone silently disable docket's only tamper record; audit writes are unconditional and best-effort (a write failure never raises, but it also can't be turned off).
Tips and Tricks
Interactive Pickers
docket info # Opens fzf picker
docket delete # Opens fzf picker
docket logs # Opens fzf picker
Batch Operations
# Reset all agents
for id in $(docket list | awk '{print $1}' | tail -n +2); do
docket maintain "$id" clean
done
# Cheaper models fleet-wide: change the policy once — every
# policy-following agent updates automatically (pins are untouched)
docket models preset openrouter-free
Cost Monitoring
# Add to crontab
0 23 * * * docket cost >> ~/docket-costs-$(date +%Y-%m).log
Backup Strategy
# Backup script
#!/bin/bash
tar -czf ~/backups/docket-$(date +%s).tar.gz \
~/.docket/fleet.json \
~/.docket/workspaces/
# Or a single-file fleet snapshot
docket snapshot -o ~/backups/fleet-$(date +%s).json
Next Steps