CLI Reference¶

The fastaiagent CLI wraps the most common operational tasks: managing traces, running evals, serving agents, exposing them over MCP, and connecting to the Platform.

Installation¶

Installed automatically with the SDK:

pip install fastaiagent
fastaiagent --help

Top-level commands¶

Command	Purpose
`fastaiagent version`	Show SDK version and which optional extras are installed
`fastaiagent connect`	Save Platform credentials and verify the API key
`fastaiagent disconnect`	Remove saved Platform credentials
`fastaiagent auth`	Inspect saved credentials (`status`, `env`)
`fastaiagent traces`	List, export, and search local traces
`fastaiagent replay`	Show, inspect, and fork traces for debugging
`fastaiagent eval`	Curate eval datasets from traces; run evaluations
`fastaiagent prompts`	Browse the prompt registry
`fastaiagent kb`	Manage local knowledge bases
`fastaiagent ui`	Start the Local UI — traces, prompts, evals, guardrails, approvals
`fastaiagent agent`	Run an Agent or Chain as an HTTP service
`fastaiagent mcp`	Expose an Agent or Chain as an MCP server
`fastaiagent resume`	Resume a paused execution (durability)
`fastaiagent list-pending`	List pending interrupts awaiting human approval
`fastaiagent inspect`	Show checkpoint history for an execution
`fastaiagent setup-checkpointer`	Provision the durability backend (SQLite or Postgres)
`fastaiagent migrate`	Copy legacy `traces.db` / `checkpoints.db` / `.prompts/` into `local.db`, once per source (`--force` re-imports); imported history is never pushed to a plane
`fastaiagent export-trace`	Export one trace as a self-contained JSON file (same payload as the Local UI's Export button)

`fastaiagent version`¶

$ fastaiagent version
fastaiagent 1.0.0 [openai, anthropic, langchain, crewai, kb, qdrant, chroma, mcp-server, otel-export, postgres]

Brackets list the optional extras whose upstream package is importable. Useful when debugging "which extras did this env install?" in bug reports.

`fastaiagent connect` / `disconnect` / `auth`¶

Persist Platform credentials to ~/.fastaiagent/credentials.toml (mode 0600) so scripts and CI don't need to pass the API key each time.

# Save + verify
fastaiagent connect --api-key fa_live_...

# Override target / project
fastaiagent connect --api-key fa_live_... --target https://platform.mycorp.com --project billing

# Inspect
fastaiagent auth status
#   Connected (source: file)
#     Target:  https://app.fastaiagent.net
#     Project: (default)
#     API key: fa_liv…ab34

# Print shell exports for sourcing
eval "$(fastaiagent auth env)"
# -> exports FASTAIAGENT_API_KEY, FASTAIAGENT_TARGET, FASTAIAGENT_PROJECT

# Remove
fastaiagent disconnect

Python interaction. fa.connect(api_key=...) in Python stays explicit — the CLI does not auto-connect your scripts. The intended pattern is to either (a) eval "$(fastaiagent auth env)" before starting your process and read os.environ["FASTAIAGENT_API_KEY"] in fa.connect(...), or (b) parse ~/.fastaiagent/credentials.toml yourself. Environment variables always win over the file.

`fastaiagent traces`¶

# List recent traces (last 24h by default)
fastaiagent traces list
fastaiagent traces list --last-hours 168

# Export a trace as JSON — printed to stdout, so redirect to save it
fastaiagent traces export <trace_id> > trace.json
fastaiagent traces export <trace_id> --format json

There is no --limit and no --output

traces list windows by time, not by row count — --last-hours N is its only option. traces export takes --format (currently json) and writes to stdout; shell redirection is how you get a file.

`fastaiagent replay`¶

# Show replay steps
fastaiagent replay show <trace_id>

# Inspect a specific step
fastaiagent replay inspect <trace_id> <step>

# Fork a trace at a step, optionally modify the prompt or input, then rerun
fastaiagent replay fork <trace_id> --step 3 --prompt "New system prompt" \
    --output rerun.json

fastaiagent replay fork <trace_id> --input "Try a different question"

replay fork is the CLI surface for Replay.load(trace_id).fork_at(step).modify_prompt(...).modify_input(...).rerun().

`fastaiagent eval`¶

# Curate an eval dataset from captured agent traces
fastaiagent eval curate --filter favorites --out cases.jsonl
fastaiagent eval curate --filter guardrail --agent support --since 24 --out fixme.jsonl

# Run a dataset against an agent and gate on the result
fastaiagent eval run \
  --agent app/agents.py:support_agent \
  --dataset cases.jsonl \
  --scorers exact_match,faithfulness \
  --fail-under "overall.pass_rate=0.9" \
  --max-error-rate 0.1 \
  --run-name main \
  --json report.json

# Compare two persisted runs (baseline first)
fastaiagent eval compare main pr --tolerance 0.02

# Inspect what Agent-CI evidence would leave this machine (connected mode)
fastaiagent eval export --status        # posture + runs queued for the plane
fastaiagent eval export --dry-run       # the literal JSON that would be sent

Each agent.<name> span (root, or nested inside a chain/supervisor/swarm) becomes one case. See Trace Curation.

--agent accepts path/to/file.py:attr or pkg.module:attr (a callable, or any object with a .run method). Thresholds use <scorer|overall>.<pass_rate|avg_score>=v; a bare scorer name means its pass_rate.

Exit codes: 0 gate passed · 1 quality gate failed (threshold miss or regression) · 3 run invalid (infra error rate exceeded, or nothing scored). 2 is reserved for usage errors.

For gating your existing pytest suite — with baselines and regression detection — see Agent CI.

eval export only inspects; it never sends. When connected, gate verdicts are pushed automatically in the background — run aggregates, gate outcome, thresholds, git provenance and per-case scorer verdicts + trace_ids. Case inputs and outputs are never sent. Disable with connect(export_evals=False) or FASTAIAGENT_EXPORT_EVALS=0; see Agent CI → Connected mode.

`fastaiagent prompts`¶

# List registered prompts
fastaiagent prompts list

# Diff two versions
fastaiagent prompts diff <name> --from v1 --to v2

`fastaiagent kb`¶

# List all KBs under the default root (.fastaiagent/kb/)
fastaiagent kb list

# List under a custom root
fastaiagent kb list --path /srv/fastaiagent/kb/

# Status of one KB
fastaiagent kb status --name product-docs

# Ingest a file or directory
fastaiagent kb add docs/           --name product-docs
fastaiagent kb add docs/refund.md  --name product-docs

# Delete by source file
fastaiagent kb delete docs/old.md --name product-docs

# Clear the whole KB
fastaiagent kb clear --name product-docs

`fastaiagent ui`¶

Start the Local UI — traces, prompts, evals, guardrails, datasets, and approvals over ./.fastaiagent/local.db.

fastaiagent ui                                      # http://127.0.0.1:7842
fastaiagent ui start --no-auth --port 8080
fastaiagent ui reset-password

Flag	Default	Effect
`--host`	`127.0.0.1`	Bind address. Non-loopback requires `--insecure-bind`.
`--port`	`7842`	Port.
`--no-auth`	off	Skip login. Throwaway use only.
`--no-open`	off	Don't open a browser.
`--insecure-bind`	off	Acknowledge the risk of a non-loopback bind.
`--db PATH`	`./.fastaiagent/local.db`	Override the DB path.
`--auth-file PATH`	`./.fastaiagent/auth.json`	Override the credentials file.
`--agent SPEC`	none	Register an agent with the server. Repeatable.

`--agent`¶

Most of the UI reads the trace database, so it needs no setup. Three features need the live object: resuming an approval, evaluating a dataset against a real agent, and listing an agent's tools before its first run.

fastaiagent ui --agent app.py:support_agent
fastaiagent ui --agent app.py:support --agent mypkg.agents:billing

Takes path/to/file.py:attr or pkg.module:attr — the same syntax as fastaiagent agent serve and fastaiagent eval run — resolving to an Agent, Chain, Swarm, or Supervisor. Targets that fail to resolve are reported and skipped; the UI still starts. The module is imported, so guard module-level side effects with if __name__ == "__main__":.

Unlike agent serve, this does not expose an endpoint that runs your agent on request. Import paths are read only from the command line, never from a request body.

Security¶

The Local UI binds to loopback and refuses anything else unless you pass --insecure-bind, since the session cookie travels over plain HTTP. This is the opposite default from agent serve, which binds 0.0.0.0 for containers.

`fastaiagent agent serve`¶

Run any Agent or Chain as a FastAPI service that exposes the uniform deployment contract:

# path/to/file.py:attr
fastaiagent agent serve examples/01_simple_agent.py:agent --port 8000

# pkg.module:attr
fastaiagent agent serve mypkg.agents:research_bot --port 9000 --reload

Exposes: - GET /health - POST /run — {"input": "..."} → {"output", "latency_ms", "tokens_used", "trace_id", "status", "execution_id", "pending_interrupt"}. status is "paused" when the run stopped for a decision — a managed approval policy or an interrupt() — with empty output and the reason and context (for a policy pause, the tool and its arguments) in pending_interrupt. The service has no resume route: resume the execution_id from your application with aresume(...) against the same checkpointer. - POST /run/stream — Server-Sent Events (Agent targets only). A run that pauses ends with a {"type": "paused", "reason", "execution_id", "context"} event before done (1.77.0).

Security¶

/run and /run/stream execute your agent — including its tools and LLM calls — so treat the port as sensitive.

Default bind is 0.0.0.0 so the service is reachable when running inside a container (binding 127.0.0.1 would make it unreachable through Docker/Kubernetes port mapping). Pass --host 127.0.0.1 for a purely local service.
The execution routes are unauthenticated by default. Enable a bearer token with --auth-token <token> (or the FASTAIAGENT_SERVE_TOKEN env var); callers then send Authorization: Bearer <token>. GET /health stays open for liveness probes.
When bound to a non-loopback address without a token, the command prints a startup warning. For any network-exposed deployment, set a token and terminate TLS at a reverse proxy so the token isn't sent in plaintext.
--max-body-bytes caps request size (default 10 MiB).

# Authenticated, container-friendly:
FASTAIAGENT_SERVE_TOKEN=$(openssl rand -hex 32) \
  fastaiagent agent serve mypkg.agents:research_bot --port 9000

# Local-only, no auth needed:
fastaiagent agent serve examples/01_simple_agent.py:agent --host 127.0.0.1

If you need custom routes / auth / middleware, copy examples/33_deploy_fastapi.py and extend it directly instead.

Requires: pip install fastapi 'uvicorn[standard]' (or fastaiagent[all]).

`fastaiagent mcp serve`¶

Expose an Agent or Chain as an MCP server over stdio — registers with Claude Desktop, Cursor, Continue, Zed, and any other MCP client:

fastaiagent mcp serve path/to/my_agent.py:agent
fastaiagent mcp serve path/to/my_agent.py:agent --expose-tools --name research_bot

See docs/tools/mcp-server.md for Claude Desktop / Cursor config snippets.

Requires: pip install 'fastaiagent[mcp-server]'.

Durability commands¶

The four commands below cover the v1.0 durability workflow: pause an execution with interrupt(), list what's waiting, then resume from any process.

`fastaiagent list-pending`¶

Rich-rendered table of every pending interrupt in the local store:

fastaiagent list-pending
fastaiagent list-pending --db-path /var/lib/fastaiagent/local.db
fastaiagent list-pending --limit 50

`fastaiagent inspect <execution_id>`¶

Checkpoint history for one execution — node-by-node statuses, timestamps, and agent_path for multi-agent topologies:

fastaiagent inspect refund-abc
fastaiagent inspect refund-abc --db-path ./.fastaiagent/local.db

Exits 1 when the execution has no checkpoints.

`fastaiagent resume <execution_id>`¶

Loads the runner via a Python entrypoint and calls aresume(...):

# Approve
fastaiagent resume refund-abc --runner myapp.flows:build_chain

# Reject with a reason
fastaiagent resume refund-abc \
    --runner myapp.flows:build_chain \
    --value '{"approved": false, "metadata": {"reason": "amount above threshold"}}'

Exits 2 on AlreadyResumed (another resumer claimed the pending row first — a deterministic outcome, not a bug).

`fastaiagent setup-checkpointer`¶

Provisions the durability backend's schema. Idempotent for both backends.

# Local SQLite (default)
fastaiagent setup-checkpointer

# Postgres
fastaiagent setup-checkpointer \
    --backend postgres \
    --connection-string "$DATABASE_URL"

# Custom Postgres schema (so two installs share one DB)
fastaiagent setup-checkpointer \
    --backend postgres \
    --connection-string "$DATABASE_URL" \
    --schema fa_prod

See docs/durability/checkpointers.md for the full backend reference.

Environment variables¶

Variable	Used by
`FASTAIAGENT_API_KEY`	Platform connection (Python + CLI)
`FASTAIAGENT_TARGET`	Platform URL override
`FASTAIAGENT_PROJECT`	Platform project override
`FASTAIAGENT_LOCAL_DB`	Local SQLite store (traces, checkpoints, idempotency, prompts)
`FASTAIAGENT_CHECKPOINT_DB_PATH`	Override checkpoint store path (legacy; prefer `FASTAIAGENT_LOCAL_DB`)
`FASTAIAGENT_LIVE_OPENAI_MODEL`	Override OpenAI model in live tests
`FASTAIAGENT_LIVE_ANTHROPIC_MODEL`	Override Anthropic model in live tests
`OPENAI_API_KEY`	LLM calls (OpenAI)
`ANTHROPIC_API_KEY`	LLM calls (Anthropic)

`fastaiagent export-trace`¶

Export a single trace as a self-contained JSON file. Reads the local SQLite directly — no UI server required.

fastaiagent export-trace --trace-id <id> --output trace.json
fastaiagent export-trace --trace-id <id> --output trace-full.json \
    --include-attachments --include-checkpoint-state

Flags:

--trace-id <id> (required) — the trace to export.
--output <path> (default trace.json) — destination file.
--include-attachments — embed image / PDF bytes (base64) in the JSON. Off by default; files can balloon to many MB.
--include-checkpoint-state — embed full state_snapshot blocks for each checkpoint. Off by default.
--db <path> — override the local DB; defaults to whatever SDKConfig.local_db_path resolves to (typically .fastaiagent/local.db).

Same JSON shape comes out of the Local UI's Export dialog. See Export trace as JSON for the schema.

CLI Reference¶

Installation¶

Top-level commands¶

fastaiagent version¶

fastaiagent connect / disconnect / auth¶

fastaiagent traces¶

fastaiagent replay¶

fastaiagent eval¶

fastaiagent prompts¶

fastaiagent kb¶

fastaiagent ui¶

--agent¶

Security¶

fastaiagent agent serve¶

Security¶

fastaiagent mcp serve¶

Durability commands¶

fastaiagent list-pending¶

fastaiagent inspect <execution_id>¶

fastaiagent resume <execution_id>¶

fastaiagent setup-checkpointer¶

Environment variables¶

fastaiagent export-trace¶

Next Steps¶

`fastaiagent version`¶

`fastaiagent connect` / `disconnect` / `auth`¶

`fastaiagent traces`¶

`fastaiagent replay`¶

`fastaiagent eval`¶

`fastaiagent prompts`¶

`fastaiagent kb`¶

`fastaiagent ui`¶

`--agent`¶

`fastaiagent agent serve`¶

`fastaiagent mcp serve`¶

`fastaiagent list-pending`¶

`fastaiagent inspect <execution_id>`¶

`fastaiagent resume <execution_id>`¶

`fastaiagent setup-checkpointer`¶

`fastaiagent export-trace`¶