Agen
Reference / CLI reference

Reference

CLI reference

Fleet commands talk to the Hub in --hub/--token (or AGEN_HUB/AGEN_TOKEN), else to the local agen up.

agen — run and manage agent fleets

Platform:
  agen up                         Hub + local Nest in one process (SQLite)
  agen down                       stop a running 'agen up' (drains instances)
  agen ui                         sign-in link for the web UI
  agen hub serve                  run a Hub
  agen nest run --hub URL         run a Nest Manager
  agen migrate --to URL           copy the local store into Postgres (distributed)
  agen store host-role            create the least-privilege Postgres role for Nests

Fleet (client of the Hub; --hub/--token or AGEN_HUB/AGEN_TOKEN, else the local config from agen up):
  agen init [dir]                 write a template bundle to start from (--template NAME; --list)
  agen deploy <bundle-dir>        create or update a deployment (--validate: check only)
  agen scale <name> <n>           set desired instances
  agen ps [--all]                 deployments (--all: every instance on every nest)
  agen logs <name> [-f]           operational logs
  agen stop <name>                stop all instances and hold at zero (paused)
  agen start <name>               resume a stopped deployment
  agen rm <name>                  delete a deployment
  agen run <name> <input>         submit a task and wait for its result
  agen wait <task-id>             wait for a task submitted earlier and print its result
  agen cancel <task-id>           cancel a task (a running one stops; --mode graceful gives it a last turn first)
  agen pause <task-id>             hold a task (a running one suspends at its next model call)
  agen resume <task-id>            end a hold started by agen pause
  agen call <name> <text>         A2A message to the deployment (wakes it if asleep)
  agen tasks [name]               recent tasks (--scheduled: waiting for their start time)
  agen providers [resume ACCT]    provider accounts held after an account error
  agen mcp workspace --root DIR  a built-in MCP tool server: files and a shell in one folder
  agen mcp sql [--dsn-env NAME]  a built-in MCP tool server: read-only SQL
  agen runs [name]                recent runs (--roots: one per trace, --status, --label)
  agen trace <task-id|trace-id>   span tree of a trace, across agents
  agen tree <task-id>              every task of the tree it belongs to
  agen query <task-id>             its progress, current activity and outcome, without waiting on it
  agen transcript <run|task>      what a run sent to the model and got back, tool calls included
  agen replay <run>                re-run a recorded run offline, from its saved cassette (needs recordInteractions on)
  agen eval <bundle-dir>           run scenario files against a bundle with mocked tools, report pass@1/pass^k
  agen events [name] [-f]         the event log: tasks, approvals, budgets, warnings (--type, --label)
  agen feedback record <task> --score S   record a judgement on how a task went (0.0-1.0)
  agen feedback ls [name]         feedback, newest first (--label, --since)
  agen memory set <id>            durable text an agent reads and updates (value on stdin)
  agen memory ls                  memory blocks in the namespace
  agen artifacts get <id>         an artifact an agent saved with save_artifact
  agen artifacts ls [task]        artifacts in the namespace, or one task's
  agen triggers <name>            trigger events (fired, missed, rejected)
  agen webhook-secret <name> <trigger>  create/rotate a webhook secret
  agen secret set|ls|rm           platform secrets (bundle secrets with source "platform")
  agen resolve <name>             A2A endpoints of a deployment and a call token
  agen nests                      enrolled nests
  agen approvals | approve <id> | deny <id>
  agen notify set|ls|rm           where the Hub POSTs a namespace's events
  agen join-token                 one-time token for 'agen nest run'
  agen token create --scope S     API token
  agen whoami                     the current token's identity and scopes
  agen version

agen up

Usage of up:
  -capacity int
    	local nest capacity (0 = unlimited) (default 8)
  -gateway-listen string
    	local Gateway (A2A) listen address (default "127.0.0.1:7071")
  -host-bin string
    	agen-host executable
  -listen string
    	Hub listen address (default "127.0.0.1:7070")
  -retention duration
    	delete spans, log lines and trigger events older than this (0 keeps them) (default 720h0m0s)
  -store string
    	store URL (default: sqlite in AGEN_HOME)

agen down

usage: agen down

agen ui

Usage of ui:
  -ca-hash string
    	pin the Hub CA of an https Hub
  -hub string
    	Hub URL
  -json
    	print the API response as JSON
  -n string
    	namespace (default "default")
  -token string
    	API token

agen hub serve

Usage of hub serve:
  -listen string
    	listen address (default "127.0.0.1:7070")
  -nest-cert-lifetime duration
    	lifetime of Nest client certificates (default 30 days; Nests renew before expiry)
  -retention duration
    	delete spans, log lines and trigger events older than this (0 keeps them) (default 720h0m0s)
  -store string
    	store URL (sqlite:<path> or postgres://...)
  -tls
    	serve HTTPS with the Hub CA; Nests enrol with certificates (mTLS)
  -tls-host value
    	extra host name or IP for the Hub certificate (repeatable)

agen nest run

Usage of nest run:
  -backend string
    	where instances run: native (child processes) or kubernetes (pods; run the nest in a pod) (default "native")
  -ca-hash string
    	pin the Hub CA (from 'agen join-token') for an https Hub
  -capacity int
    	maximum instances (0 = unlimited) (default 8)
  -cert-renew-before duration
    	mTLS: renew the Nest certificate when less than this remains (default 10 days)
  -data-dir string
    	nest state directory (default: AGEN_HOME/nests/<name>)
  -gateway-auth string
    	required: A2A callers need a Hub-signed call token; optional: anonymous callers allowed (loopback gateways only) (default "required")
  -gateway-listen string
    	Gateway listen address (default "127.0.0.1:7071")
  -gateway-url string
    	public URL of this nest's Gateway (default: from --gateway-listen)
  -host-bin string
    	agen-host executable
  -host-env value
    	pass this variable from the nest's environment to every instance, e.g. a provider key (repeatable)
  -host-env-dir string
    	pass each file in this directory (name = variable, content = value; e.g. a mounted secret) to every instance
  -host-memory-limit string
    	native backend: cap each agent host's memory, e.g. 1GiB (Windows job limit, Linux RLIMIT_AS)
  -hub string
    	Hub URL
  -join-token string
    	one-time join token (first start only)
  -kube-cpu-limit string
    	kubernetes: CPU limit per instance pod (default "1")
  -kube-image string
    	kubernetes: image with agen-host for instance pods
  -kube-memory-limit string
    	kubernetes: memory limit per instance pod (default "1Gi")
  -kube-namespace string
    	kubernetes: namespace for instance pods (default: the nest pod's)
  -label value
    	nest label key=value (repeatable)
  -manager-listen string
    	ManagerService listen address for host callbacks (kubernetes default 0.0.0.0:7072)
  -manager-url string
    	URL hosts use to reach ManagerService (kubernetes default http://$POD_IP:<port>)
  -name string
    	nest name (default: hostname)
  -store string
    	store URL given to instances for run data
  -store-for value
    	NAMESPACE=URL: store URL for that namespace's instances, e.g. a role limited to it (repeatable)
  -store-for-only
    	run only namespaces that have a --store-for entry (no fallback to --store)

agen migrate

Usage of migrate:
  -from string
    	source store URL (default: the local agen up store)
  -to string
    	target store URL, empty (e.g. postgres://user:pass@host/db)

agen store

usage: agen store host-role --store postgres://<admin>@host/db [--role agen_host]  (password from AGEN_HOST_DB_PASSWORD)

agen init

Usage of init:
  -example string
    	same as --template
  -fallback string
    	comma-separated models to try when the model keeps failing ("none" clears them)
  -json
    	with --list: print the templates as JSON
  -list
    	list the templates
  -max-tier string
    	highest cost tier a task may ask for (routing models)
  -model string
    	OpenRouter model instead of the template's (a routing model such as typesafe/jev-router picks the model per request)
  -template string
    	template to start from: hello, researcher, writer, editor, pr-reviewer, fleet-steward, approval-triage, assistant, coder, ci-fixer, support, incident-responder, data-analyst (default "hello")
  -tier string
    	default cost tier for a routing model: low, medium, high (xhigh, max for openrouter/auto)

agen deploy

Usage of deploy:
  -ca-hash string
    	pin the Hub CA of an https Hub
  -eval-runs int
    	runs per scenario for --require-eval (default 1)
  -host-bin string
    	agen-host executable, for --require-eval (default: next to agen, $AGEN_HOST_BIN, or on PATH)
  -hub string
    	Hub URL
  -json
    	print the API response as JSON
  -n string
    	namespace (default "default")
  -name string
    	deployment name (default: bundle name)
  -replicas int
    	desired instances after deploying (default -1)
  -require-eval
    	run the bundle's eval scenarios first (agen eval) and refuse to deploy unless every one passes (2.43)
  -scenarios string
    	eval scenarios directory for --require-eval (default: x-agen/evals inside the bundle, if present)
  -token string
    	API token
  -validate
    	check the bundle and print warnings without deploying

agen scale

Usage of scale:
  -ca-hash string
    	pin the Hub CA of an https Hub
  -hub string
    	Hub URL
  -json
    	print the API response as JSON
  -n string
    	namespace (default "default")
  -token string
    	API token

agen ps

Usage of ps:
  -A	all namespaces
  -all
    	list every instance on every nest, in all namespaces
  -ca-hash string
    	pin the Hub CA of an https Hub
  -hub string
    	Hub URL
  -json
    	print the API response as JSON
  -n string
    	namespace (default "default")
  -token string
    	API token

agen logs

Usage of logs:
  -ca-hash string
    	pin the Hub CA of an https Hub
  -f	follow
  -hub string
    	Hub URL
  -instance string
    	only this instance
  -json
    	print the API response as JSON
  -limit int
    	lines (default 200)
  -n string
    	namespace (default "default")
  -token string
    	API token

agen stop

Usage of stop:
  -at agen start
    	hold-runs only: end the hold at this time (RFC 3339, e.g. 2026-10-18T09:00:00Z), instead of waiting for agen start
  -ca-hash string
    	pin the Hub CA of an https Hub
  -hold-runs
    	also hold every unfinished task of the deployment, not just stop leasing new ones
  -hub string
    	Hub URL
  -in duration
    	hold-runs only: end the hold this long from now (e.g. 30m)
  -json
    	print the API response as JSON
  -n string
    	namespace (default "default")
  -reason string
    	hold-runs only: why, for anyone who looks at a held task later
  -token string
    	API token

agen start

Usage of start:
  -at agen start
    	hold-runs only: end the hold at this time (RFC 3339, e.g. 2026-10-18T09:00:00Z), instead of waiting for agen start
  -ca-hash string
    	pin the Hub CA of an https Hub
  -hold-runs
    	also hold every unfinished task of the deployment, not just stop leasing new ones
  -hub string
    	Hub URL
  -in duration
    	hold-runs only: end the hold this long from now (e.g. 30m)
  -json
    	print the API response as JSON
  -n string
    	namespace (default "default")
  -reason string
    	hold-runs only: why, for anyone who looks at a held task later
  -token string
    	API token

agen rm

Usage of rm:
  -ca-hash string
    	pin the Hub CA of an https Hub
  -hub string
    	Hub URL
  -json
    	print the API response as JSON
  -n string
    	namespace (default "default")
  -token string
    	API token

agen run

Usage of run:
  -at string
    	run no earlier than this time (RFC 3339, e.g. 2026-10-18T09:00:00Z)
  -ca-hash string
    	pin the Hub CA of an https Hub
  -conversation string
    	continue the conversation of earlier tasks with this key
  -delivery string
    	override the conversation's queue mode for this submission only: followup, collect, steer or interrupt
  -expires-in duration
    	fail as expired if still queued this long from now, instead of waiting indefinitely
  -hub string
    	Hub URL
  -idempotency-key string
    	resubmitting the same key returns the same task
  -in duration
    	run no earlier than this long from now (e.g. 30m)
  -json
    	print the API response as JSON
  -label value
    	label the task, key=value (repeatable)
  -lock value
    	wait until this (and every other --lock) is free, then hold it until the task ends (repeatable)
  -n string
    	namespace (default "default")
  -no-wait
    	print the task id and return
  -on-parent-end string
    	what happens to this task's own children when it ends: cancel (default) or abandon
  -priority string
    	lease order within the deployment's queue: urgent, high, normal or background
  -schedule-key string
    	at most one queued task per deployment and key; submitting again with the same key cancels the queued one
  -tier string
    	cost tier for a routing model: low, medium, high, xhigh or max
  -timeout duration
    	how long to wait for the result (0: no limit); the task keeps running after it (default 10m0s)
  -token string
    	API token
  -trust string
    	a trust at most this high: operator, trusted or untrusted (default: the token's own)

agen wait

Usage of wait:
  -ca-hash string
    	pin the Hub CA of an https Hub
  -hub string
    	Hub URL
  -json
    	print the API response as JSON
  -n string
    	namespace (default "default")
  -timeout duration
    	how long to wait (0: no limit)
  -token string
    	API token

agen cancel

Usage of cancel:
  -ca-hash string
    	pin the Hub CA of an https Hub
  -grace duration
    	mode=graceful only: how long to wait for a last turn before stopping anyway (default 20s, capped at 5m)
  -hub string
    	Hub URL
  -json
    	print the API response as JSON
  -mode string
    	hard (default): stop at once. graceful: give each run a last turn to call finish before stopping it
  -n string
    	namespace (default "default")
  -token string
    	API token
  -tree
    	cancel every unfinished task of its whole tree (its root and every descendant), not just this one

agen pause

Usage of pause:
  -at agen resume
    	end the hold at this time (RFC 3339, e.g. 2026-10-18T09:00:00Z), instead of waiting for agen resume
  -ca-hash string
    	pin the Hub CA of an https Hub
  -hub string
    	Hub URL
  -in duration
    	end the hold this long from now (e.g. 30m)
  -json
    	print the API response as JSON
  -n string
    	namespace (default "default")
  -reason string
    	why, for anyone who looks at the task later
  -token string
    	API token
  -tree
    	hold every unfinished task of its whole tree (its root and every descendant), not just this one

agen resume

Usage of resume:
  -ca-hash string
    	pin the Hub CA of an https Hub
  -hub string
    	Hub URL
  -json
    	print the API response as JSON
  -n string
    	namespace (default "default")
  -token string
    	API token
  -tree
    	end the hold on every task of its whole tree, not just this one

agen call

Usage of call:
  -ca-hash string
    	pin the Hub CA of an https Hub
  -hub string
    	Hub URL
  -json
    	print the API response as JSON
  -n string
    	namespace (default "default")
  -timeout duration
    	request timeout (default 5m0s)
  -token string
    	API token

agen tasks

Usage of tasks:
  -ca-hash string
    	pin the Hub CA of an https Hub
  -hub string
    	Hub URL
  -json
    	print the API response as JSON
  -limit int
    	tasks (default 20)
  -n string
    	namespace (default "default")
  -scheduled
    	only tasks waiting for their start time
  -state string
    	only tasks in this state: queued, running, succeeded, failed, cancelled
  -token string
    	API token

agen providers

Usage of providers:
  -ca-hash string
    	pin the Hub CA of an https Hub
  -hub string
    	Hub URL
  -json
    	print the API response as JSON
  -n string
    	namespace (default "default")
  -token string
    	API token

agen mcp

usage: agen mcp workspace --root DIR [--no-run] [--run-timeout D] | agen mcp sql [--dsn-env NAME]

agen runs

Usage of runs:
  -ca-hash string
    	pin the Hub CA of an https Hub
  -hub string
    	Hub URL
  -json
    	print the API response as JSON
  -label value
    	only runs with this key=value label (repeatable)
  -limit int
    	runs (default 20)
  -n string
    	namespace (default "default")
  -roots
    	only runs that started a trace, with the usage of the runs they delegated to
  -since duration
    	only runs started within this long (e.g. 1h)
  -status string
    	running, waiting_approval, succeeded, failed or cancelled
  -task string
    	only the run of this task
  -token string
    	API token

agen trace

Usage of trace:
  -ca-hash string
    	pin the Hub CA of an https Hub
  -hub string
    	Hub URL
  -json
    	print the API response as JSON
  -n string
    	namespace (default "default")
  -token string
    	API token

agen tree

Usage of tree:
  -ca-hash string
    	pin the Hub CA of an https Hub
  -hub string
    	Hub URL
  -json
    	print the API response as JSON
  -n string
    	namespace (default "default")
  -token string
    	API token

agen query

Usage of query:
  -ca-hash string
    	pin the Hub CA of an https Hub
  -hub string
    	Hub URL
  -json
    	print the API response as JSON
  -n string
    	namespace (default "default")
  -token string
    	API token

agen transcript

Usage of transcript:
  -ca-hash string
    	pin the Hub CA of an https Hub
  -history
    	also the earlier messages of the conversation
  -hub string
    	Hub URL
  -json
    	print the API response as JSON
  -n string
    	namespace (default "default")
  -system
    	also the system prompt
  -token string
    	API token

agen replay

Usage of replay:
  -ca-hash string
    	pin the Hub CA of an https Hub
  -host-bin string
    	agen-host executable (default: next to agen, $AGEN_HOST_BIN, or on PATH)
  -hub string
    	Hub URL
  -json
    	print the API response as JSON
  -n string
    	namespace (default "default")
  -token string
    	API token

agen eval

Usage of eval:
  -host-bin string
    	agen-host executable (default: next to agen, $AGEN_HOST_BIN, or on PATH)
  -json
    	print the full JSON report instead of a table
  -runs int
    	runs per scenario (default 1)
  -scenarios string
    	directory of scenario JSON files (required)
  -store string
    	store URL for the eval runs (default: a scratch SQLite database, removed after)

agen events

Usage of events:
  -after int
    	only events after this seq
  -ca-hash string
    	pin the Hub CA of an https Hub
  -f	keep printing new events
  -hub string
    	Hub URL
  -json
    	print the API response as JSON
  -label value
    	only events with this key=value label (repeatable)
  -limit int
    	events (default 50)
  -n string
    	namespace (default "default")
  -severity string
    	only events at least this severe: info, warning or critical
  -token string
    	API token
  -type value
    	only this type (repeatable; "task." matches every task event)

agen feedback

usage: agen feedback record <task> --score S [--note TEXT] [--label k=v] | agen feedback ls [name] [--label k=v] [--since D]

agen memory

usage: agen memory set <id> [--title T] [--description D] [--limit-chars N] (value on stdin) | agen memory ls

agen artifacts

usage: agen artifacts get <id> | agen artifacts ls [task]

agen triggers

Usage of triggers:
  -ca-hash string
    	pin the Hub CA of an https Hub
  -hub string
    	Hub URL
  -json
    	print the API response as JSON
  -limit int
    	events (default 50)
  -n string
    	namespace (default "default")
  -token string
    	API token

agen webhook-secret

Usage of webhook-secret:
  -ca-hash string
    	pin the Hub CA of an https Hub
  -hub string
    	Hub URL
  -json
    	print the API response as JSON
  -n string
    	namespace (default "default")
  -token string
    	API token

agen secret

usage: agen secret set NAME --for DEPLOYMENT... [-n NS] (value on stdin) | agen secret ls [-n NS] | agen secret rm NAME [-n NS]

agen resolve

Usage of resolve:
  -ca-hash string
    	pin the Hub CA of an https Hub
  -hub string
    	Hub URL
  -json
    	print the API response as JSON
  -n string
    	namespace (default "default")
  -token string
    	API token

agen nests

Usage of nests:
  -ca-hash string
    	pin the Hub CA of an https Hub
  -hub string
    	Hub URL
  -json
    	print the API response as JSON
  -n string
    	namespace (default "default")
  -token string
    	API token

agen approvals

Usage of approvals:
  -all
    	include decided approvals
  -ca-hash string
    	pin the Hub CA of an https Hub
  -hub string
    	Hub URL
  -json
    	print the API response as JSON
  -n string
    	namespace (default "default")
  -token string
    	API token

agen notify

usage: agen notify set <name> <url> [--event E]... [--deployment D] [--label k=v] [--severity S] | agen notify ls | agen notify rm <name>

agen join-token

Usage of join-token:
  -ca-hash string
    	pin the Hub CA of an https Hub
  -hub string
    	Hub URL
  -json
    	print the API response as JSON
  -n string
    	namespace (default "default")
  -token string
    	API token
  -ttl duration
    	validity (default 1h0m0s)

agen token create

Usage of token create:
  -ca-hash string
    	pin the Hub CA of an https Hub
  -hub string
    	Hub URL
  -json
    	print the API response as JSON
  -n string
    	namespace (default "default")
  -name string
    	token name
  -namespace value
    	limit to namespace (repeatable)
  -on-behalf
    	for an agent that works for people: it acts for whoever submitted its task (see the assistant template)
  -scope value
    	scope (repeatable)
  -token string
    	API token
  -trust string
    	trust tasks submitted with this token get: operator, trusted (default) or untrusted
  -ttl duration
    	validity (0 = no expiry)

agen whoami

Usage of whoami:
  -ca-hash string
    	pin the Hub CA of an https Hub
  -hub string
    	Hub URL
  -json
    	print the API response as JSON
  -n string
    	namespace (default "default")
  -token string
    	API token