CLI reference¶
Every command, subcommand and flag of graph-agents-cli,
generated at build time from the CLI itself, so this page always matches
graph-agents-cli <command> --help.
create is an alias of scaffold create. Commands follow one
exit-code scheme; the environment variables the CLI reads are in
Environment variables. Extension overrides can replace or add commands in a
project; this page shows the built-in ones (see Extensions).
graph-agents-cli¶
Graph Agents CLI — LangGraph agents on Kubernetes.
Build, evaluate, and deploy LangGraph agents with a single unified CLI.
Quick start:
graph-agents-cli setup Install skills to your coding agent
graph-agents-cli create my-agent Create a new agent project
graph-agents-cli playground Start the local playground
graph-agents-cli eval run Run the agent over the eval dataset and grade it
graph-agents-cli deploy --env dev Deploy to the current Kubernetes context
Usage:
Options:
--version- Show the version (with the commit, for a build that is not a release) and exit.
--help- Show this message and exit.
Subcommands
- api: Declare and change the outbound APIs tools may call (api-policy.yaml).
- approvals: List and decide the gated API calls agent runs are waiting on.
- auth: Local credentials for the project's auth policy (dev-only JWTs).
- build: Build the agent container image.
- create: Create a LangGraph agent project from a template.
- deploy: Deploy the agent to Kubernetes (mode depends on the project's CD setting).
- eval: Evaluate agents and compare results.
- extension: Manage graph-agents-cli extensions (experimental).
- info: Show project configuration, paths, and CLI version.
- infra: Check cluster and repository prerequisites (read-only).
- install: Install project dependencies.
- lint: Run code quality checks and the API-policy check.
- login: Check model provider keys, LangSmith, and kubeconfig; optionally write .env.
- peer: Declare the other agents this agent asks, over A2A (its peers).
- playground: Start the application locally with reload and the dev chat page.
- run: Run the agent with a single prompt (non-interactive).
- scaffold: Scaffold, enhance, and upgrade agent projects.
- secrets: Provision and inspect the application Secret per environment.
- setup: Install graph-agents-cli and skills to detected coding agents.
- system: Check, wire and deploy agents that call each other, as one system.
- update: Force reinstall skills to all detected coding agents.
graph-agents-cli api¶
Declare and change the outbound APIs tools may call (api-policy.yaml).
The policy belongs to the project and evolves with the agent: add an API, then widen or narrow its access as tools need it. There is no default access: read-only (GET, HEAD) and read-write (GET, HEAD, POST, PUT, PATCH, DELETE) are written into the file as those methods, and custom takes --methods. Every change is validated with the rules the agent enforces, keeps comments and key order, prints a unified diff and writes atomically; --dry-run prints the diff only. The manifest (api_policy, secrets.keys), .env.example and the chart's values.yaml follow the change.
api approval makes chosen calls wait for a human approval before they are sent (requester confirmation, or role:<name> approvers for a second person's review; --add-rule gives other calls of the API other approvers); approval never widens access.
A JSON-RPC API (add --protocol jsonrpc), or another agent over A2A (--protocol a2a --a2a-path /a2a/<name>), is judged by the request each POST sends, read from its body: allow, deny and gate it by --rpc-method, and an agent's approve decisions by --a2a-operation(s) approve.
Exit codes:
0 changed, or nothing to change
1 check: a declared call is refused
2 usage error
3 invalid result, invalid api-policy.yaml (check too), or not in a project
Usage:
Options:
--help- Show this message and exit.
Subcommands
- access: Set the HTTP methods an API allows (read-only, read-write, or custom --methods).
- add: Declare an API with an explicit access choice (creates api-policy.yaml when absent).
- allow: Allow one operation (an allowed_operations entry, by OPERATION_ID and/or --method/--path).
- approval: Require a human approval before some of an API's calls are sent (or --remove it).
- check: Check every tool's API_CALLS against api-policy.yaml (same as lint --policy-only).
- deny: Deny one operation (a denied_operations entry, by OPERATION_ID and/or --method/--path).
- limits: Set or clear an API's limits (max calls per run, rate per minute, answer size).
- remove: Remove an API (the last one removes api-policy.yaml).
- revoke: Remove the allowed or denied entries naming an operation (OPERATION_ID or --method/--path).
- show: Show the effective policy per API and the calls every tool declares.
graph-agents-cli api access¶
Set the HTTP methods an API allows (read-only, read-write, or custom --methods).
Usage:
Options:
--methods TEXT- custom: e.g. GET,POST (or "*").
--dry-run- Print the diff only; write nothing.
--help- Show this message and exit.
graph-agents-cli api add¶
Declare an API with an explicit access choice (creates api-policy.yaml when absent).
With --protocol a2a (another agent), every message that approves one of that agent's pending approvals is denied (denied_operations: a2a_operation: approve) when POST is allowed: an agent never decides a person's approvals on its own. To relay the person's decision instead, gate it (api approval NAME --a2a-operations approve --approvers requester), then lift the denial (api revoke NAME --a2a-operation approve --from denied).
Usage:
Options:
--base-url-env TEXT- Environment variable holding the API's base URL (e.g. ORDERS_API_BASE_URL). [required]
--auth [none|bearer|forward|exchange]- none, bearer (a token from --token-env), forward (the caller's own credential) or exchange (a token the issuer mints for --audience in exchange for the caller's, RFC 8693). [required]
--token-env TEXT- --auth bearer: variable holding the token.
--forward-header TEXT- --auth forward or exchange: header the credential is sent in (default Authorization).
--audience TEXT- --auth exchange (required): the audience the issuer mints the token for (the target's AUTH_JWT_AUDIENCE). --auth forward: forward_audience, the audience the caller's own token must name to be forwarded (jwt).
--scope TEXT- --auth exchange: the scopes to ask for, space separated (least privilege).
--resource TEXT- --auth exchange: the target's resource indicator, an absolute URI (RFC 8707).
--allow-actorless- --auth exchange: accept exchanged tokens that name no actor (exchange.allow_actorless; refused by default). Only when the agent behind the API sets AUTH_JWT_DIRECT_CLIENTS and lists this agent as client:<its client id> in AUTH_ALLOWED_ACTORS.
--protocol [http|jsonrpc|a2a]- http (the default), jsonrpc (a JSON-RPC 2.0 API) or a2a (another agent over A2A 1.0 JSON-RPC, with --a2a-path): jsonrpc and a2a judge each POST by the JSON-RPC request it sends, read from its body.
--a2a-path PATH- --protocol a2a (required): the agent's A2A endpoint, a literal path such as /a2a/orders.
--description TEXT- What the API is for (1-300 characters).
--access [read-only|read-write|custom]- Required, no default: read-only (GET, HEAD), read-write (GET, HEAD, POST, PUT, PATCH, DELETE) or custom (--methods). [required]
--methods TEXT- --access custom: e.g. GET,POST (or "*").
--openapi FILE- The API's OpenAPI spec (copied under openapi/<name>/ unless inside the project).
--max-calls-per-run N- Limit: calls to this API within one agent run. [x>=1]
--rate-per-minute N- Limit: calls per minute, per process (replica). [x>=1]
--max-response-bytes N- Limit: the most an answer may hold, in bytes (larger answers are discarded). [1<=x<=67108864]
--connect-timeout-ms N- Connect timeout (default 2000). [x>=1]
--read-timeout-ms N- Read timeout (default 5000). [x>=1]
--dry-run- Print the diff only; write nothing.
--help- Show this message and exit.
graph-agents-cli api allow¶
Allow one operation (an allowed_operations entry, by OPERATION_ID and/or --method/--path).
An entry pins every field given, and all of them must match a call: pin the method (--methods, or --method with --path) and, without an OpenAPI spec, the path, so the entry allows exactly the declared call. With the API's openapi spec recorded, OPERATION_ID must exist there and its method and path are filled in. On a JSON-RPC API, --rpc-method M --method POST --path P allows the requests with that JSON-RPC method (read from the body) at that endpoint.
Usage:
Options:
--method TEXT- The operation's HTTP method (with --path; also with OPERATION_ID).
--path TEXT- The operation's path template (with --method; also with OPERATION_ID).
--methods TEXT- Limit the entry to these methods (e.g. GET,PUT).
--rpc-method M- A JSON-RPC API (protocol jsonrpc or a2a): the JSON-RPC method of the request, with --method POST --path P (OPERATION_ID optional); A2A 1.0 names under a2a.
--dry-run- Print the diff only; write nothing.
--help- Show this message and exit.
graph-agents-cli api approval¶
Require a human approval before some of an API's calls are sent (or --remove it).
A gated call is still allowed by the rest of the policy first (approval never widens access; denials still win). The run pauses before sending it and an approver decides: requester (the principal who started the run confirms) and/or role:<name> (a principal holding that role; list roles without requester for a second person's review). Approving sends exactly the call shown, once; rejecting or expiry sends nothing.
Each option given replaces that part of the rule and keeps the rest:
--methods POST,DELETE every call with those methods
--operations cancelOrder calls to those operations
--a2a-operations approve (protocol a2a) messages that approve one
of the called agent's pending approvals
--approvers requester who decides (required for a new rule)
--timeout-s 900 how long a pending approval waits
--decide-with relayed --relayers concierge
let the agent concierge deliver the
requester's decision (default: direct)
Different approvers for different calls: add a rule, and name one to
change or remove by its number (api show lists them):
--add-rule --operations createOrder --approvers role:admin
--rule 1 --approvers role:admin,role:ops
--rule 1 --remove
The approval block then holds a list of rules, and a call is gated by the
FIRST rule in file order that covers it, with that rule's approvers; a
later rule that also covers it does not apply to it (lint and api show
name the rule each declared call waits for).
Usage:
Options:
--methods M,...|none- Gate every call with these methods (e.g. POST,PATCH,DELETE, or "*"); none clears it.
--operations OP,...|none- Gate these operations by operationId (the API's openapi spec pins their method and path); none clears it.
--a2a-operations approve[,reject]|none- protocol a2a: gate the messages that approve (or reject) a pending approval of the agent behind the API, whatever their path, label or spelling; none clears it.
--approvers A,...- Who decides: requester and/or role:<name> (e.g. requester, or role:ops for four-eyes).
--timeout-s N- Seconds a pending approval waits before it expires, which rejects the call (30-86400; default 900). [30<=x<=86400]
--decide-with [direct|relayed]- How the requester decides: direct (the default: with their own credentials, at this agent) or relayed (the agents --relayers names may deliver the requester's decision from another agent; a loosening, reviewed like one).
--relayers ID,...- With --decide-with relayed: the agents, by actor id (the act.sub of their exchanged tokens, usually their client ids), that may relay the requester's decision.
--add-rule- Add a rule after the existing ones, for calls other approvers decide (needs --approvers, and --methods and/or --operations).
--rule N- Change, or --remove, rule N of a list of rules: approval[N], numbered from 0 in file order as
api showprints them (0 is also a single approval block). [x>=0] --remove- Remove the approval block, every rule of it (the API's calls are sent without waiting for a human), or with --rule N that one rule.
--dry-run- Print the diff only; write nothing.
--help- Show this message and exit.
graph-agents-cli api check¶
Check every tool's API_CALLS against api-policy.yaml (same as lint --policy-only).
Usage:
Options:
--help- Show this message and exit.
graph-agents-cli api deny¶
Deny one operation (a denied_operations entry, by OPERATION_ID and/or --method/--path).
A denial with a path refuses every call to that path (with its method), whatever operation id the call names. A denial by OPERATION_ID alone knows only that label: with the API's openapi spec recorded, the id's method and path are filled in; without one, give --method M --path P too so the denial holds whatever a call is labelled. On a JSON-RPC API, --rpc-method M refuses every request with that method, and --a2a-operation approve every message that approves a pending approval of the agent behind the API (read from the body, whatever the label).
Usage:
Options:
--method TEXT- The operation's HTTP method (with --path; also with OPERATION_ID).
--path TEXT- The operation's path template (with --method; also with OPERATION_ID).
--rpc-method M- A JSON-RPC API (protocol jsonrpc or a2a): the requests with this JSON-RPC method (read from the body; letter case ignored), whatever their path or label.
--a2a-operation [approve|reject]- protocol a2a: the messages that approve (or reject) a pending approval of the agent behind the API, whatever their path, label or spelling.
--dry-run- Print the diff only; write nothing.
--help- Show this message and exit.
graph-agents-cli api limits¶
Set or clear an API's limits (max calls per run, rate per minute, answer size).
Usage:
Options:
--max-calls-per-run N|none- Calls to this API within one agent run (none removes the limit).
--rate-per-minute N|none- Calls per minute, per process (replica); none removes the limit.
--max-response-bytes N|none- The most an answer may hold, in bytes (1-67108864; larger answers are discarded); none removes the cap.
--dry-run- Print the diff only; write nothing.
--help- Show this message and exit.
graph-agents-cli api remove¶
Remove an API (the last one removes api-policy.yaml).
Usage:
Options:
--dry-run- Print the diff only; write nothing.
--help- Show this message and exit.
graph-agents-cli api revoke¶
Remove the allowed or denied entries naming an operation (OPERATION_ID or --method/--path).
On a JSON-RPC API, --rpc-method M and/or --a2a-operation approve|reject name the entries that pin them (with OPERATION_ID, the one also naming it).
Usage:
Options:
--method TEXT- The operation's HTTP method (with --path).
--path TEXT- The operation's path template (with --method).
--rpc-method M- A JSON-RPC API (protocol jsonrpc or a2a): the requests with this JSON-RPC method (read from the body; letter case ignored), whatever their path or label.
--a2a-operation [approve|reject]- protocol a2a: the messages that approve (or reject) a pending approval of the agent behind the API, whatever their path, label or spelling.
--from [allowed|denied]- The list to remove the entry from (needed when both have a match).
--dry-run- Print the diff only; write nothing.
--help- Show this message and exit.
graph-agents-cli api show¶
Show the effective policy per API and the calls every tool declares.
Each call's status says whether the policy allows it, and a gated call names who must approve it before it is sent (the API's approval block).
Usage:
Options:
--json- Print JSON.
--help- Show this message and exit.
graph-agents-cli approvals¶
List and decide the gated API calls agent runs are waiting on.
A call gated by an API's approval block in api-policy.yaml is not sent until an approver decides it: requester (the principal who started the run) and/or role:<name> (a principal holding that role; a requester decides their own call only when requester is listed). Approving sends exactly the call shown, once; rejecting, or letting it expire, sends nothing and the agent is told it was not approved.
Credentials follow the project's auth policy, as for `run`: put a bearer
credential in GRAPH_AGENTS_CLI_API_KEY (locally, the API_KEY in .env is
used when it is unset), or pass --header / --cookie. Each approver uses
their own credential.
Exit codes:
0 listed, or decided (the resumed run was shown)
1 refused (not an allowed approver, already decided, expired, not
found), or the resumed run ended with an error
2 the agent could not be reached
3 configuration error (not in a project without --url)
Usage:
Options:
--help- Show this message and exit.
Subcommands
- approve: Approve a pending call: it is sent exactly as shown, once, and the run resumes.
- list: List pending approvals (a thread's, or every one you may see).
- reject: Reject a pending call: it is never sent, and the run resumes without it.
graph-agents-cli approvals approve¶
Approve a pending call: it is sent exactly as shown, once, and the run resumes.
Usage:
Options:
--url TEXT- Base URL of a deployed agent. Without it, the project's local server.
-H, --header TEXT- Custom HTTP header ('Key: Value'). Repeatable. An Authorization header overrides GRAPH_AGENTS_CLI_API_KEY; prefer the variable for bearer credentials.
--cookie TEXT- Cookie ('name=value'), for a custom auth policy that reads cookies. Repeatable.
--thread-id TEXT- The approval's thread (printed with the approval). Without it, every approval you may see is searched.
--comment TEXT- Why; recorded with the decision.
-v, --verbose- Print each event of the resumed run.
--help- Show this message and exit.
graph-agents-cli approvals list¶
List pending approvals (a thread's, or every one you may see).
Usage:
Options:
--url TEXT- Base URL of a deployed agent. Without it, the project's local server.
-H, --header TEXT- Custom HTTP header ('Key: Value'). Repeatable. An Authorization header overrides GRAPH_AGENTS_CLI_API_KEY; prefer the variable for bearer credentials.
--cookie TEXT- Cookie ('name=value'), for a custom auth policy that reads cookies. Repeatable.
--thread-id TEXT- The thread to list. Without it: every approval you may see (your own, the ones your roles may decide, all of them for a read-across role; the newest 500).
--all- Also list decided and expired ones.
--json- Print JSON.
--help- Show this message and exit.
graph-agents-cli approvals reject¶
Reject a pending call: it is never sent, and the run resumes without it.
Usage:
Options:
--url TEXT- Base URL of a deployed agent. Without it, the project's local server.
-H, --header TEXT- Custom HTTP header ('Key: Value'). Repeatable. An Authorization header overrides GRAPH_AGENTS_CLI_API_KEY; prefer the variable for bearer credentials.
--cookie TEXT- Cookie ('name=value'), for a custom auth policy that reads cookies. Repeatable.
--thread-id TEXT- The approval's thread (printed with the approval). Without it, every approval you may see is searched.
--comment TEXT- Why; recorded with the decision.
-v, --verbose- Print each event of the resumed run.
--help- Show this message and exit.
graph-agents-cli auth¶
Local credentials for the project's auth policy (dev-only JWTs).
Nothing here touches a cluster or an identity provider.
Usage:
Options:
--help- Show this message and exit.
Subcommands
- dev-token: Mint a JWT for local runs of a jwt project (APP_ENV=dev only).
graph-agents-cli auth dev-token¶
Mint a JWT for local runs of a jwt project (APP_ENV=dev only).
Prints the token alone on stdout, so it can go straight into the variable run and eval send as the bearer, without appearing in argv or your shell history:
export GRAPH_AGENTS_CLI_API_KEY="$(graph-agents-cli auth dev-token --sub alice --roles user)"
graph-agents-cli run "hello"
graph-agents-cli eval run
An agent calling another agent for a user presents a token naming both:
graph-agents-cli auth dev-token --sub alice --act concierge
(--act billing --act concierge: billing, called by concierge, for alice).
The first call creates a dev RSA key pair in .graph-agents-cli/dev-jwt/
(git ignored) and fills blank AUTH_JWT_PUBLIC_KEY, AUTH_JWT_ISSUER and
AUTH_JWT_AUDIENCE in .env (kept 0600); values .env already sets are used
as they are. Restart a running local server afterwards
(`graph-agents-cli run --stop-server`). Refused unless the project's
policy is jwt, APP_ENV is exactly dev, and .env names no JWKS URL and no
other public key. Never deploy the dev key.
Exit codes:
0 token printed
2 the project's environment could not sign (run `graph-agents-cli install`)
3 not a jwt project under APP_ENV=dev, or another key or issuer is configured
Usage:
Options:
--sub TEXT- The principal id the token carries (in AUTH_JWT_PRINCIPAL_CLAIM, default sub). [required]
--roles TEXT- Comma list of roles (in AUTH_JWT_ROLES_CLAIM, default roles), e.g. user,support.
--ttl TEXT- Lifetime: seconds, or a number with s, m, h or d (at most 7d). [default: 12h]
--act ID- An agent presenting the token for --sub (the RFC 8693 act claim); repeat for a chain, the current agent first. The server refuses it unless AUTH_ALLOWED_ACTORS lists it.
--azp ID- The token's authorized party (client id), as AUTH_JWT_DIRECT_CLIENTS reads it.
--help- Show this message and exit.
graph-agents-cli build¶
Build the agent container image.
Runs docker build -t <registry>/<name>:<tag> . with the project's runtime-specific Dockerfile. The registry defaults to the manifest's create_params.registry; without one the image is named after the project.
Usage:
Options:
--tag TEXT- Image tag. [default: latest]
--registry TEXT- Override the manifest registry (e.g. ghcr.io/org).
--push- Push the image after building.
--dry-run- Print the docker commands without running them.
--help- Show this message and exit.
graph-agents-cli create¶
Create a LangGraph agent project from a template.
Usage:
Options:
-a, --agent TEXT- Template to use: a bundled agent (default: langgraph), a local path (
local@/path/to/template), or a remote spec (org/repo/path@ref,https://github.com/org/repo/tree/main/path). -o, --output-dir PATH- Output directory for the project (default: current directory)
--response-schema FILE- Structured final answers: seed <agent directory>/response_schema.json (the JSON Schema of the agent's final answer) from this file; checked before the project is created
--runtime [fastapi|langgraph-server]- Application runtime (default: fastapi)
--model-provider [openai|anthropic|gemini|openai-compatible]- Model provider (default: openai; prompted in interactive mode)
--model TEXT- Model name (default: the provider's default model)
--checkpointer [memory|postgres]- Deployed checkpointer (default: postgres for kubernetes, memory for none)
-d, --deployment-target [kubernetes|none]- Deployment target (default: kubernetes)
--registry TEXT- Container registry <url/org> (default: ghcr.io/<git origin owner>)
--cd [argocd|helm-push|skip]- Continuous delivery mode (default: skip; requires --deployment-target kubernetes)
--auth-policy [shared-bearer|jwt|custom]- Authentication policy (default: shared-bearer). jwt verifies per-user OIDC tokens; custom is a fail-closed stub the project implements
--api-policy FILE- Seed api-policy.yaml (the outbound APIs tools may call, and how) from this file; validated before the project is created
--process TEXT- Governing process document (path or string) recorded as process: in the manifest and rendered into the guidance file
-p, --prototype- Minimal project: deployment target defaults to 'none' unless given, CD is forced to 'skip'
-dir, --agent-directory TEXT- Name of the agent directory (overrides template default)
--agent-guidance-filename TEXT- Filename for agent guidance (e.g. AGENTS.md, CLAUDE.md, GEMINI.md) [default: AGENTS.md]
-bt, --base-template TEXT- Base template to use (overrides template default, only for remote templates)
-i, --interactive- Enable interactive prompts for human use
-y, --auto-approve, --yes- Non-interactive: skip prompts and use defaults
-s, --skip-checks- Skip preflight checks (uv on PATH)
--debug- Enable debug logging
--help- Show this message and exit.
graph-agents-cli deploy¶
Deploy the agent to Kubernetes (mode depends on the project's CD setting).
Modes (from create_params.cd in the manifest):
skip direct: build, local-load or push, apply the Secret, helm upgrade
helm-push CI builds and pushes; deploy --image runs helm only
argocd never runs helm: writes image.tag into values-<env>.yaml and opens a PR
Outside dev the kube context must be recorded in the manifest
(environments.<env>.context) or passed with --context; the kubeconfig's
current context is used only after a confirmation (or --yes).
Usage:
Options:
--env TEXT- Target environment (dev, staging, prod). [required]
--image TEXT- Image reference to deploy instead of building one (CI mode).
--env-file TEXT- Env file for the Secret; defaults to .env.<env> (dev also falls back to .env).
--context TEXT- Kube context to use instead of environments.<env>.context.
-y, --yes- Accept the kubeconfig's current context outside dev without prompting.
--status- Report the rollout, pods and warning events instead of deploying (exit 1 when not ready within --timeout, default 60s).
--restart- Rollout-restart the Deployment (after a Secret rotation) and wait for the new pods.
--force-direct- helm-push mode: allow a deploy to staging/prod from outside CI.
--dry-run- Print every command; run
helm templateinstead of upgrade. --tag TEXT- Image tag for a local build (default: short git sha, plus -dirty-<time> for uncommitted changes; a timestamp outside git).
--timeout TEXT- How long to wait for the rollout (e.g. 300s, 10m; default 5m, 60s for --status).
--atomic / --no-atomic- Roll back a failed rollout (after printing pod diagnostics). [default: atomic]
--rotate-api-key- Replace the live API_KEY with the one in the env file (otherwise the live key wins).
--help- Show this message and exit.
graph-agents-cli eval¶
Evaluate agents and compare results.
Core:
run Chain generate + grade in one command
generate Run the agent over the eval dataset and write traces
grade Grade traces against checks and judges; apply the gate
compare Compare two eval results files
metric Discover evaluation metrics
Analysis and sharing:
analyze Cluster failures by reason (optionally judge-summarised)
submit Upload a dataset and results to LangSmith (optional)
Exit codes (run, generate, grade):
0 gate met, 1 gate failed, 2 incomplete run, 3 configuration error
Usage:
Options:
--help- Show this message and exit.
Subcommands
- analyze: Cluster failed, quality-below-threshold, error and missing cases by reason.
- compare: Compare two eval results files (baseline, candidate).
- generate: Run the agent over the eval dataset and write traces.
- grade: Grade traces against the dataset's checks and judges and apply the gate.
- metric: Discover evaluation metrics: deterministic checks and judges.
- run: Chain
eval generateandeval gradein one command. - submit: Upload the dataset and a results file to LangSmith as an experiment.
graph-agents-cli eval analyze¶
Cluster failed, quality-below-threshold, error and missing cases by reason.
Grouping is deterministic (status, check or metric, masked message), so two runs of the same results file produce the same clusters. With --judge the clusters are also summarised by the judge model through the project's judge runner. The analysis is written to artifacts/analysis_<ts>.json.
Usage:
Options:
--results TEXT- Results file. Defaults to the newest artifacts/grade_results/results_<ts>.json.
--output TEXT- Analysis file. Defaults to artifacts/analysis_<ts>.json.
--top-k INTEGER RANGE- Print only the K largest clusters. [x>=1]
--judge- Ask the judge model for root causes and fixes per cluster.
--judge-provider TEXT- Override the judge provider (with --judge).
--judge-model TEXT- Override the judge model (with --judge).
--help- Show this message and exit.
graph-agents-cli eval compare¶
Compare two eval results files (baseline, candidate).
Reports per-case status changes, quality pass-rate deltas and summary deltas. A regression is a case whose status got worse (or disappeared), a quality metric whose pass rate dropped or stopped meeting its min_pass_rate, or a worse exit code. Purely in-process.
Usage:
Options:
--fail-on-regression- Exit 1 when the candidate regresses.
--json- Print the full comparison as JSON instead of tables.
--help- Show this message and exit.
graph-agents-cli eval generate¶
Run the agent over the eval dataset and write traces.
Each case's user messages are sent to POST /chat (SSE) and the events are folded into one trace per case: response, tool calls, usage, latency, thread and run ids, and a status of ok, error or missing. The trace file records the dataset hash so eval grade can account for every planned case.
Without --url the local server is started through run's server manager and stopped after the run. Credentials follow the project's auth policy, locally and with --url. Put a bearer credential in GRAPH_AGENTS_CLI_API_KEY (sent as 'Authorization: Bearer <value>'): unlike --header, it stays out of the process list and your shell history.
shared-bearer GRAPH_AGENTS_CLI_API_KEY=<API_KEY> (locally: the API_KEY in .env)
jwt GRAPH_AGENTS_CLI_API_KEY=<token> (locally: auth dev-token)
custom --header 'Name: value' or --cookie name=value
With --url every tool the agent calls runs for real in that environment (a warning names the target first): cases that create, change or delete data do so there. Use a dedicated test identity and data you can reset.
A call the API policy gates (an approval block) pauses the run; it is decided as the case's "approvals" instructions say ({"decision": "approve"|"reject", "match": {...}}) and the run continues. A gate no instruction matches makes the case an error: generate never approves on its own, and rejects such a gate (as it does one whose decision was refused) so that no approval is left pending; one it may not reject goes with the case's thread, which it deletes as the eval identity (deleting a thread deletes its approvals). The trace records how (approvals[].cleanup), and the case error names a gate it could neither reject nor delete, which stays pending until it expires or an approver decides it (approves or rejects). A gate that lists requester is decided as the eval identity (it started the run); any other with GRAPH_AGENTS_CLI_APPROVER_API_KEY as a bearer credential when it is set (a principal holding the gate's role).
Exit codes:
0 every case produced a trace with a response
2 at least one case is error or missing (summary on stderr)
3 configuration error (no dataset, malformed case, no project)
Usage:
Options:
--dataset TEXT- Dataset file, or a directory of *.json datasets. Defaults to tests/eval/datasets/basic-dataset.json, else every *.json in tests/eval/datasets/.
-o, --output TEXT- Traces file, or a directory to write traces_<ts>.json into. Defaults to artifacts/traces/traces_<ts>.json.
--url TEXT- Base URL of a running agent (its POST /chat). Its tools run for real in that environment, write tools included. When omitted the project's local server is started for the run and stopped afterwards.
--concurrency INTEGER RANGE- Cases run in parallel, each on its own thread. [default: 4; x>=1]
-H, --header TEXT- Extra HTTP header 'Key: Value' (repeatable). For a bearer credential use GRAPH_AGENTS_CLI_API_KEY instead (argv is visible to other local users); an Authorization header overrides it.
--cookie TEXT- Cookie 'name=value' (repeatable), for a custom auth policy that reads cookies.
--app-name TEXT- Agent name recorded in the traces and sent as request metadata. Defaults to agent_directory.
--timeout FLOAT RANGE- Seconds allowed per chat call. [default: 300.0; x>=1]
--help- Show this message and exit.
graph-agents-cli eval grade¶
Grade traces against the dataset's checks and judges and apply the gate.
Deterministic checks run in-process first; judge metrics and custom metrics run inside the project's environment through the staged judge runner. Every planned case ends as passed, failed, quality_below_threshold, error or missing, and the results file records the per-status counts.
Exit codes:
0 gate met
1 a case failed, or a quality metric is under its min_pass_rate
2 a case is error or missing (incomplete run)
3 configuration error (unknown metric, unreachable judge, no threshold)
Usage:
Options:
--traces PATH- Traces file, or a directory whose *.json files are merged (all from one dataset). Defaults to the newest artifacts/traces/traces_<ts>.json.
--dataset TEXT- Dataset file or directory to re-read for planned-case accounting and expectations. Defaults to the dataset recorded in the traces (falling back to the cases embedded in them).
--config PATH- Eval config (judge, quality_metrics, judges, custom_metrics). Defaults to tests/eval/eval_config.yaml.
-o, --output TEXT- Results file, or a directory to write results_<ts>.json into. Defaults to artifacts/grade_results/results_<ts>.json.
--judge-provider TEXT- Override the judge model provider for this run.
--judge-model TEXT- Override the judge model name for this run.
--judge-timeout INTEGER RANGE- Seconds allowed for the judge runner (all judge calls of the run). [default: 600; x>=1]
--help- Show this message and exit.
graph-agents-cli eval metric¶
Discover evaluation metrics: deterministic checks and judges.
Usage:
Options:
--help- Show this message and exit.
Subcommands
- list: List deterministic checks and built-in judges (plus this project's config).
graph-agents-cli eval metric list¶
List deterministic checks and built-in judges (plus this project's config).
Usage:
Options:
--json- Print the catalogue as JSON.
--help- Show this message and exit.
graph-agents-cli eval run¶
Chain eval generate and eval grade in one command.
Credentials are those of eval generate: a bearer credential goes in GRAPH_AGENTS_CLI_API_KEY (locally, a shared-bearer project's API_KEY in .env is used; a jwt project needs a token, e.g. from graph-agents-cli auth dev-token --sub <user>), never on the command line.
Traces go to a fresh artifacts/traces/traces_<ts>.json and are graded immediately. An extension that overrides eval generate or eval grade is dispatched exactly as the standalone command would be. The exit code is the worse of the two stages (0 gate met, 1 gate failed, 2 incomplete, 3 configuration error).
Usage:
Options:
--dataset TEXT- Dataset file or directory. Forwarded to
eval generate. --url TEXT- Base URL of a running agent; its tools run for real there, write tools included. Forwarded to
eval generate. --concurrency INTEGER RANGE- Cases run in parallel. Forwarded to
eval generate. [default: 4; x>=1] -H, --header TEXT- Extra HTTP header 'Key: Value' (repeatable). For a bearer credential use GRAPH_AGENTS_CLI_API_KEY instead (argv is visible to other local users).
--cookie TEXT- Cookie 'name=value' (repeatable).
--app-name TEXT- Agent name recorded in the traces.
--timeout FLOAT RANGE- Seconds allowed per chat call. Forwarded to
eval generate. [default: 300.0; x>=1] --config PATH- Eval config. Forwarded to
eval grade. -o, --output TEXT- Results file or directory. Forwarded to
eval grade. --judge-provider TEXT- Override the judge provider. Forwarded to
eval grade. --judge-model TEXT- Override the judge model. Forwarded to
eval grade. --judge-timeout INTEGER RANGE- Seconds allowed for the judge runner. Forwarded to
eval grade. [default: 600; x>=1] --help- Show this message and exit.
graph-agents-cli eval submit¶
Upload the dataset and a results file to LangSmith as an experiment.
Creates or updates the dataset and its examples (one per case, keyed by case id), then creates an experiment whose runs carry each case's response, tool calls and status, with feedback scores for the gate, every deterministic check and every judge metric. Requires LANGSMITH_API_KEY in the environment or the project's .env, and the langsmith extra.
Usage:
Options:
--results TEXT- Results file. Defaults to the newest artifacts/grade_results/results_<ts>.json.
--traces TEXT- Traces file or directory. Defaults to the traces recorded in the results.
--dataset TEXT- Dataset file or directory. Defaults to the dataset recorded in the results.
--dataset-name TEXT- LangSmith dataset name. Defaults to '<project>-eval'.
--experiment TEXT- LangSmith experiment (project) name. Defaults to '<dataset-name>-<graded_at>'.
--endpoint TEXT- LangSmith API URL. Defaults to LANGSMITH_ENDPOINT.
--help- Show this message and exit.
graph-agents-cli extension¶
Manage graph-agents-cli extensions (experimental).
Experimental: the manifest schema and the command surface may still change in a breaking way. Pin the CLI version if you depend on either.
Subcommands:
add Add an extension from a git reference or local path
list List active extensions and the commands they contribute
update Advance extension pins to the latest tracked ref
remove Remove an installed extension
Usage:
Options:
--help- Show this message and exit.
Subcommands
- add: Add an extension from a git reference or local path.
- list: List active extensions and the commands they contribute.
- remove: Remove an installed extension (checks project then user scope).
- update: Advance extension pins (re-resolve the tracked ref).
graph-agents-cli extension add¶
Add an extension from a git reference or local path.
Usage:
Options:
--global- Install for all projects (user scope, global/org-wide). Default is project scope (committed to this repo only), so the extension cannot affect your other projects.
--ref TEXT- Pin a branch, tag, or SHA.
-i, --interactive- Enable interactive confirmation prompt.
-y, --yes, --auto-approve- Skip confirmation prompt.
--help- Show this message and exit.
graph-agents-cli extension list¶
List active extensions and the commands they contribute.
Usage:
Options:
--help- Show this message and exit.
graph-agents-cli extension remove¶
Remove an installed extension (checks project then user scope).
Usage:
Options:
-i, --interactive- Enable interactive confirmation prompt.
-y, --yes, --auto-approve- Skip confirmation prompt.
--help- Show this message and exit.
graph-agents-cli extension update¶
Advance extension pins (re-resolve the tracked ref).
Updates every installed extension when NAME is omitted. The tracked ref is resolved first: an extension whose code did not change is reported as up to date without a trust prompt. New third-party code needs your trust (a prompt, or -y); without a terminal to ask on it keeps its pin and the command exits 1.
Usage:
Options:
-i, --interactive- Enable interactive confirmation prompt.
-y, --yes, --auto-approve- Skip confirmation prompt.
--help- Show this message and exit.
graph-agents-cli info¶
Show project configuration, paths, and CLI version.
The installed skills come from npx skills list, which is not run (and reported as not listed) with GRAPH_AGENTS_CLI_NO_UPDATE_CHECK=1 or in CI.
Usage:
Options:
--json- Output as JSON.
--help- Show this message and exit.
graph-agents-cli infra¶
Check cluster and repository prerequisites (read-only).
Usage:
Options:
--help- Show this message and exit.
Subcommands
- check: Report which prerequisites exist for the selected environment and mode.
graph-agents-cli infra check¶
Report which prerequisites exist for the selected environment and mode.
Usage:
Options:
--env TEXT- Environment to check the cluster for (dev, staging, prod).
--profile [disconnected]- Also verify the named profile (disconnected: no hosted dependency).
--json- Print the report as JSON.
--help- Show this message and exit.
graph-agents-cli install¶
Install project dependencies.
Usage:
Options:
--clean- Delete and recreate the uv virtual environment (e.g. after moving the project folder).
--locked- Assert that uv.lock is up to date with pyproject.toml; fail instead of updating it.
--help- Show this message and exit.
graph-agents-cli lint¶
Run code quality checks and the API-policy check.
ruff check . (--fix applies fixes)
ruff format . --check (--fix reformats in place)
API-policy check api-policy.yaml must pass the strict schema, and
every API_CALLS entry of every tool must name a
declared API and be allowed by its rules (and
exist in its OpenAPI spec when one is named)
Response schema <agent directory>/response_schema.json, when the
project has one (structured final answers), must
be a schema the agent starts with; a warning when
agent.py does not pass response_format() to the
agent or has no StructuredAnswer() in its
middleware
Exit codes:
0 clean
1 a refused call or an unreadable API_CALLS, or ruff failed
3 configuration error: an invalid api-policy.yaml or response
schema, the retired product policy, or not in a project
Usage:
Options:
--fix- Auto-fix lint and formatting issues.
--policy-only- Run only the API-policy check (skip ruff).
--help- Show this message and exit.
graph-agents-cli login¶
Check model provider keys, LangSmith, and kubeconfig; optionally write .env.
A preflight, not an authentication: nothing is stored. Exit code 1 when any check fails (0 with --status).
Usage:
Options:
--profile [default|disconnected]- 'disconnected' fails on any hosted dependency. [default: default]
--cluster- Also run 'kubectl cluster-info' against the current context (fails when unreachable).
--write-env- Prompt for missing keys and write them to .env (blank KEY= lines are filled in place; the file is kept 0600; values are never echoed).
--env-file FILE- The .env file to read (and write with --write-env). Default: <project>/.env or ./.env.
--status- Print the report and exit 0 even when a check fails.
--json- Emit the report as JSON.
--help- Show this message and exit.
graph-agents-cli peer¶
Declare the other agents this agent asks, over A2A (its peers).
A peer is an api-policy.yaml API with protocol: a2a. peer add NAME writes it (the endpoint, the JSON-RPC methods it may send, the approve gate or its denial, the credential, the limits) with the manifest, .env.example and chart values that follow, and regenerates <agent_dir>/tools/a2a_peers.py, which gives the model ask_agent and, for peers it relays approvals to, approve_agent_action. It then prints what is left to set, here and on the peer. Every change is validated, shown as one diff and written atomically; --dry-run prints the diff only. .env is never touched.
Exit codes:
0 changed, or nothing to change
1 show --check: the peer is unreachable, or its card names another endpoint
2 usage error
3 not in a project, a 0.2 runtime, an invalid policy, or a change it cannot make
Usage:
Options:
--help- Show this message and exit.
Subcommands
- add: Add another agent this agent asks (a protocol: a2a API), and regenerate tools/a2a_peers.py.
- list: List the peers: name, API, URL, auth, audience, approvals and limits.
- remove: Remove a peer (its API and variables), and regenerate or delete tools/a2a_peers.py.
- show: Show a peer's entry and what is left to set; --check reads its card.
- sync: Regenerate tools/a2a_peers.py from api-policy.yaml (after
scaffold upgrade, orapiedits).
graph-agents-cli peer add¶
Add another agent this agent asks (a protocol: a2a API), and regenerate tools/a2a_peers.py.
Defaults fit a peer made with graph-agents-cli: its endpoint /a2a/NAME, the credential by this project's auth policy (jwt: a token exchanged for the user's, audience NAME), SendMessage and GetTask, the person's approval relayed through a gate here, 12 calls per run, a 120 s read timeout and a 1 MiB answer cap. It prints what is left to set: here, at the issuer, and on the peer (AUTH_ALLOWED_ACTORS, and the api approval --decide-with relayed --relayers line that lets this agent relay there).
Usage:
Options:
--api-name TEXT- The API's name (default <NAME>_agent).
--url-env TEXT- Base URL variable (default <NAME>_AGENT_URL).
--path TEXT- The peer's A2A endpoint (default /a2a/<NAME>: its agent directory or A2A_NAME).
--auth [exchange|forward|bearer]- Default by the auth policy: jwt exchange, custom forward, shared-bearer bearer.
--audience TEXT- exchange: the audience the issuer mints for (default NAME); forward (jwt): forward_audience.
--scope TEXT- exchange: the scopes to ask for.
--resource TEXT- exchange: the resource indicator.
--allow-actorless- exchange: accept exchanged tokens that name no actor; the peer must then set AUTH_JWT_DIRECT_CLIENTS and list client:<this agent's client id>.
--token-env TEXT- bearer: the key's variable (default <NAME>_AGENT_KEY).
--description TEXT- What the peer does, for the model's roster (at most 300 characters).
--card URL|FILE- Read the description, the path and origin support from the peer's agent card.
--calls TEXT- What the agent may send: ask (SendMessage), status (GetTask), cancel (CancelTask). [default: ask,status]
--approvals [relay|deny]- relay: messages that approve the peer's pending approvals wait for the person here (gated: requester); deny: this agent never sends them. [default: relay]
--approval-timeout-s INTEGER RANGE- [default: 900; 30<=x<=86400]
--max-calls-per-run INTEGER RANGE- [default: 12; x>=1]
--read-timeout-ms INTEGER RANGE- A peer runs a model: its answers take time. [default: 120000; x>=1]
--max-response-bytes INTEGER RANGE- [default: 1048576; 1<=x<=67108864]
--cluster-url TEMPLATE- The peer's URL per environment, with {env}, for values-<env>.yaml (e.g. http://orders-agent.orders-agent-{env}.svc.cluster.local).
--dry-run- Print the diff only.
--help- Show this message and exit.
graph-agents-cli peer list¶
List the peers: name, API, URL, auth, audience, approvals and limits.
Usage:
Options:
--json- Print JSON.
--help- Show this message and exit.
graph-agents-cli peer remove¶
Remove a peer (its API and variables), and regenerate or delete tools/a2a_peers.py.
Usage:
Options:
--dry-run- Print the diff only.
--help- Show this message and exit.
graph-agents-cli peer show¶
Show a peer's entry and what is left to set; --check reads its card.
Usage:
Options:
--json- Print JSON.
--check- Read the peer's card (no credential) and check its endpoint; exit 1 when it fails.
--help- Show this message and exit.
graph-agents-cli peer sync¶
Regenerate tools/a2a_peers.py from api-policy.yaml (after scaffold upgrade, or api edits).
Usage:
Options:
--dry-run- Print the diff only.
--help- Show this message and exit.
graph-agents-cli playground¶
Start the application locally with reload and the dev chat page.
fastapi uv run uvicorn <agent_dir>.fast_api_app:app --reload (APP_ENV=dev)
langgraph-server uv run langgraph dev --no-browser
--graph uv run langgraph dev (LangGraph Studio) under either runtime
The chat page at /playground talks to the same /chat endpoint and auth policy that run and eval generate use.
Usage:
Options:
--port INTEGER RANGE- Port the application listens on (refused when already in use). [default: 8000; 1<=x<=65535]
--graph- Run
langgraph devfor LangGraph Studio graph debugging (bypasses the auth policy). --no-open- Do not open the browser.
--help- Show this message and exit.
graph-agents-cli run¶
Run the agent with a single prompt (non-interactive).
MESSAGE is the prompt to send to the agent.
Run from your project directory to query the agent locally. A plain run
starts a one-off server (uvicorn under the fastapi runtime, langgraph dev
under langgraph-server) and shuts it down when it finishes; pass
--start-server to keep it running. Later plain runs reuse a running
server. Stop it with --stop-server. After 30 minutes idle, the next
request restarts it, or reuses it with a warning when the operating
system refuses to stop it (a sandbox may let a command signal only what
it started itself). The server listens on the first free port of
18080-18089, or on --port / GRAPH_AGENTS_CLI_RUN_PORT when given.
Use --url to query a deployed agent instead. --mode selects the protocol
(default chat). Credentials follow the project's auth policy, locally and
with --url. Put a bearer credential in GRAPH_AGENTS_CLI_API_KEY (sent as
'Authorization: Bearer <value>'): unlike --header, it stays out of the
process list and your shell history.
shared-bearer GRAPH_AGENTS_CLI_API_KEY=<API_KEY> (locally: the API_KEY in .env)
jwt GRAPH_AGENTS_CLI_API_KEY=<token> (locally: auth dev-token)
custom --header 'Name: value' or --cookie name=value
--thread-id continues a conversation; the footer of every run, one that
ends with an error included, prints the thread id and the command to
resume it. --file attaches UTF-8 text files as extra context.
A call gated by the API policy (an approval block in api-policy.yaml)
pauses the run before it is sent, and the call is printed in full. On a
terminal, when the requester is an approver, "Approve? [y/N]" decides
it (Enter rejects) and the run continues. Otherwise the run ends with an
"Awaiting approval" line and the `graph-agents-cli approvals approve` /
`reject` commands that decide it; a one-off local server with an
in-memory checkpointer is then kept running so the paused run survives.
Exit codes:
0 the agent answered, or the run is awaiting an approval
1 the agent refused or reported an error (HTTP error, error event), or
the decision was refused (not an approver, already decided, expired)
2 the agent could not be reached or went silent; --stop-server could
not stop the local server (the processes still running are named,
and its record is kept)
3 configuration error (no project, port unavailable)
Usage:
Options:
--mode [chat|a2a]- Protocol: 'chat' (POST /chat, SSE) or 'a2a' (JSON-RPC via a2a-sdk). [default: chat]
--url TEXT- Base URL of a deployed agent. If given, no local server is started.
--thread-id TEXT- Continue an existing thread (printed in the footer of a previous run).
-H, --header TEXT- Custom HTTP header ('Key: Value'). Repeatable. An Authorization header overrides GRAPH_AGENTS_CLI_API_KEY; prefer the variable for bearer credentials (argv is visible to other local users).
--cookie TEXT- Cookie ('name=value'), for a custom auth policy that reads cookies. Repeatable.
-f, --file FILE- Attach a UTF-8 text file as extra context. Repeatable.
--start-server- Keep the local server running after execution. It persists until stopped with --stop-server, so later runs are faster and in-memory threads survive.
--stop-server- Stop the local background server and exit. Exit 2, naming the processes still running, when the operating system refuses to stop them (the record is kept).
--port INTEGER RANGE- Port for the local server this run starts (default: the first free one of 18080-18089, or GRAPH_AGENTS_CLI_RUN_PORT). Refused when the port is in use. [1<=x<=65535]
-v, --verbose- Also print each event on one compact line (text deltas are counted, not repeated).
--help- Show this message and exit.
graph-agents-cli scaffold¶
Scaffold, enhance, and upgrade agent projects.
Subcommands:
create Create a new agent project
enhance Add or change the deployment target, CD mode, or runtime of a project
upgrade Upgrade project to a newer graph-agents-cli version
Usage:
Options:
--help- Show this message and exit.
Subcommands
- create: Create a LangGraph agent project from a template.
- enhance: Add or change the deployment target, CD mode, or runtime of an existing project.
- upgrade: Upgrade project to a newer graph-agents-cli version.
graph-agents-cli scaffold create¶
Create a LangGraph agent project from a template.
Usage:
Options:
-a, --agent TEXT- Template to use: a bundled agent (default: langgraph), a local path (
local@/path/to/template), or a remote spec (org/repo/path@ref,https://github.com/org/repo/tree/main/path). -o, --output-dir PATH- Output directory for the project (default: current directory)
--response-schema FILE- Structured final answers: seed <agent directory>/response_schema.json (the JSON Schema of the agent's final answer) from this file; checked before the project is created
--runtime [fastapi|langgraph-server]- Application runtime (default: fastapi)
--model-provider [openai|anthropic|gemini|openai-compatible]- Model provider (default: openai; prompted in interactive mode)
--model TEXT- Model name (default: the provider's default model)
--checkpointer [memory|postgres]- Deployed checkpointer (default: postgres for kubernetes, memory for none)
-d, --deployment-target [kubernetes|none]- Deployment target (default: kubernetes)
--registry TEXT- Container registry <url/org> (default: ghcr.io/<git origin owner>)
--cd [argocd|helm-push|skip]- Continuous delivery mode (default: skip; requires --deployment-target kubernetes)
--auth-policy [shared-bearer|jwt|custom]- Authentication policy (default: shared-bearer). jwt verifies per-user OIDC tokens; custom is a fail-closed stub the project implements
--api-policy FILE- Seed api-policy.yaml (the outbound APIs tools may call, and how) from this file; validated before the project is created
--process TEXT- Governing process document (path or string) recorded as process: in the manifest and rendered into the guidance file
-p, --prototype- Minimal project: deployment target defaults to 'none' unless given, CD is forced to 'skip'
-dir, --agent-directory TEXT- Name of the agent directory (overrides template default)
--agent-guidance-filename TEXT- Filename for agent guidance (e.g. AGENTS.md, CLAUDE.md, GEMINI.md) [default: AGENTS.md]
-bt, --base-template TEXT- Base template to use (overrides template default, only for remote templates)
-i, --interactive- Enable interactive prompts for human use
-y, --auto-approve, --yes- Non-interactive: skip prompts and use defaults
-s, --skip-checks- Skip preflight checks (uv on PATH)
--debug- Enable debug logging
--help- Show this message and exit.
graph-agents-cli scaffold enhance¶
Add or change the deployment target, CD mode, or runtime of an existing project.
Applies a template in-place, adding infrastructure files without touching your agent logic. It always enhances the current directory.
TEMPLATE_PATH says which template to apply, not which project to enhance. It defaults to the current directory, which re-renders the scaffolding from the base template and puts your files back on top.
If the project has a graph-agents-cli-manifest.yaml, the template recorded there is re-applied and TEMPLATE_PATH is ignored. Pass a local directory or a remote spec (org/repo@tag) for a project graph-agents-cli did not create.
--base-template is separate. It names a base template this CLI ships, which sits underneath whatever TEMPLATE_PATH supplies.
api-policy.yaml is never touched by enhance: it belongs to the project; change it with graph-agents-cli api.
A runtime or model-provider change is applied to the files it shapes, including ones you edited (the chart values key by key, around your edits). What cannot be applied is listed under 'Left for you'; the steps marked (required) leave the image or the chart on the old settings (an edited Dockerfile gets the new version beside it as Dockerfile.new).
Use --dry-run to preview changes before applying them.
Exit codes:
0 applied (anything left for you is optional)
1 applied, but steps marked (required) are left for you
2 usage error (e.g. a model chosen for another provider)
3 configuration error (no project for --dry-run, a legacy policy file)
Usage:
Options:
-n, --name TEXT- Project name for templating (default: the manifest's name, else the current directory name)
--runtime [fastapi|langgraph-server]- Application runtime (default: fastapi)
--model-provider [openai|anthropic|gemini|openai-compatible]- Model provider (default: openai; prompted in interactive mode)
--model TEXT- Model name (default: the provider's default model)
--checkpointer [memory|postgres]- Deployed checkpointer (default: postgres for kubernetes, memory for none)
-d, --deployment-target [kubernetes|none]- Deployment target (default: kubernetes)
--registry TEXT- Container registry <url/org> (default: ghcr.io/<git origin owner>)
--cd [argocd|helm-push|skip]- Continuous delivery mode (default: skip; requires --deployment-target kubernetes)
--auth-policy [shared-bearer|jwt|custom]- Authentication policy (default: shared-bearer). jwt verifies per-user OIDC tokens; custom is a fail-closed stub the project implements
--process TEXT- Governing process document (path or string) recorded as process: in the manifest and rendered into the guidance file
-p, --prototype- Minimal project: deployment target defaults to 'none' unless given, CD is forced to 'skip'
-dir, --agent-directory TEXT- Name of the agent directory (overrides template default)
--agent-guidance-filename TEXT- Filename for agent guidance (e.g. AGENTS.md, CLAUDE.md, GEMINI.md) [default: AGENTS.md]
-bt, --base-template TEXT- Base template to use (overrides template default, only for remote templates)
-i, --interactive- Enable interactive prompts for human use
-y, --auto-approve, --yes- Non-interactive: skip prompts and use defaults
-s, --skip-checks- Skip preflight checks (uv on PATH)
--debug- Enable debug logging
--force- Force overwrite all files (skip smart-merge comparison)
--dry-run, --dryrun- Preview changes without applying them (requires saved metadata)
--prefer-new- Resolve conflicts in favor of the new template version
--help- Show this message and exit.
graph-agents-cli scaffold upgrade¶
Upgrade project to a newer graph-agents-cli version.
Applies a 3-way merge between the old template, the new template, and your project: unmodified files are auto-updated, your customizations are preserved, and conflicts are surfaced for manual resolution (with --interactive) or kept as-is.
The old template is regenerated by the exact CLI build that scaffolded the project: its release, or the commit the manifest records for a build between releases (--baseline-ref names it when the manifest cannot). If that build cannot be fetched and run, the upgrade stops with no changes; pass --baseline current to compare against the current templates instead (the summary is labelled accordingly).
Usage:
Options:
--dry-run, --dryrun- Preview changes without applying them
-y, --auto-approve, --yes- Auto-apply non-conflicting changes without prompts
-i, --interactive- Enable interactive prompts for human use
--baseline [authentic|current]- Which templates render the old snapshot: 'authentic' runs the exact build that created the project through uvx and stops if it cannot; 'current' is an explicit opt-in to compare against the current templates instead [default: authentic]
--baseline-ref REF- The build that created the project, when the manifest cannot name it (a project from a build between releases, or a missing release tag): a commit or tag of the repository, <clone>@<commit> for a local clone, a path to a checkout or wheel, or a full install spec. Also upgrades a project of this same version.
--debug- Enable debug logging
--help- Show this message and exit.
graph-agents-cli secrets¶
Provision and inspect the application Secret per environment.
Subcommands:
apply Create or update <name>-app from the allow-listed keys of an env file
status List which allow-listed keys are present (values are never printed)
Usage:
Options:
--help- Show this message and exit.
Subcommands
- apply: Create or update the app Secret from the allow-listed keys of an env file.
- status: List which allow-listed keys are present in the app Secret (never values).
graph-agents-cli secrets apply¶
Create or update the app Secret from the allow-listed keys of an env file.
Usage:
Options:
--env TEXT- Target environment (dev, staging, prod). [required]
--env-file TEXT- Env file; defaults to .env.<env> (dev also falls back to .env).
--context TEXT- Kube context to use instead of environments.<env>.context.
-y, --yes- Accept the kubeconfig's current context outside dev without prompting.
--rotate-api-key- Replace the live API_KEY with the one in the env file (otherwise the live key wins).
--dry-run- Print the kubectl pipeline and a redacted manifest.
--help- Show this message and exit.
graph-agents-cli secrets status¶
List which allow-listed keys are present in the app Secret (never values).
Exit codes (usable as a CI or pre-deploy gate):
0 the Secret holds every required key (optional ones may be missing)
1 the Secret is missing, or a required key is (any key with --strict)
2 kubectl failed (unreachable cluster, credentials, RBAC)
3 configuration error (unknown environment or kube context, no manifest)
Required keys follow the environment's chart values: the model provider's key
(not for openai-compatible), API_KEY under shared-bearer, AUTH_JWT_SECRET under
jwt with an HS* algorithm, and POSTGRES_DSN or DATABASE_URI/REDIS_URI unless the
bundled subchart provides them.
Usage:
Options:
--env TEXT- Target environment (dev, staging, prod). [required]
--context TEXT- Kube context to use instead of environments.<env>.context.
--strict- Also exit 1 when an optional allow-listed key is missing.
--dry-run- Print the kubectl command without running it.
--help- Show this message and exit.
graph-agents-cli setup¶
Install graph-agents-cli and skills to detected coding agents.
Installs the graph-agents-cli tool (via uv tool install) and detects installed coding agents (Claude Code, Antigravity, Codex, Gemini CLI, Cursor, etc.) to install the LangGraph development skills via npx skills. The skills come from this repository at the tag of the running release (the default branch for a development build), falling back to the copy bundled with the CLI when that fails.
By default, skills are installed globally for all detected agents. Use --workspace to install at the project level instead. Use --agent to specify specific coding agents (e.g. --agent claude-code --agent cursor) or 'all'. Use --dry-run to preview what would happen without executing. Use --dev to install graph-agents-cli as editable from the local repo (for contributors).
This command stores no credentials; run 'graph-agents-cli login' to check provider keys and kubeconfig.
Usage:
Options:
--workspace- Install to project/workspace scope instead of global. Skills are installed relative to the current directory.
--dry-run, --dryrun- Show what would be done without making changes.
--dev- Install as editable from the local repo (for contributors).
--skills-source TEXT- Skills source: local path, GitHub owner/repo, or URL (default: this repository at the running release's tag; no fallback to the bundled copy).
--agent TEXT- Specify the agent to install skills to (e.g. --agent claude-code --agent cursor). Use 'all' to install for all supported agents.
--help- Show this message and exit.
graph-agents-cli system¶
Check, wire and deploy agents that call each other, as one system.
graph-agents-system.yaml (in this directory or above, or --file) names the agent projects that call each other over A2A: each agent's project, the client id it exchanges tokens as, the agents it calls, and the environments they run in. Every project stays complete on its own (peer add); the file adds checks across projects, writes both sides of each edge at once, and deploys them in order.
Exit codes:
0 ok
1 check: a finding with an error; deploy: a deploy or the live check failed
2 usage error
3 the file is unreadable or invalid, names an unknown project or an
ambiguous edge, or a project cannot take its edges
Usage:
Options:
--help- Show this message and exit.
Subcommands
- apply: Write each project's side of every edge; idempotent, one diff per project.
- check: Report what would keep the agents from calling each other (SC01-SC15); exit 1 on an error.
- delegations: Print what the token issuer must let each client exchange for (auth: exchange edges),
- deploy: Deploy every project (
graph-agents-cli deploy --env ENV), callees first, a few at a time. - graph: Draw the system: edges with their auth, relay or deny, and how the callee decides;
graph-agents-cli system apply¶
Write each project's side of every edge; idempotent, one diff per project.
In each caller, per edge: what `peer add` writes (the policy entry, the
manifest's secrets.keys, .env.example, the chart values, tools/a2a_peers.py),
with the called agent's A2A path and its name as the audience; per
environment, <PEER>_AGENT_URL, TOKEN_EXCHANGE_URL, and networkPolicy.egressTo
to the called agent's pods; TOKEN_EXCHANGE_CLIENT_ID is the client_id.
In each called agent: appUrl per environment (the URL its callers dial),
AUTH_JWT_AUDIENCE when empty, the callers' client ids in AUTH_ALLOWED_ACTORS,
and networkPolicy.ingressFrom for the callers' pods (plus the Gateway's
namespace while the route publishes paths).
Never written: approval gates (the api approval ... --decide-with relayed line a relay needs is printed), secrets, .env, and local environments (printed). A peer of an agent of the file is removed when it has left calls; other peers and APIs are never touched. An existing peer keeps its limits, timeouts, approval timeout and description.
Usage:
Options:
--file F- The system file (default: graph-agents-system.yaml here or in a parent directory).
--env TEXT- Write the settings of these environments only (repeatable; default: every one).
--dry-run- Print the diffs only.
--help- Show this message and exit.
graph-agents-cli system check¶
Report what would keep the agents from calling each other (SC01-SC15); exit 1 on an error.
SC01 projects, 0.3 runtimes, charts SC09 cycles, delegation depth
SC02 each edge is a peer, as the file SC10 shared database connections
says; tools/a2a_peers.py in step SC11 the callers' secrets.keys, the salt
SC03 the path is the callee's A2A mount SC12 exchange/forward on langgraph-server
SC04 issuer, audience, auth policies SC13 a callee still published publicly
SC05 appUrl = the URL the caller dials SC14 (--live) Services, cards, issuer
SC06 replicas with in-memory A2A tasks SC15 (--live) the Secrets' keys (names)
SC07 relays the callee's gates refuse
SC08 AUTH_ALLOWED_ACTORS lacks a caller
--live uses each project's recorded kube context (environments.<env>.context), and outside dev never the kubeconfig's current one. A local environment's settings are in .env, which is never read.
Usage:
Options:
--file F- The system file (default: graph-agents-system.yaml here or in a parent directory).
--env TEXT- Check one environment (default: every one).
--live- Also ask the cluster and the network: Services, card URLs, the token URL, Secrets.
--json- Print JSON.
--help- Show this message and exit.
graph-agents-cli system delegations¶
Print what the token issuer must let each client exchange for (auth: exchange edges), and what it must guarantee.
Usage:
Options:
--file F- The system file (default: graph-agents-system.yaml here or in a parent directory).
--format [table|json]- [default: table]
--help- Show this message and exit.
graph-agents-cli system deploy¶
Deploy every project (graph-agents-cli deploy --env ENV), callees first, a few at a time.
1. `system check --env ENV` (the files only): an error stops here.
2. The agents deploy in waves, each once the agents it calls are deployed
(a cycle is broken in file order, with a warning), at most --parallel at
once; a failed wave stops the run unless --keep-going.
3. Each agent's build, image load and rollout times are printed.
4. `system check --live --env ENV`.
Projects in argocd mode deploy one at a time (each writes a commit and a pull request, and projects may share a repository).
Outside dev every project must record its kube context (environments.<env>.context in its manifest): the kubeconfig's current context is never used there, and no deploy is asked to confirm one.
Usage:
Options:
--env TEXT- The environment to deploy. [required]
--file F- The system file (default: graph-agents-system.yaml here or in a parent directory).
--parallel INTEGER RANGE- Deploys at once (default: deploy.parallel in the file, else 3). [1<=x<=16]
--only A,B- Deploy these agents only.
--keep-going- Go on after a failed wave.
--skip-check- Skip
system checkbefore (static) and after (--live) the deploys. --dry-run- Pass --dry-run to each deploy (helm template; nothing changes); no live check.
--help- Show this message and exit.
graph-agents-cli system graph¶
Draw the system: edges with their auth, relay or deny, and how the callee decides; agents with their replicas and A2A task store per environment.
Usage:
Options:
--file F- The system file (default: graph-agents-system.yaml here or in a parent directory).
--format [mermaid|dot|json]- [default: mermaid]
--help- Show this message and exit.
graph-agents-cli update¶
Force reinstall skills to all detected coding agents.
Refreshes the installed skills via npx skills, then reinstalls the CLI from the latest GitHub release (best effort) and, when it did, installs that release's skills (pinned to its tag) so the two stay in step.
Usage:
Options:
--workspace- Update workspace-level skills instead of global.
-i, --interactive- Enable interactive confirmation prompt.
-y, --yes, --auto-approve- Skip confirmation prompt.
--help- Show this message and exit.