graph-agents-cli 0.3.1__py3-none-any.whl

graph_agents_cli/skills/data/graph-agents-cli-workflow/references/commands.md

@@ -0,0 +1,419 @@
+# Command reference
+
+Every `graph-agents-cli` command with its flags, as `graph-agents-cli <command> --help` prints
+them. The help is authoritative and ends with a `Source:` line pointing at the implementing file.
+Commands are loaded lazily; nothing imports a model SDK, LangGraph, or a Kubernetes client at
+startup.
+
+| Phase | Commands |
+|---|---|
+| Setup | `setup` · `update` · `login` · `auth dev-token` |
+| Scaffold | `create` (alias of `scaffold create`) · `scaffold enhance` · `scaffold upgrade` |
+| Develop | `playground` · `run` · `install` · `lint` · `build` |
+| Evaluate | `eval run` · `eval generate` · `eval grade` · `eval compare` · `eval analyze` · `eval submit` · `eval metric list` |
+| Deploy | `infra check` · `secrets apply` · `secrets status` · `deploy` |
+| Extend / inspect | `extension add\|list\|remove\|update` · `info` |
+
+Exit codes, for every command: `0` ok; `1` refused by policy or mode, a declined confirmation,
+or a failed gate (a lint violation, an agent that answered with an error, `scaffold enhance`
+with required steps left); `2` tool failure (helm/kubectl/docker/git/gh non-zero or missing from
+`PATH`, a local server that cannot start, an agent that cannot be reached, `uvx` missing or unable
+to fetch the prior build for `scaffold upgrade` or a version-locked `scaffold enhance`, an
+unexpected crash); `3` configuration error (not in a project, an invalid manifest, including a
+missing or unreleased `cli_version` for `scaffold upgrade`, env file, policy, port or kube
+context, an unusable `GRAPH_AGENTS_CLI_INSTALL_SPEC`, a `scaffold upgrade --baseline-ref` that
+names no build or a build of another version). A signal ends a command with 128+N (130 for Ctrl-C, 143 for SIGTERM) after the local
+server it started is stopped. `secrets status` exits `1` when the Secret or a *required* key is
+missing (`--strict`: any allow-listed key). `eval` exit codes are in `/graph-agents-cli-eval`.
+`GRAPH_AGENTS_CLI_DEBUG=1` shows the traceback behind a one-line network, file or parse error.
+
+## Setup
+
+```
+graph-agents-cli setup [--workspace] [--dry-run] [--dev] [--skills-source TEXT] [--agent TEXT]...
+graph-agents-cli update [--workspace] [-i/--interactive] [-y/--yes]
+graph-agents-cli login [--profile default|disconnected] [--cluster] [--write-env] [--env-file FILE] [--status] [--json]
+graph-agents-cli auth dev-token --sub TEXT [--roles TEXT] [--ttl TEXT]
+```
+
+- `setup` installs the CLI (`uv tool install <install spec>`: the running version's git tag, or
+  `GRAPH_AGENTS_CLI_INSTALL_SPEC`) and the six `graph-agents-cli-*` skills into detected coding
+  agents through `npx skills add` from this repository at the running release's tag
+  (`https://github.com/ss7172/graph-agents-cli#v<version>`; the default branch for a development
+  build), falling back to the wheel-bundled copy, then to a direct copy into `~/.agents/skills`
+  (`./.agents/skills` with `--workspace`). `--agent` is repeatable (`claude-code`, `cursor`, ...
+  or `all`); `--dev` installs the CLI editable from the checkout and the skills from it;
+  `--skills-source` picks another source (no fallback). It performs no authentication.
+- `update` refreshes the skills (`npx skills update`), then reinstalls the CLI from the latest
+  GitHub release (`uv tool install --force <install spec>`; skipped when there is no newer
+  release; a failure is a warning, a malformed `GRAPH_AGENTS_CLI_INSTALL_SPEC` is exit 3) and
+  installs that release's skills from its tag.
+- `login` is a preflight check, not an authentication: the provider key for `MODEL_PROVIDER`
+  (`OPENAI_BASE_URL` for `openai-compatible`), the judge key, `LANGSMITH_API_KEY` or an OTLP
+  endpoint when `TRACING_ENABLED=true`, the kube context (`--cluster` also runs
+  `kubectl cluster-info`). Provider precedence: `MODEL_PROVIDER` from the environment or `.env`
+  (the value the app reads at runtime) > the manifest's `create_params.model_provider` > `openai`;
+  `MODEL_PROVIDER=fake` is accepted as the test-only provider (warning, no key check, allowed
+  under the disconnected profile) and `JUDGE_MODEL_PROVIDER=fake` is ok. `--write-env` prompts for
+  missing keys without echoing and writes them to `.env` (default `<project>/.env`, or
+  `--env-file`): a blank `KEY=` line (also `export KEY=` and `KEY=""`) is filled in place, other
+  keys are appended, the file is written atomically and kept at mode 0600 (an existing `.env` is
+  made 0600 even when nothing is missing; plain `login` warns about one other users can read).
+  Under the `shared-bearer` auth policy it also generates a missing `API_KEY` (an unset one is a
+  warning, since the local server answers 503 without it). Under `jwt` it warns when no
+  verification key is set (`AUTH_JWT_JWKS_URL` or `AUTH_JWT_PUBLIC_KEY`) and when
+  `GRAPH_AGENTS_CLI_API_KEY` holds no token for `run` and `eval`, pointing at `auth dev-token`.
+  With stdin closed it writes what it has and names the keys left unset. Exit `1` when any check fails; `--status` prints the report and
+  exits `0`; `--json` emits the report. `--profile disconnected` fails on any hosted dependency. The CLI stores no
+  credentials.
+- `auth dev-token` makes local runs of a `jwt` project work without an identity provider: it
+  creates an RSA key pair in `.graph-agents-cli/dev-jwt/` (git ignored, private key 0600) with
+  the project's Python (`uv run`, so `install` first), fills blank `AUTH_JWT_PUBLIC_KEY`,
+  `AUTH_JWT_ISSUER` (`graph-agents-cli-dev`) and `AUTH_JWT_AUDIENCE` (the project name) in
+  `.env` (values already set are used), and prints only the token on stdout, with the principal
+  in `AUTH_JWT_PRINCIPAL_CLAIM` and `--roles` in `AUTH_JWT_ROLES_CLAIM` (dotted paths nested);
+  `--ttl` defaults to `12h` (at most `7d`). Use it as
+  `export GRAPH_AGENTS_CLI_API_KEY="$(graph-agents-cli auth dev-token --sub alice --roles user)"`.
+  Exit 3 unless the effective policy is `jwt` and `APP_ENV` is exactly `dev`, or when
+  `AUTH_JWT_JWKS_URL` is set, `AUTH_JWT_ALGORITHMS` excludes RS256 or `AUTH_JWT_PUBLIC_KEY`
+  holds another key; exit 2 when the project's environment cannot sign. Restart a kept local
+  server afterwards (`run --stop-server`). Never deploy the dev key.
+
+## Scaffold
+
+```
+graph-agents-cli create [PROJECT_NAME]
+  -a/--agent TEXT           langgraph (default) | local@<path> | <org>/<repo>/<path>@<ref> | https://github.com/org/repo/tree/main/path
+  -o/--output-dir PATH      parent directory (default: current directory)
+  --runtime fastapi | langgraph-server                              (default: fastapi)
+  --model-provider openai | anthropic | gemini | openai-compatible  (default: openai; prompted with -i)
+  --model TEXT                                                      (provider default if omitted)
+  --checkpointer memory | postgres                                  (default: postgres for kubernetes, memory for none)
+  -d/--deployment-target kubernetes | none                          (default: kubernetes)
+  --registry TEXT                                                   (default: ghcr.io/<git origin owner>)
+  --cd argocd | helm-push | skip                                    (default: skip; requires --deployment-target kubernetes)
+  --auth-policy shared-bearer | jwt | custom                        (default: shared-bearer)
+  --api-policy FILE                                                 (validated, then seeds api-policy.yaml; optional)
+  --process TEXT                                                    (path or string recorded as process: and rendered into the guidance file)
+  -p/--prototype                                                    (target defaults to none unless given; CD forced to skip)
+  -dir/--agent-directory TEXT   --agent-guidance-filename TEXT (default AGENTS.md)   -bt/--base-template TEXT (remote templates only)
+  -i/--interactive   -y/--auto-approve/--yes   -s/--skip-checks (skips only the uv-on-PATH preflight)   --debug
+graph-agents-cli scaffold create [PROJECT_NAME] ...                 (same command)
+graph-agents-cli scaffold enhance [TEMPLATE_PATH]
+  -n/--name TEXT plus the create flags above except --api-policy (--runtime, --model-provider,
+  --model, --checkpointer, -d/--deployment-target, --registry, --cd, --auth-policy, --process, -p,
+  -dir, --agent-guidance-filename, -bt, -i, -y, -s, --debug) and
+  --force   --dry-run/--dryrun   --prefer-new
+  (api-policy.yaml belongs to the project: enhance never touches it; use graph-agents-cli api)
+graph-agents-cli scaffold upgrade [PROJECT_PATH] [--dry-run/--dryrun] [-y/--auto-approve/--yes] [-i/--interactive]
+  [--baseline authentic|current] [--baseline-ref REF] [--debug]
+```
+
+`enhance` always enhances the current directory; `TEMPLATE_PATH` names the template to apply and
+is ignored when the manifest records one. A runtime or model-provider change is applied to every
+file it shapes (chart values and `.github/agent.env` merged key by key around your edits) and ends
+with a "Left for you" list; steps marked `(required)` make `enhance` exit 1. Backups go to
+`~/.graph-agents-cli/backups/<dir>_<project id>_<timestamp>` (private; the newest 5 per project are
+kept). Full flag tables and the valid combinations: the `flags.md` reference of
+`/graph-agents-cli-scaffold`.
+
+## Develop
+
+```
+graph-agents-cli playground [--port INTEGER] [--graph] [--no-open]
+graph-agents-cli run MESSAGE [--mode chat|a2a] [--url TEXT] [--thread-id TEXT]
+  [-H/--header 'Key: Value']... [--cookie name=value]... [-f/--file FILE]...
+  [--start-server] [--stop-server] [--port INTEGER] [-v/--verbose]
+graph-agents-cli approvals list [--thread-id TEXT] [--all] [--json] [--url TEXT] [-H]... [--cookie]...
+graph-agents-cli approvals approve|reject APPROVAL_ID [--thread-id TEXT] [--comment TEXT] [-v]
+  [--url TEXT] [-H]... [--cookie]...
+graph-agents-cli install [--clean] [--locked]
+graph-agents-cli lint [--fix] [--policy-only]
+graph-agents-cli build [--tag TEXT] [--registry TEXT] [--push] [--dry-run]
+```
+
+- `playground`: the selected application with reload and the `/playground` page (`APP_ENV=dev`),
+  default port 8000 (a port in use is refused with exit 3 and a free one suggested), browser
+  opened unless `--no-open`. Ctrl-C, SIGTERM or SIGHUP stops the whole server tree. `--graph` runs `langgraph dev` under
+  either runtime for LangGraph Studio; it bypasses the auth policy and the chat API.
+- `run`: default `--mode chat` against the local server it starts (tracked in
+  `.graph-agents-cli/run_server.json`) on the first free port of 18080-18089, or on `--port` /
+  `GRAPH_AGENTS_CLI_RUN_PORT` (exit 3 when that port is taken), or against `--url`. Credentials per auth policy,
+  locally and with `--url`: a bearer credential goes in `GRAPH_AGENTS_CLI_API_KEY`, sent as
+  `Authorization: Bearer <value>` and kept out of argv and shell history (`shared-bearer`: the
+  `API_KEY`, and a local run falls back to the one in `.env`; `jwt`: a token, locally from
+  `auth dev-token`); `--header` or `--cookie` for `custom`. An explicit `--header
+  'Authorization: ...'` wins over the variable. The 401 and 503 hints name what the project's
+  policy needs. `--file` attaches UTF-8 text files as extra context. `--start-server` keeps
+  the local server for later runs (idle timeout 30 minutes: the next run restarts it, or reuses it
+  with a warning when the OS refuses to stop it); `--stop-server` stops it, or exits 2
+  naming the processes still running when the OS refuses the signal (a sandbox may let a command
+  signal only what it started itself), keeping the record so later runs reuse that server. `-v` adds
+  one compact line per SSE event (a run of text deltas is one counted line). The footer (thread
+  id and resume command) is printed after an `error` event too, with the run id; a stream that
+  drops after the run started is reported as such (not as "could not reach"), with the thread
+  to continue. The footer's "Resume with" line prints credential flags redacted
+  (`--header 'Authorization: <redacted>'`, `--cookie name=<redacted>`);
+  re-supply them. A turn silent for 600 s is reported as "no event from the agent" and leaves the
+  server running (a one-off server is still stopped). `--mode a2a` dials the endpoint the agent
+  card names only on the origin it was asked for (another origin: refused, nothing sent; the
+  local server advertises its own address as `APP_URL`) and needs the optional `a2a` extra
+  (the hint prints the `uv tool install` command) and fails with a one-line hint before any server
+  starts when it is absent. A run that pauses on a gated call (the API's `approval` block)
+  prints the call in full (control characters escaped, never cut); on a terminal, when the
+  requester is an approver, it asks `Approve? [y/N]` (Enter rejects) and streams the rest;
+  otherwise (no terminal, a `role:` gate, `--mode a2a`) it prints the approval id and the exact
+  `approvals approve` / `reject` commands and exits 0 with an "Awaiting approval" line, keeping
+  a one-off local server with the in-memory checkpointer running. Streamed agent text and tool
+  output are printed with terminal control characters escaped. Exit codes: `0` answered or
+  awaiting an approval, `1` the agent refused or reported an error, or the server refused a
+  decision, `2` the agent could not be reached or went silent (or the local server could not
+  start), `3` configuration error. A signal during `run` stops the server it started before
+  exiting.
+- `approvals`: the client of the approval routes, for the project's local server (the running
+  one, such as the one a paused `run` kept; with none, a temporary one for `fastapi` with a
+  postgres checkpointer and for `langgraph-server`, whose `langgraph dev` keeps its threads
+  and the approvals in `.langgraph_api/`; not for `fastapi` with the in-memory checkpointer,
+  whose paused run ends with its server) or `--url`, with `run`'s credentials. `list` shows a thread's pending approvals (`--all`: decided ones too),
+  or, without `--thread-id`, every one the caller may see (`GET /approvals`: its own and the
+  ones a role of its may decide; an agent without that route: the caller's own threads);
+  `approve` / `reject` show the call, send only the decision and `--comment`, and stream the
+  resumed run. Exit `1` when the server refuses: not an approver (403),
+  unknown (404), already decided (409), expired (410). Deciding is the approver's act: never
+  approve on the user's behalf.
+- `install`: `uv sync` (`--clean` recreates `.venv`; `--locked` asserts `uv.lock` matches
+  `pyproject.toml`) plus re-materialising vendored extensions.
+- `lint`: `ruff check` and `ruff format --check` (`--fix` applies both) plus the static
+  API-policy check: `api-policy.yaml` passes the strict schema, and every `*.py` under
+  `app/tools/` (subpackages included, the top-level `__init__.py` excluded) declares one literal
+  `API_CALLS`, read with `ast` by the CLI and checked against the named API's rules and, when set,
+  its OpenAPI spec; `API_CALLS` changed anywhere else (`+=`, `.append()`, a conditional) is a
+  violation. A leftover `PRODUCT_CALLS` is an error; a
+  project still on `product-policy.yaml` stops with migration steps (exit 3).
+  `--policy-only` skips ruff. Each refused call is followed by the `graph-agents-cli api`
+  command that would allow it (a reviewed change; propose it, do not run it unasked). A
+  project with `app/response_schema.json` (structured final answers) has it checked first:
+  a schema the agent would not start with is exit 3, and an `agent.py` that does not pass
+  `response_format()` to `create_agent`, or has no `StructuredAnswer()` in its middleware, is
+  a warning.
+- `build`: `docker build -t <registry>/<name>:<tag> -f Dockerfile .` (default tag `latest`;
+  `--registry` overrides the manifest; `--push` pushes; `--dry-run` prints the commands). Exit `2`
+  on a docker failure, `3` without a Dockerfile or with a placeholder (`ghcr.io/CHANGE-ME`) or
+  invalid image reference (checked before docker runs, `--dry-run` included).
+
+
+## Outbound API policy
+
+```
+graph-agents-cli api add NAME --base-url-env ENV --auth none|bearer|forward|exchange [--token-env ENV]
+  [--forward-header H] [--audience AUD] [--scope "S ..."] [--resource URI] [--allow-actorless]
+  --access read-only|read-write|custom [--methods M,...] [--openapi PATH]
+  [--max-calls-per-run N] [--rate-per-minute N] [--connect-timeout-ms N] [--read-timeout-ms N] [--dry-run]
+graph-agents-cli api access NAME read-only|read-write|custom [--methods M,...] [--dry-run]
+graph-agents-cli api allow NAME (OPERATION_ID [--method M --path P] | --method M --path P) [--methods M,...] [--dry-run]
+graph-agents-cli api deny NAME (OPERATION_ID [--method M --path P] | --method M --path P) [--dry-run]
+graph-agents-cli api revoke NAME (OPERATION_ID | --method M --path P) [--from allowed|denied] [--dry-run]
+graph-agents-cli api limits NAME [--max-calls-per-run N|none] [--rate-per-minute N|none] [--dry-run]
+graph-agents-cli api approval NAME [--methods M,...|none] [--operations OP,...|none]
+  [--approvers requester,role:NAME,...] [--timeout-s N] [--add-rule | --rule N] [--remove] [--dry-run]
+graph-agents-cli api remove NAME [--dry-run]
+graph-agents-cli api show [NAME] [--json]
+graph-agents-cli api check
+```
+
+- `api-policy.yaml` belongs to the project and evolves with the agent; `create --api-policy`
+  only seeds it. There is no default access: `--access` is required on `add`; `read-only` writes
+  `[GET, HEAD]`, `read-write` writes `[GET, HEAD, POST, PUT, PATCH, DELETE]`, `custom` writes
+  `--methods` (case-insensitive, stored upper-case; `"*"` alone for every method). The file never
+  stores a preset name.
+- Every mutating command loads and validates the current file, applies one change, validates the
+  result, prints a unified diff of each file it touches (the policy, the manifest's `api_policy`
+  and `secrets.keys`, `.env.example`, the chart's `values.yaml` `env`), keeps comments and key
+  order, and writes atomically; `--dry-run` prints the diff only. It says whether access widens
+  (a reviewed change: CODEOWNERS covers `api-policy.yaml`) or narrows, and which declared calls
+  become allowed or refused. What it cannot edit safely is listed under "Left for you".
+- `add` creates the file when absent, copies an `--openapi` spec outside the project to
+  `openapi/<name>/`, adds a bearer `token_env` to `secrets.keys`, and documents the variables in
+  `.env.example` and the chart values (placeholder `http://CHANGE-ME`). `forward` is refused under
+  `langgraph-server`.
+- `allow` on an API without `allowed_operations` creates the list, which narrows access from
+  every operation within `allowed_methods` to the listed ones: the command says so. With
+  `openapi:` recorded, `allow` and `deny` by operation id check that the id exists and fill in its
+  method and path.
+- `revoke` removes the entries naming the operation; with `--method` only that method goes (an
+  entry pinning several keeps the others, and an entry without `methods` keeps every other
+  method, now listed); `--from` picks the list when both match; removing the last
+  `allowed_operations` entry is refused (it would allow every operation).
+- `remove` drops the API (and its token from `secrets.keys` when no other API uses it); the last
+  one removes `api-policy.yaml` and the manifest's `api_policy`, so every call is refused.
+- `approval` sets the calls that wait for a human before they are sent: `--methods` (every
+  call with them; `"*"` for all), `--operations` (operation ids; pinned to their method and
+  path from the API's `openapi:` spec), `--approvers` (`requester`, the principal who started
+  the run, and/or `role:<name>`, another principal holding it: four-eyes without `requester`,
+  which needs the `jwt` or `custom` auth policy), `--timeout-s` (30-86400, default 900),
+  `--remove`. Each option given replaces that part of the block; `--approvers` is required for
+  a new one. It says which declared calls become gated, and whether the change tightens the
+  gate (safe) or loosens it (fewer gated calls, a new approver, a longer timeout, removal: a
+  reviewed change, like widening access). Approval never widens access; a gate on a method the
+  API does not allow is noted. Propose gates for write tools; never loosen one unasked.
+- Other approvers for other calls of one API: `approval --add-rule` (with `--approvers` and
+  `--methods`/`--operations`) appends a rule, turning the block into a list of rules (comments
+  kept); it never loosens the gate. A call is gated by the first rule in file order that covers
+  it, with that rule's approvers; later rules that also cover it do not apply. A call that an
+  earlier rule covers only because it names no operation id (an entry by `operationId` alone),
+  and that a later rule with other approvers also covers, is refused at runtime and by `lint`:
+  pin path and methods in the earlier rule (with an `openapi:` spec, `--operations` does) and
+  name `operation_id` on every call; the command notes such a rule and does not call the change
+  safe. `--rule N`
+  changes, or with `--remove` removes, rule N (`approval[N]`, from 0, as `show` numbers them);
+  on a list of several rules a command without `--add-rule` or `--rule` is refused (exit 2),
+  and `--remove` alone removes every rule. It says which declared calls get other approvers,
+  and when a rule that now covers more takes calls from a later rule with other approvers (a
+  loosening). Replacing a single block's operations and approvers at once also prints the
+  `--add-rule` command that would keep the old gate.
+- `show` prints the effective policy per API (auth, methods and preset, allowed and denied
+  operations, limits, openapi, timeouts, approval) and every tool's declared calls with their
+  status, hint and approvers when gated, and the rule that gates each (`--json`: `approval`
+  and `approval_rules` per API, `approval` per call with `rule`, `rule_index` and
+  `also_covered_by`, a `gated` count); `check` is `lint --policy-only` (same exit codes; gated
+  calls are listed, not violations; calls several rules cover and rules that never apply are
+  noted).
+- Exit codes: `0` changed (or nothing to change), `1` `check` found a refused call, `2` usage
+  error, `3` an invalid result (nothing written), an invalid current file (`check` and `lint`
+  too), or not in a project.
+## Evaluate
+
+```
+graph-agents-cli eval run      [--dataset TEXT] [--url TEXT] [--concurrency N] [-H/--header]... [--cookie]...
+                               [--app-name TEXT] [--timeout SECONDS] [--config PATH] [-o/--output TEXT]
+                               [--judge-provider TEXT] [--judge-model TEXT] [--judge-timeout SECONDS]
+graph-agents-cli eval generate [--dataset TEXT] [-o/--output TEXT] [--url TEXT] [--concurrency N] [-H/--header]... [--cookie]...
+                               [--app-name TEXT] [--timeout SECONDS]
+graph-agents-cli eval grade    [--traces PATH] [--dataset TEXT] [--config PATH] [-o/--output TEXT]
+                               [--judge-provider TEXT] [--judge-model TEXT] [--judge-timeout SECONDS]
+graph-agents-cli eval compare  BASELINE CANDIDATE [--fail-on-regression] [--json]
+graph-agents-cli eval analyze  [--results TEXT] [--output TEXT] [--top-k N] [--judge] [--judge-provider TEXT] [--judge-model TEXT]
+graph-agents-cli eval submit   [--results TEXT] [--traces TEXT] [--dataset TEXT] [--dataset-name TEXT] [--experiment TEXT] [--endpoint TEXT]
+graph-agents-cli eval metric list [--json]
+```
+
+Datasets `tests/eval/datasets/*.json` (`--dataset` defaults to `basic-dataset.json`, else every
+file); config `tests/eval/eval_config.yaml`; traces `artifacts/traces/traces_<ts>.json`; results
+`artifacts/grade_results/results_<ts>.json`; analyses `artifacts/analysis_<ts>.json` (a `_2`,
+`_3`, ... suffix is added when two runs land in the same second). `eval run` chains generate and
+grade and returns the worse exit code; it honours extension overrides of both `eval.generate` and
+`eval.grade`. `eval grade` defaults to the newest traces file. `eval submit` uploads the dataset
+and a results file to LangSmith as an experiment (needs `LANGSMITH_API_KEY` and the `langsmith`
+extra; optional, never required). Credentials as for `run`: a bearer credential goes in
+`GRAPH_AGENTS_CLI_API_KEY` (locally a `shared-bearer` project's `API_KEY` from `.env`; a `jwt`
+project needs a token, e.g. from `auth dev-token`); a 401 prints the policy's hint. With `--url`,
+a warning names the target (credentials in the URL shown as `***@`, never stored in traces or
+results) and the write methods `api-policy.yaml` allows: every tool call runs for real there.
+`eval grade` warns when the agent or the judge ran on the fake model (a met gate is then a
+plumbing check only). A case that reaches a gated call decides it with its `approvals`
+instructions (an unmatched gate is a case error): a `requester` gate as the eval identity, a
+`role:` gate as `GRAPH_AGENTS_CLI_APPROVER_API_KEY` when set. Details: `/graph-agents-cli-eval`.
+
+## Deploy
+
+```
+graph-agents-cli infra check [--env TEXT] [--profile disconnected] [--json]
+graph-agents-cli secrets apply  --env TEXT [--env-file TEXT] [--context TEXT] [-y/--yes] [--rotate-api-key] [--dry-run]
+graph-agents-cli secrets status --env TEXT [--context TEXT] [--strict] [--dry-run]
+graph-agents-cli deploy --env TEXT [--image TEXT] [--env-file TEXT] [--context TEXT] [-y/--yes] [--status] [--restart]
+  [--force-direct] [--dry-run] [--tag TEXT] [--timeout DURATION] [--atomic/--no-atomic] [--rotate-api-key]
+```
+
+- `infra check` is read-only: reports the required tools and the kube context, Gateway API CRDs
+  and `GatewayClass`es, `IngressClass`es, cert-manager (only when `tls.certManager.enabled`),
+  Argo CD (only when `cd: argocd`), metrics-server (only when `hpa.enabled`), the namespace, the
+  image pull secret, the app Secret and its required keys, every `CHANGE-ME` placeholder
+  (registry, chart image and env, CODEOWNERS, Argo CD `repoURL`), and, when `gh` is logged in,
+  the GitHub `production`/`staging` environments, `main` branch protection and (helm-push) the
+  `DEPLOY_KUBECONFIG` environment secrets. `--profile disconnected` adds the
+  disconnected-profile checks (no hosted dependency). Never creates anything.
+- Env file and context rules (`deploy` and `secrets apply`): `--env-file`, else `.env.<env>`;
+  only `dev` falls back to `.env` (exit 3 otherwise). The kube context is `--context`, else
+  `environments.<env>.context`, else the kubeconfig's current one, which outside `dev` needs a
+  confirmation prompt or `--yes` (exit 1 without); an explicit context missing from the kubeconfig
+  is exit 3. The context and API server are always printed first.
+- `secrets apply` creates the namespace when missing and applies the Opaque Secret
+  `<release>-app` from the allow-listed keys (`secrets.keys` in the manifest) of the env file with
+  server-side apply (a 0600 temporary `--from-env-file` piped into `kubectl apply --server-side`);
+  allow-listed keys the file leaves out are kept from the live Secret. Under `shared-bearer` (the
+  only policy that reads `API_KEY`) the live `API_KEY` wins unless the file sets another and
+  `--rotate-api-key` is passed, and a missing one is generated and written to the env file (0600),
+  never printed; other policies get none. With `METRICS_TOKEN` allow-listed it is also applied
+  alone to `<release>-metrics` (the ServiceMonitor's token). It is not refused under CI; keeping application
+  secrets out of CI is the documented procedure. `--dry-run` prints the pipeline and a redacted
+  manifest. `secrets status` lists present, missing required, missing optional and unexpected
+  keys without values: exit `0` all required keys present, `1` the Secret or a required key missing
+  (`--strict`: any), `2` kubectl failed, `3` configuration error.
+- `deploy` behaviour depends on `create_params.cd` and the kube context (see the mode table in
+  `/graph-agents-cli-deploy`). `--tag` sets the tag of a local build (default: the short git sha,
+  plus `-dirty-<time>` for uncommitted changes, else a UTC timestamp); in argocd mode without
+  `--image` it is the tag written into the values file. Before building anything, direct mode
+  checks that the Secret it would produce holds every required key (exit 1) and that no other helm
+  operation holds the release (exit 2). helm runs with `--wait --timeout <--timeout, default 5m>`;
+  a failed rollout prints this release's pod diagnostics and, with `--atomic` (default), rolls back
+  this run's revision (or uninstalls a first install that never succeeded) and puts the app Secret
+  (and `<release>-metrics`) back to its values from before the run, keys this run removed
+  included, or deletes it when this run created it; a Secret someone else changed meanwhile is
+  left alone and the error says so. `--status` (argocd mode with the `argocd` CLI: `argocd app
+  get`) waits at most `--timeout` (default 60s) for the rollout, prints replicas, image, helm
+  revision and each pod's state, and exits 1 with diagnostics when it is not ready (or the
+  Deployment does not exist), 2 when kubectl fails. `--restart` runs `kubectl rollout restart`
+  (after secret rotation) and waits up to `--timeout` (default 5m) for the new pods: exit 2 with
+  diagnostics when they never become ready (the old pods keep serving);
+  `--force-direct` allows a workstation deploy to staging/prod in `helm-push` mode, which is
+  otherwise refused outside CI even with `--image`; `--dry-run` prints the docker, helm, kubectl
+  and gh commands and the rendered manifests without running them and never prompts (except
+  `helm dependency build`, which is executed when subcharts are missing because the render needs
+  them). `deploy --env staging|prod` refuses while the manifest has
+  `auth_policy_implemented: false`.
+
+## Extensions and info
+
+```
+graph-agents-cli extension add REFERENCE [--global] [--ref TEXT] [-i/--interactive] [-y/--yes]
+graph-agents-cli extension list
+graph-agents-cli extension update [NAME] [-i/--interactive] [-y/--yes]
+graph-agents-cli extension remove NAME [-i/--interactive] [-y/--yes]
+graph-agents-cli info [--json]
+```
+
+`extension add` takes a git reference (`org/repo`, a URL, `--ref`) or a local path (`/abs`,
+`./rel`, `../rel`, `~/dir`, or `local@<path>`); a local source is recorded relative to the project
+root (absolute with `--global`). A bad local path is exit 3, a git or network failure exit 2.
+`extension update` resolves the tracked ref first and reports "Already up to date" when nothing
+changed, without a trust prompt; new third-party code needs a prompt or `-y`. Without a terminal
+(CI, a pipe) the trust gate never prompts: `add` and `update` of untrusted code exit 1 with a hint
+to pass `-y`, and `update` keeps the old pin.
+
+`info` prints the CLI version, its build (`CLI build:` the id `--version` prints, `0.2.0` for
+a release and `0.2.0+g<commit>` for a build between releases, with the full commit; `--json`:
+`cli_build`), install path and installed skills (from `npx skills list`, which is not run with
+`GRAPH_AGENTS_CLI_NO_UPDATE_CHECK=1` or in CI: "not listed", `--json`:
+`installed_skills_skipped`) plus, inside a project: the version and build that scaffolded it
+(`Scaffolded with:`, from the manifest's `cli_build`), name, base template,
+agent directory, runtime, model provider and model, checkpointer, deployment target, registry,
+CD mode, auth policy, the API policy file (or none), `process`, the environments with their
+namespaces, and active extensions with their sources and conflicts.
+
+## Environment variables (CLI side)
+
+| Variable | Effect |
+|---|---|
+| `GRAPH_AGENTS_CLI_NO_UPDATE_CHECK=1` | disables the GitHub release check, the skills-version check and `info`'s skills listing (`npx skills list`; `info` says "not listed") (disconnected profile; CI markers do the same) |
+| `GRAPH_AGENTS_CLI_INSTALL_SPEC` | where `setup`, `update`, the `scaffold upgrade` baseline and generated projects' CI install the CLI from (a mirror, a wheel); `{version}` is replaced by the version needed, a release number, so it cannot name a build between releases (`scaffold upgrade --baseline-ref` does); control characters and whitespace are refused (exit 3), except the spaces of `name @ url` |
+| `GRAPH_AGENTS_CLI_RUN_PORT` | port of the local server `run` and `eval generate` start |
+| `GRAPH_AGENTS_CLI_DEBUG=1` | print the traceback behind a one-line network, file or parse error |
+| `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` (SOCKS too), `NO_PROXY` | used for `--url` agents and other remote requests; the local server (`run`, `approvals`, `eval`) is never reached through a proxy; a proxy the CLI cannot use is a one-line error (exit 3) |
+| `GRAPH_AGENTS_CLI_API_KEY` | bearer credential `run` and `eval` send (locally and with `--url`) when no `Authorization` header is given: the `API_KEY` (`shared-bearer`) or a JWT (`jwt`; locally from `auth dev-token`); keeps it out of argv |
+| `GRAPH_AGENTS_CLI_E2E=1` | opts the CLI repository's slow end-to-end test suite in (contributors only) |
+| `GRAPH_AGENTS_CLI_DISABLE_OVERRIDES=1` | bypass extension overrides (set automatically inside an override) |
+| `GRAPH_AGENTS_CLI_EXTENSION_DIR` | set for an override's process: the extension's directory |
+| `GRAPH_AGENTS_CLI_EXPERIMENTS` | JSON map of experiment toggles (empty mechanism today) |
+| `GRAPH_AGENTS_CLI_SKIP_VERSION_LOCK` | skip the CLI-version mismatch guard on a project |
+| `GH_HOST` (or `GITHUB_HOST`, `GITHUB_SERVER_URL`) | GitHub Enterprise Server host for argocd-mode pull requests and the disconnected-profile CI check |
+| `GITHUB_TOKEN`, `GH_TOKEN`, `GH_ENTERPRISE_TOKEN` | token for the REST fallback when `gh` is not installed (argocd mode) |

graph_agents_cli/skills/data/graph-agents-cli-workflow/references/extension.md

@@ -0,0 +1,156 @@
+# Extensions: override or extend graph-agents-cli
+
+An extension overrides or adds a built-in command. It is a directory containing a
+`graph-agents-cli-extension.yaml`, so any git repo can serve as a registry.
+
+Two things you can do: **author** an extension (start ad-hoc in the current repo, publish it
+later), or **adopt** an existing one. Extensions change commands; they cannot add a deployment
+target or a framework.
+
+---
+
+## Author an ad-hoc extension (no separate repo)
+
+Drop a single file, `graph-agents-cli-extension.yaml`, at the project root (next to
+`graph-agents-cli-manifest.yaml`). It is auto-loaded at project scope, so no `extension add` is
+needed. Commit it and teammates and CI get the same overrides.
+
+Only one, at that exact path, and always project scope. For a second one, or to install a local
+extension globally, move it into its own directory and
+`graph-agents-cli extension add local@./path --global`; `#name` picks one out of a directory
+holding several.
+
+**Publish it for other repos:** move the same file (and its scripts) into its own git repo and tag
+it; others then `graph-agents-cli extension add <org>/<repo>#<name> --ref v1.0.0`. The file does
+not change; ad-hoc and shared are the same format.
+
+### Schema by example (`graph-agents-cli-extension/v1alpha1`)
+
+Everything below is optional except `run` on a command (a non-empty list). Unknown keys are
+rejected, so a typo fails loudly.
+
+Machine-readable equivalent: `schemas/graph-agents-cli-extension-v1alpha1.schema.json` in the
+graph-agents-cli repo, generated from the models the loader uses. Point a `yaml-language-server`
+modeline at it for editor validation.
+
+```yaml
+schema: graph-agents-cli-extension/v1alpha1
+name: my-extension
+description: What this extension does.
+requires:
+  agents_cli: ">=0.2,<0.3"  # derive from `graph-agents-cli --version`, see below
+  on_incompatible: warn     # warn (install + warn) | error (refuse at add/update, block its commands if the CLI drifts out)
+
+commands:
+  override:               # replace a built-in; user argv passes through verbatim
+    deploy:
+      run: ["uv", "run", "scripts/custom_deploy.py"]
+      description: SBOM upload and a change-ticket check, then the built-in deploy.
+    eval.generate:        # dotted name = a subcommand (group.sub)
+      run: ["uv", "run", "scripts/eval_generate.py"]
+      description: Drive a different chat transport for traces.
+  add:                    # a brand-new command
+    compliance-report:
+      run: ["python", "scripts/compliance_report.py"]
+      description: Generate the quarterly compliance report.
+```
+
+### Rules that matter
+
+- **`run:` is a command vector** executed with **no shell**; user argv is appended verbatim. Paths
+  relative to the extension dir resolve to absolute, and `$GRAPH_AGENTS_CLI_EXTENSION_DIR` locates
+  sibling scripts and templates.
+- **You cannot override a command group** (`eval`, `scaffold`, `secrets`, `infra`); override a
+  specific subcommand (`eval.generate`, `scaffold.create`, `secrets.apply`, `infra.check`). Peers
+  keep their built-in behaviour. `install` and `extension` can never be overridden.
+- **`eval run` honours both stage overrides.** Overriding `eval.generate` or `eval.grade` changes
+  the composite `eval run` exactly as it changes the standalone command.
+- **`create` and `scaffold create` are one command:** overriding `scaffold.create` takes over the
+  `create` alias too.
+- **Re-invoke the built-in safely.** An override runs with `GRAPH_AGENTS_CLI_DISABLE_OVERRIDES=1`,
+  so calling `graph-agents-cli deploy` inside your wrapper hits the built-in (no recursion).
+- **Chaining is done in a wrapper script**, since `run:` is a single vector:
+  ```bash
+  #!/usr/bin/env bash
+  set -e
+  "$GRAPH_AGENTS_CLI_EXTENSION_DIR/scripts/change_ticket_check.sh"   # non-zero here aborts
+  graph-agents-cli deploy "$@"                                         # hits the built-in
+  ```
+- **Start `run:` with a program, not a script.** `["python", "scripts/x.py"]` or
+  `["uv", "run", "python", "scripts/x.py"]` works everywhere; a bare `["scripts/x.py"]` relies on a
+  shebang and never runs on Windows (the CLI warns).
+- **Conflicts** (same scope, shown in `extension list` and `info`): two extensions claiming one
+  command is first-wins. Cross-scope is fine; project wins over user (`--global`).
+- **Declare a compatibility range** with `requires`, always. Run `graph-agents-cli --version` and
+  set the lower bound to that `major.minor`. The upper bound is the next minor while the CLI is
+  0.x (a 0.x minor release may break compatibility: `>=0.2,<0.3`), the next major from 1.0 on. Let the user pick
+  `on_incompatible`; default `warn`.
+  - `warn`: installs, runs, warns when out of range.
+  - `error`: `extension add`/`update` refuse an out-of-range install, and if a later CLI upgrade
+    moves you out of range the extension's commands fail with the range and the fix rather than
+    silently running the built-in. The recovery commands (`install`, `extension *`) keep working.
+  - `schema` tracks the manifest format, not the CLI version.
+
+---
+
+## Adopt an existing extension
+
+```bash
+graph-agents-cli extension add <ref> [--global] [--ref <branch|tag|sha>] [--yes]
+graph-agents-cli extension list                 # what's active, its scope, and its commands
+graph-agents-cli extension update [<name>]      # advance the pin (re-resolve the tracked ref)
+graph-agents-cli extension remove <name>        # drop it and delete its vendored copy
+graph-agents-cli info                           # active extensions + sources + conflicts
+```
+
+### Reference forms
+
+| Form | Meaning |
+|------|---------|
+| `acme/gacli-extensions` | any `org/repo` on github.com |
+| `acme/gacli-extensions#soc2-deploy` | select one extension from a multi-extension repo |
+| `https://git.example.com/acme/gacli-extensions` | any git host: `https://`, `http://`, or `ssh://` |
+| `git@git.example.com:acme/gacli-extensions` | the same host, scp form |
+| `../my-extension`, `./ext`, `/abs/path`, `~/ext`, `C:\ext`, or `local@<path>` | a local directory (for development); recorded relative to the project root (absolute with `--global`) and resolved from there by `install` and `update`. A bad local path is exit 3; a git or network failure resolving a repository is exit 2 |
+| `<name>` | first-party shorthand (resolves to the graph-agents-cli repository) |
+| `--ref <branch\|tag\|sha>` | pin a branch, tag, or commit SHA |
+
+A URL is cloned with your ambient git configuration; graph-agents-cli neither asks for nor stores
+credentials. On a disconnected network, extensions come from an on-network git host or
+`local@` paths.
+
+### Scopes
+
+- **Project scope (default):** recorded in `graph-agents-cli-extensions.yaml`, working copy
+  vendored under `extensions/`. Commit both so it works offline (`install` re-fetches if missing).
+- **User scope (`--global`):** `~/.config/graph-agents-cli/`. Applies to every project on the
+  machine. Prefer project scope unless you truly want it machine-wide.
+- When both scopes define the same command, **project wins**; `info` shows the source.
+
+### Trust
+
+- First-party extensions added via the shorthand form are trusted automatically.
+- Every other reference prompts before install (its commands run arbitrary code when invoked).
+  `--yes` skips the prompt; use it only for automation.
+
+### Pinning and updates
+
+- `extension add` resolves the ref to an exact commit SHA and records `source` / `ref` / `sha`
+  under `extensions:` in `graph-agents-cli-extensions.yaml`, vendoring a working copy under
+  `extensions/`.
+- `graph-agents-cli install` re-materializes any missing or stale vendored copy from the pinned
+  SHA. It never advances a pin.
+- `extension update [name]` advances the pin to the latest commit of the same tracked ref. A pinned
+  tag or SHA re-resolves to itself; to move to a different tag, re-run `extension add <ref>
+  --ref <new-tag>`.
+- `extension remove <name>` removes from one scope per call (project before user).
+
+```bash
+graph-agents-cli extension add acme/gacli-extensions#soc2 --ref v1.2.0   # pin a tag (recommended)
+graph-agents-cli extension add acme/gacli-extensions#soc2 --ref main     # follow a branch
+graph-agents-cli extension update soc2                                   # advance within the tracked ref
+graph-agents-cli extension add acme/gacli-extensions#soc2 --ref v1.3.0   # move to another tag: re-add
+```
+
+A failed re-`add` rolls back to nothing rather than to the previous pin, so re-add the old ref to
+restore it.