cli.md

CLI

The readyagents command is a Typer app.

Command examples below use examples/... paths from a source checkout; from a PyPI install, materialize one first with readyagents new NAME --from-example <name> (new --list-examples shows all of them).

readyagents --help
readyagents --version
readyagents --log-format json run examples/calc_pipeline.yaml

readyagents init

Writes .env from .env.example when .env is missing. Prints next steps. Does not overwrite an existing .env.

readyagents init
readyagents init --dest .env

readyagents new [name]

Write a starter project: workflow.yaml, README.md, and .env.example. Refuses to overwrite those files if they already exist. --list-examples lists the shipped example workflows; --from-example NAME copies one example (and its include children) instead of a template (cannot combine with --template).

readyagents new my-flow
readyagents run my-flow/workflow.yaml
readyagents new demo --template gated
readyagents run demo/workflow.yaml --approve gate
readyagents new --list-examples
readyagents new f --from-example calc_pipeline
readyagents new g --from-example approval_gate   # pip path for examples/approval_gate.yaml
readyagents run g/workflow.yaml

Templates: basic, approval, research (parallel + approval), pipeline (default; calc/json/condition), review (read_file + approval), foreach, agent-tools, gated, decide (confidence-gated triage; keyless run is not calibration).

readyagents import SOURCE PATH

Parse an operator-exported n8n, LangGraph, CrewAI, or trigger-action workflow and write a new ReadyAgents YAML plus a fidelity report. Structural translation only. See migration.md.

readyagents import n8n exported.json --out workflows/migrated --json
readyagents import --explain n8n
readyagents import langgraph graph.py --out workflows/lg --force

--out is workspace-confined. Overwrite requires --force. Python sources are AST-parsed, never imported. Secret values are not written.

readyagents validate PATH

Loads YAML/JSON and validates the Pydantic schema (unique node ids, dangling next / edges, cycles over next / then / else / edges, required fields per type, unique parallel branch ids). Does not call tools or LLMs. --json prints {ok, command, name, start, nodes} (or {ok: false, command, error, message} on failure). Failure --json also adds an additive problems array of {loc, message, file, line, column} when positions are known. The table shows then: / else: routing, not only next. Human output still starts with Invalid workflow PATH: and, when a position is known, a caret excerpt of the offending line.

readyagents doctor

Read-only diagnostic: platform, Python, ReadyAgents version and install location, optional extras, READYAGENTS_HOME writability, whether restrictive permissions are enforceable, filesystem case sensitivity, loopback bind, SQLite WAL, the resolved run-store backend, whether --sovereign would succeed here, and loopback model presence (never secret values or full private hostnames). Loopback probes only; no egress. Exit 0 if nothing is broken, 1 if a check failed. Attach --json output to an I-ran-this issue.

readyagents attest RUN_ID

Write a data-residency attestation for a persisted run (mode, recorded connect attempts, model endpoint, workspace, digests, MCP subprocess markers). Technical evidence, not legal compliance. MCP stdio is network_uncontrolled: true. --json, --out FILE, --sign --key PEM.

readyagents bundle --out DIR

Collect wheels plus manifest.json checksums for offline pip install --no-index --find-links DIR. One --python / --platform per invocation.

--sovereign on readyagents run refuses non-loopback egress at the socket boundary. See sovereign.md.

readyagents doctor
readyagents doctor --json

readyagents schema

Print the workflow JSON Schema 2020-12 document generated from the Pydantic models (file-format aliases else / from / inputs). No network, no workflow execution.

readyagents schema
readyagents schema --output .readyagents/workflow.schema.json
readyagents schema --output .readyagents/workflow.schema.json --force
readyagents schema --json
readyagents schema --check schemas/workflow-v1.json

--output / -o writes UTF-8 and refuses to overwrite without --force. Directories and symlink targets outside the workspace are refused. --check PATH exits 0 if PATH matches the generated bytes, 1 with a diff summary if not (CI uses this). --json wraps the schema under a schema key in the standard envelope. See authoring.md.

readyagents memory list|show|search|forget|export

Local scoped memory. Offline except optional BYOK embeddings. Memory is untrusted. forget and export require --yes. Export is workspace-confined and audited. See memory.md.

readyagents memory list --json
readyagents memory search --scope subject:T-1 "printer"
readyagents memory forget --scope subject:T-1 --yes
readyagents memory export --scope subject:T-1 --out mem.json --yes

readyagents table head|schema|stats

Inspect an intermediate table file (CSV/JSONL) or a stored content hash. schema and stats print types and counts, not every cell. head shows at most 50 sample rows. No model call. See data-pipelines.md.

readyagents table schema exports.csv --json
readyagents table head exports.csv --n 5
readyagents table stats exports.csv

readyagents a2a serve|card|probe

Serve one workflow as an A2A agent, print its Agent Card, or probe a remote card. Loopback by default. Polling only. Remote content is untrusted; delegation can exfiltrate. This is a served mapping, not A2A certification. See a2a.md.

readyagents a2a card examples/approval_gate.yaml --json
readyagents a2a serve examples/approval_gate.yaml --port 8770
readyagents a2a probe http://127.0.0.1:8770 --json
readyagents run examples/a2a_delegate.yaml --dry-run

Flag	Meaning
--host	Bind address (default 127.0.0.1). Serve only.
--port	Bind port (default 8770). Serve only.
--allow-public-bind	Allow a non-loopback bind; prints a warning. You own the exposure.
--token-env	Env var for the bearer token (default READYAGENTS_A2A_TOKEN). No token-value CLI flag.
--url	Canonical URL written into the card (a2a card).
--out	Write the card JSON to a file (a2a card).
--json	Standard envelope.

a2a serve needs starlette and uvicorn (pip install "readyagentsdev[mcp]" starlette uvicorn; from a clone, pip install -e ".[mcp]"). Same extra as MCP HTTP. a2a card and type: a2a dry-run work on a core install. If --token-env is empty on loopback, a token is generated and printed once to stderr. Public bind requires the env var.

readyagents connectors list|show|test

Installed connectors: schemas, auth names, destinations, determinism, idempotency. No secret values. test runs the conformance harness offline. The catalog is small by design.

readyagents connectors list --json
readyagents connectors show rest --json
readyagents connectors test ingest

See connectors.md.

readyagents simulate PATH

Generate declaration-driven cases, score with eval, freeze distinct failures. Dry-run side effects by default. Not exhaustive coverage. See simulation.md.

readyagents simulate flow.yaml --seed 42 --json
readyagents simulate flow.yaml --out sims/ --fail-on new-failure

readyagents bench run|compare

Offline-by-default scenario suite. Engine timing vs live end-to-end are separate labels. See benchmarks.md.

readyagents bench run --offline --json
readyagents bench run --offline --out results.json
readyagents bench compare results.json --baseline baselines/bench_offline.json
readyagents bench compare --models mock:a,mock:b --scenario classify --json
readyagents bench compare --workflows a.yaml,b.yaml --input text=hello --json

readyagents optimize PATH --eval SUITE

Reflective prompt optimization against your eval suite. Cassette scoring is zero cost; only candidate generation spends. A held-out set is mandatory. Does not rewrite workflow YAML. See prompt-optimization.md.

readyagents optimize flow.yaml --eval suite.yaml --max-iterations 8 --json
readyagents prompts history flow.yaml --id draft --json
readyagents prompts diff flow.yaml --id draft
readyagents prompts rollback flow.yaml --id draft

Not a hosted optimizer and not a claim of GEPA/DSPy parity.

readyagents env status|history|diff|deploy

Declared environments and pinned releases. Not a hosted deployment service. See environments.md.

readyagents env deploy flow.yaml --env staging --json
readyagents env deploy flow.yaml --env prod --candidate
readyagents env status --json
readyagents env history --env prod --json
readyagents env diff --env prod --from previous --to current --json
readyagents run flow.yaml --env prod --json --no-persist

readyagents registry scan|annotate|check|list|show|stats|card|export

Local agent inventory derived from declared roots. Not a hosted registry and not an Article 49 filing. See registry.md.

readyagents registry scan --json
readyagents registry annotate agt_… --owner payments_ops --tier high --json
readyagents registry check --enforce --json
readyagents registry list --tier high --max-spend 1000 --min-health 0.9 --json
readyagents registry show agt_… --json
readyagents registry stats --json
readyagents registry card agt_… --json
readyagents registry export agt_… --format annex-viii --out annex-viii-draft.json --yes --json

--unredact is RBAC-checked. list and stats accept --min-spend / --max-spend (derived spend_micros) and --min-health / --max-health. Export paths are workspace-confined; the filename must contain draft. Scan never executes a workflow or imports a pack.

readyagents distill plan|dataset|train|evaluate|promote

Local one-node adapters from consented corrections. Core never trains. Not a quality claim beyond your fixtures. See distillation.md.

readyagents distill plan --node classify --json
readyagents distill dataset --node classify --out datasets/classify --yes --json
readyagents distill train --dataset datasets/classify --base qwen-2.5-7b --json
readyagents distill evaluate --adapter adp_… --against evals/classify.yaml --dataset datasets/classify --json
readyagents distill promote --adapter adp_… --node classify --json
readyagents models adapters list --json

Holdout is mandatory. Unsigned adapters refuse to load. Sovereign mode refuses hosted tune.

readyagents promote PATH --from SRC --to DST

Copy the source environment's current pin onto the target after declared gates (eval, fixtures, benchmark, health, complete-diff approval). Never re-pins the working copy. Never auto-promotes.

readyagents promote flow.yaml --from staging --to prod --approve promote --json

readyagents rollback --env NAME

Restore the previous release atomically. Clears the candidate. Never rolls forward. When the env declares approval roles, --approve rollback is required (same class as promote). Guards also fire on the next run — there is no watcher daemon.

readyagents rollback --env prod --approve rollback --reason manual --json

readyagents feedback export|stats

Consent-gated correction export. Eval is the default format and round-trips through readyagents eval. Consent is recorded policy, not a flag. See feedback.md.

readyagents feedback export --format eval --out datasets/out.yaml --yes --json
readyagents feedback stats --by node --json

An export is production data in a portable file. Not a hosted dataset service.

readyagents health

Cluster failures by fingerprint over the existing run store. Rank by impact (count and cost burned). Bounded. No daemon. See self-healing.md.

readyagents health --json
readyagents health --workflow my-flow --window 50 --limit 64
readyagents health explain FINGERPRINT --out explain/ --yes

--yes is required for explain (diagnostic data). Not a hosted reliability service and it does not predict failures.

readyagents eval PATH

Score fixture workflows from a suite file using the same local harness as readyagents.testing.run_eval. No network and no API keys — cases must be keyless fixtures (builtin tools, transforms, recorded/scripted LLM), not live vendors.

readyagents eval examples/eval/pass.yaml
readyagents eval examples/eval/fail.yaml
readyagents eval examples/eval/pass.yaml --json

The suite is YAML or JSON with a cases: list. Each case has name, workflow (a path relative to the suite file, or an inline workflow mapping), and optional inputs, decisions, expect_status (default succeeded), expect_outputs, and expect_contains. Frozen fixtures also pin optional expect_determinism (sets of node ids for sealed / recomputed / unsealable / misses), expect_nodes (ordered node ids), expect_tools (name plus optional argument subset), and expect_usage ceilings (prompt_tokens.max and friends). Suites that omit those keys score as they did before. An empty cases: list is refused.

Human output is one PASS name / FAIL name: reason line per case, then passed=N failed=M. --json prints {ok, command, passed, failed, results} with command "eval" and results as {name, passed, reason} rows. Exit 0 if every case passes, 1 if any fail or the suite cannot be loaded. A missing suite file is ConfigError (exit 1), same as a missing workflow; --json then prints {ok: false, command: "eval", error, message}.

readyagents policy check PATH

Validate a firewall policy file. Unknown keys, bad YAML, and missing files fail closed (exit 1). --json prints {ok, command, default, source}.

readyagents policy explain WORKFLOW

Show which tools each node may call and why. --policy PATH optional (resolution is --policy, READYAGENTS_POLICY, then readyagents.policy.yaml beside the workflow).

readyagents evidence RUN_ID

Write a local evidence pack for a persisted run. This is evidence, not legal compliance or certification. The pack may contain prompts and outputs. --out DIR defaults to evidence-<run_id> and is confined to the workspace. --sign writes a detached HMAC of manifest.json using READYAGENTS_DECISION_SECRET. Overwrite requires --force. Copy manifest.json's chain_anchor off-box if you need an independent check.

readyagents evidence RUN_ID --out evidence-dir
readyagents evidence RUN_ID --out evidence-dir --force --json
readyagents evidence RUN_ID --sign

readyagents audit verify

Walk one audit JSONL (--file) or every file under $READYAGENTS_HOME/audit. Exit 0 if there is no break. Unchained pre-chain lines are reported, not failed. A mutation or truncated line exits 1 and names the first break. Hash chaining is tamper-evident, not tamper-proof.

readyagents audit verify
readyagents audit verify --file .readyagents/audit/RUN_ID.jsonl --json

readyagents graph PATH

Deterministic Mermaid of a workflow's declared routing. Executes nothing: no run, no provider, no include expansion, no pack import. Labels are sanitized (<>, URLs, click are stripped). --direction LR (default) or TD. --output / --out writes a file confined to the workspace. This is a routing picture, not an execution trace.

readyagents graph examples/graph_complex.yaml
readyagents graph examples/fanout_gate.yaml --direction TD --json

readyagents run PATH

readyagents run examples/calc_pipeline.yaml
readyagents run examples/list_dir.yaml
readyagents run examples/approval_gate.yaml --approve gate
readyagents run examples/research_brief.yaml --input topic="mcp servers"
readyagents run examples/support_triage.yaml -i message="billing question"
readyagents run examples/code_review.yaml --dry-run
readyagents run examples/research_brief.yaml --no-persist
readyagents run examples/calc_pipeline.yaml --stream --json

Flag	Meaning
--input KEY=VALUE / -i	Repeatable. true/false/null and integers are coerced
--dry-run	No LLM, no http_get or write_file (including when an agent allowlist names them); templates still interpolate. Read-only tools (now, calc, json_get, read_file, list_dir) still run.
--no-persist	Skip writing .readyagents/runs/<run_id>.json
--approve NODE	Supply an approval-node decision (repeatable)
--reject NODE	Reject an approval node (repeatable)
--resume RUN_ID	Continue a paused/failed run instead of starting fresh
--json	Print the run record as JSON on stdout (no tables; scripts/CI)
--stream	Incremental events. Combined with --json: newline-delimited events, no Rich
--log-level	DEBUG / INFO / WARNING / ERROR
--log-format	text (default) or json (machine-parseable events with run / node)
--decision-file PATH	JSON approval decisions (same shapes as readyagents decide --file)
--actor NAME	Actor id for RBAC hooks (READYAGENTS_ACTOR)
--no-cache	Skip the local LLM response cache
--pack PATH	Load a local pack .py (repeatable). Confined to the workspace. Env: READYAGENTS_PACK
--record	Write a cassette under $READYAGENTS_HOME/cassettes/ (opt-in; also READYAGENTS_RECORD=1)
--policy PATH	Firewall policy file (READYAGENTS_POLICY). Stored on the run and reloaded on resume/decide.
--estimate	Walk routing, print a spend range, execute nothing (no network)
--max-spend USD	Hard run-level USD cap consulted before each model call
--max-tokens N	Hard run-level token cap consulted before each model call
--label KEY=VALUE	Attribution label stored on the run and spend ledger (repeatable)
--override-budget	Start even when the estimate ceiling exceeds a cap (audited)
--max-model-calls N	Runaway guard: maximum complete() attempts
--max-run-tool-rounds N	Runaway guard: maximum agent tool rounds across the run
--max-wall-seconds N	Runaway guard: maximum wall-clock seconds
--require-signed	Refuse unsigned or untrusted workflow and pack artifacts. Opt-in.
--frozen	Refuse to run when readyagents.lock digests do not match.
--env NAME	Run the pinned release for a declared environment, not the working copy. Absent: today's working-copy path. See environments.md.

Signing proves origin, not safety. See supply-chain.md.

Exit code 1 on validation or execution errors, including a missing workflow file (ConfigError). Exit code 2 is reserved for an approval node pausing for a decision. Exit code 3 means resume --approve / decide was refused because the approval prompt changed since the pause (reapprove_required; --json carries reason, expected_sha256, actual_sha256); the run stays paused on the new prompt, so review and approve again. The CLI prints ErrorClass: message rather than a full traceback. Logs include run=<id> and node=<id>.

Failed runs print the node timeline, run_id, and a readyagents resume RUN_ID hint (same idea as approval pauses). --json is an envelope with additive ok and command plus existing keys (run_id, error, message, run). Pause is exit 2 and still includes run_id. resume and runs replay accept --json too. JSON is written without Rich markup, so values like [dry-run] stay intact.

State is persisted after each successful node (unless --no-persist).

--estimate prints a floor–ceiling range and the assumption list. See cost.md. The provider invoice is authoritative.

readyagents batch PATH

Foreground: one workflow, many input rows. Ends when the file is done. Not a worker, broker, or cluster. See scale.md.

readyagents batch examples/batch_echo.yaml --input-file examples/batch_rows.jsonl --concurrency 4 --out results.jsonl --json
readyagents batch examples/batch_echo.yaml --input-file examples/batch_rows.csv --no-persist

Flag	Meaning
--input-file PATH	JSONL (object per line or a JSON array) or CSV. Each row is that run's inputs.
--concurrency N	Max in-flight rows (default 8). Capped by READYAGENTS_MAX_CONCURRENCY (default 4096).
--per-workflow-limit N	Max in-flight rows for this workflow (READYAGENTS_PER_WORKFLOW_CONCURRENCY).
--per-provider-limit N	Max in-flight rows per provider (READYAGENTS_PER_PROVIDER_CONCURRENCY).
--provider-rate N	Token-bucket tokens/sec (READYAGENTS_PROVIDER_RATE).
--continue-on-error	Default on. A failed row is recorded; others continue.
--max-spend USD	Hard cap across rows, consulted before each model call.
--out PATH	Per-row JSONL sorted by index. Workspace-confined.
--json	Summary envelope (command is batch). Progress on stderr.
--run-store sqlite|json	Batch defaults to sqlite. run still defaults to JSON.
--no-persist	Skip run records.
--dry-run / --pack / --actor / --policy	Same meaning as run.

Exit 0 if every row succeeded, 2 if some paused and none failed, 1 otherwise. Existing run flags, exit codes, and --json keys are unchanged.

readyagents spend

Aggregate the local append-only spend ledger ($READYAGENTS_HOME/ledger/spend.jsonl).

readyagents spend
readyagents spend --since 2026-09-01 --by workflow --json
readyagents spend --by label

--by is day (default), workflow, model, actor, or label. Empty and corrupt lines are skipped (skipped_corrupt in --json). No network.

readyagents decide

--actor NAME remains the default unconfigured path. --token-file presents an OIDC/JWT assertion; verification is against --trust-anchors / READYAGENTS_TRUST_ANCHORS. Signed (HMAC of the body) and identified (verified subject) are separate. Replay of the same token on a gate is refused. --reason TEXT is stored with the vote (require_reason on the node enforces it). See approvals.md.

readyagents identity

readyagents identity verify --token-file ./id.jwt --json
readyagents identity whoami --json
readyagents identity trust list

whoami prints subject, key id, and fingerprint — never the private key. See identity.md. Publisher keys for signed workflows/packs are a different command: readyagents trust (supply-chain.md).

readyagents sign PATH / verify PATH

readyagents sign flow.yaml --key publisher.pem
readyagents verify flow.yaml --json

Detached Ed25519 signature beside the artifact (flow.yaml.sig). Requires the optional sign extra. Private keys are only read from --key.

readyagents trust add|list|remove

Local publisher keyring under $READYAGENTS_HOME/keyring.json. No default-trusted key. A malformed keyring fails closed.

readyagents trust add publisher.pub.pem --name ops
readyagents trust list --json
readyagents trust remove KEY_ID

readyagents lock PATH

Write readyagents.lock pinning workflow, include, pack, and MCP surface digests (digest_version: 1). --pack is the same as on run.

readyagents lock examples/include_demo.yaml
readyagents run examples/include_demo.yaml --frozen

readyagents sbom PATH

Deterministic CycloneDX-shaped JSON inventory. No network, no secrets.

readyagents sbom examples/include_demo.yaml --json
readyagents sbom examples/include_demo.yaml --out sbom.json

readyagents resume RUN_ID

Resume a paused or failed run from the last successful node. Uses the workflow path stored on the run record. A policy that was in force for the run is reloaded even if --policy is omitted.

readyagents resume abcdef --approve gate
readyagents resume abcdef --workflow examples/approval_gate.yaml --reject gate
readyagents resume abcdef --json
readyagents resume abcdef --decision-file decision.json

readyagents decide RUN_ID

Inject an approval decision from outside the CLI (a pack, a ticket webhook, a file drop) and resume.

Core still does not auto-start a listener. An optional foreground MCP HTTP door (readyagents mcp serve --transport streamable-http) exposes POST /runs/{id}/decide; see mcp.md. A pack can still receive a webhook and call this CLI.

readyagents decide abcdef --node gate --decision approve
readyagents decide abcdef --file decision.json

Accepted JSON shapes: {"gate": "approve"}, {"node_id": "gate", "decision": "approve"}, {"decisions": {"gate": "approve"}}, or a list of those objects.

readyagents runs list

List persisted runs (newest first). Each line includes run_id. --json prints a JSON array. Filters: --status, --workflow, --limit.

readyagents runs show RUN_ID

Show status, pending node (if paused), pending prompt (HITL), node timeline, inputs, and outputs. readyagents runs inspect RUN_ID is an alias. --json prints the stored run record including pending and per-node tool_rounds. Missing or ambiguous ids print {ok: false, error, message, run_id} (exit 1).

readyagents runs replay RUN_ID

Start a new run with the stored workflow path and inputs (not a resume). --offline replays a cassette: no network, no API keys. --json adds a determinism object (sealed, recomputed, unsealable, misses). Approval pause is still exit 2.

readyagents runs fork RUN_ID --from-node NODE

Mint a new run from the state after NODE. --occurrence N is required when that node ran more than once. --set KEY=VALUE overrides inputs only — it cannot satisfy an approval. The parent run record and audit file are not rewritten.

readyagents runs diff RUN_A RUN_B

Read-only. First divergent node, bounded redacted output diff, usage delta.

readyagents runs freeze RUN_ID --out DIR

Write cassette.json, case.yaml, and README.md. Conservative assertions by default; --exact pins full outputs. Also writes expect_determinism, expect_nodes, expect_tools (when the cassette recorded tool calls), and expect_usage ceilings when usage was observed. --allow-unsealed fixtures pin the non-empty unsealable list rather than omitting it. Refuses unsealable nodes unless --allow-unsealed. Warns that the fixture contains recorded model content.

See time-machine.md.

readyagents runs delete RUN_ID

Delete one local run JSON file. Requires --yes.

readyagents runs delete abcdef --yes

readyagents runs migrate

Copy JSON run records into a local SQLite file. JSON sources are never deleted or modified. JSON remains the default backend; this command is opt-in. SQLite is a local file, not hosted recovery.

readyagents runs migrate --from json --to sqlite
readyagents runs migrate --from json --to sqlite --dry-run --json
readyagents runs migrate --from json --to sqlite --on-conflict skip-identical --verify

Flag	Meaning
--from json --to sqlite	v0.9 supports this direction only
--source PATH	JSON runs directory (default $READYAGENTS_HOME/runs)
--database PATH	SQLite file (default $READYAGENTS_HOME/runs.sqlite3; relative paths under READYAGENTS_HOME)
--on-conflict	error (default) or skip-identical (resumable; never overwrites a different record)
--skip-invalid	Skip unreadable JSON instead of aborting
--verify / --no-verify	Re-read destination and compare records (default verify)
--dry-run	Plan/validate without writing
--json	Envelope {ok, command: "runs migrate", scanned, imported, skipped, conflicts, invalid, verified}

Exit 0 only when the selected policy succeeds. Exit 1 on config/schema/conflict/invalid/verification failure. See run-stores.md.

readyagents runs gc

Delete succeeded/failed/cancelled run records. Paused runs are kept unless --include-paused. Requires --yes. --keep N leaves the newest N matching runs. Records younger than READYAGENTS_RETENTION_DAYS (default 180) are refused unless --override-retention (that override is audited). This is a local hygiene window, not a legal retention obligation. gc does not delete $READYAGENTS_HOME/audit/*.jsonl. Operators who need a statutory archive must copy evidence off-box themselves.

readyagents runs gc --yes
readyagents runs gc --yes --status succeeded --keep 20
readyagents runs gc --yes --override-retention

Ctrl-C during a persisted run stores status cancelled (not leftover running).

readyagents runs report RUN_ID

Write a local HTML summary (timeline, usage, outputs). Open the file in a browser.

readyagents runs report <run_id>
readyagents runs report <run_id> --out /tmp/run.html

readyagents approvals serve

Foreground localhost approval page. Not a hosted dashboard. Binds only after this command; v0.9 rejects non-loopback hosts. Default --host 127.0.0.1 --port 8766. The bootstrap URL is printed once on stderr.

readyagents approvals serve
readyagents approvals serve --host 127.0.0.1 --port 8766

Flag	Meaning
--host	Loopback only (127.0.0.1, localhost, ::1)
--port	Default 8766
--token-env	Env var for the UI HMAC secret (default READYAGENTS_APPROVAL_UI_SECRET). Never a secret CLI flag.
--session-ttl	Session cookie seconds (default 1800)
--action-ttl	One-use action token seconds (default 300)
--actor	Actor id for RBAC
--no-open	Do not launch a browser (default)

See browser-approval-ui.md.

readyagents studio

Foreground localhost workflow canvas and run inspector (Unreleased). Not a hosted product. Binds loopback only. The bootstrap token is printed once on stderr, not in the URL. Stops when the command stops.

readyagents studio
readyagents studio --port 8790 --read-only
readyagents studio --open

Flag	Meaning
--host	Loopback only (127.0.0.1, localhost, ::1)
--port	Default 8790
--open	Open the loopback URL (token still on stderr)
--read-only	Disable save, fork, freeze, and decide on the server
--actor	Actor id for RBAC

See studio.md.

readyagents models list|show|route

Dry catalog of the shipped capability matrix and a dry explanation of which model a node would use. No provider call, no API key, no execution. --explain uses the same selector as a real run. See model-routing.md.

readyagents models list
readyagents models show openai:gpt-4o-mini
readyagents models route workflow.yaml --node draft --explain
readyagents models list --json

readyagents approvals list

Queue of paused approval gates this caller may see. Unauthorized and missing look identical (empty). --role, --actor, --expiring-within 1h, --json. Listing evaluates expiry for display only; it does not resume the graph. Status query (runs show), resume, and decide do fire lazy expiry.

readyagents delegate / delegations list|revoke

Time-bounded, single-hop, revocable delegation stored under $READYAGENTS_HOME/delegations.json. Self, chains, and scope-widening grants are refused. Checked at decision time. See approvals.md.

readyagents delegate --from alice --to bob --until 2026-09-20T00:00:00Z --scope security
readyagents delegations list --json
readyagents delegations revoke ID

readyagents mcp serve

MCP server. Requires pip install "readyagentsdev[mcp]" (from a clone: pip install -e ".[mcp]"). Stdio is the default and needs no new flag. See mcp.md.

readyagents mcp serve
readyagents mcp serve --transport stdio
readyagents mcp serve --transport streamable-http --host 127.0.0.1 --port 8765

Flag	Meaning
--transport	stdio (default) or streamable-http
--host	HTTP bind address (default 127.0.0.1). HTTP only. v0.9 rejects non-loopback binds.
--port	HTTP port (default 8765, range 1–65535). HTTP only.
--auth	token (default) or none. none is allowed only on an exact loopback bind and prints a warning.
--token-env	Env var that holds the bearer token (default READYAGENTS_MCP_TOKEN). There is no token-value CLI flag.
--max-concurrent-runs	In-process executor cap (default 4). HTTP only.
--max-pending-runs	Queue cap (default 32); extra POST /runs return 429 without a record. HTTP only.
--approval-ui	Mount the localhost approval UI on this HTTP process. HTTP only.
--json	Print protocol versions, extensions, SDK pin, and /runs deprecation, then serve.

If --auth token and the env var is empty, the process generates at least 256 bits of entropy and prints the token once to stderr. It is never persisted or logged.

streamable-http mounts official MCP Streamable HTTP at /mcp with server/discover and io.modelcontextprotocol/tasks. /runs remains a deprecated alias of the same durable run record (removal no earlier than v1.2). Stopping the command stops both the listener and the in-process executor; work does not survive process death. A keyless tasks transcript is examples/mcp_tasks_client.py. The deprecated /runs client is examples/mcp_http_client.py.

readyagents mcp probe

Read-only diagnostic. Calls server/discover, falls back to initialize, prints protocol versions and extensions, exits 0 on success and 1 on failure, and never calls a tool.

readyagents mcp probe http://127.0.0.1:8765/mcp
readyagents mcp probe http://127.0.0.1:8765/mcp --json

readyagents serve chat

Foreground loopback chat endpoint for a converse workflow. Not a hosted product, no widget CDN. Loopback by default, token-protected (READYAGENTS_CHAT_TOKEN), foreground. Public bind requires --allow-public-bind and prints a warning. See conversational-sessions.md.

readyagents serve chat my-chat/workflow.yaml --port 8795 --widget

Flag	Meaning
--host	Bind address (default 127.0.0.1)
--port	Bind port (default 8795)
--allow-public-bind	Allow a non-loopback bind; prints a warning. You own the exposure.
--token-env	Env var holding the Bearer [REDACTED] (default READYAGENTS_CHAT_TOKEN). No token-value CLI flag.
--widget	Serve bundled vanilla widget assets
--json	Standard envelope

readyagents packs

Lists packs discovered via entry points. Empty when only core is installed. --json prints {ok, packs} (or {ok: false, error, message} if a pack fails to load). A local .py loads with --pack PATH, for example readyagents packs --pack examples/packs/connector_pack.py.

The optional Continuous pack is a separate executable, readyagents-continuous, not a readyagents subcommand. See continuous-pack.md. Core still has no tick/scheduler command (serve only exposes foreground loopback surfaces such as serve chat).

readyagents package build|install|list|show|remove|upgrade|index

Workflow package archives (.rapkg). Review-before-install; nothing executes during install; --confirm is required to write. Not a hosted registry. See packaging.md.

readyagents package build ./my-pkg --out my-pkg-1.0.0.rapkg
readyagents package install my-pkg-1.0.0.rapkg --json
readyagents package install my-pkg-1.0.0.rapkg --confirm
readyagents package list
readyagents package index readyagents.index.json --json

readyagents version

Prints the package version.

Python API

from pathlib import Path
from readyagents.workflow.runner import run_workflow_file
from readyagents.testing import ScriptedLLM, run_workflow_spec

state = run_workflow_file(Path("examples/calc_pipeline.yaml"), persist=False)
print(state.status, state.output_keys)

state = run_workflow_spec(
    {"name": "t", "nodes": [{"id": "a", "type": "agent", "prompt": "hi", "output_key": "t"}]},
    llm=ScriptedLLM().enqueue("ok"),
)