# CLI

> Every kindgi command, its flags and its subcommands.

The `kindgi` command-line interface (`@kindgi/cli`). Generated from the CLI's own command definitions, so it matches this version. Each command has its synopsis, what it does, its options with their defaults, examples, and the guides that use it.

## Commands

- [`kindgi auth`](https://docs.kindgi.com/v0.1.8/reference/cli/auth.md): Manage local auth: the API's URL and token, and the runtime image's registry.
- [`kindgi init`](https://docs.kindgi.com/v0.1.8/reference/cli/init.md): Scaffold a new Kindgi pack repo, or add Kindgi to an existing app: a Node.js, Python, Maven or sbt project, auto-detected from its `package.json`, `pyproject.toml`, `pom.xml` or `build.sbt` when no pack-name is given.
- [`kindgi upgrade`](https://docs.kindgi.com/v0.1.8/reference/cli/upgrade.md): Move a Java or Scala pack's pin of the Kindgi CLI ("cli" in kindgi.config.json, which ./kindgiw runs) and its build's kindgi-pack version (pom.xml's kindgi.version, build.sbt's kindgi-pack-scala) to this CLI's version, or --to. A TypeScript or Python pack upgrades through its package manager.
- [`kindgi dev`](https://docs.kindgi.com/v0.1.8/reference/cli/dev.md): Run the Kindgi runtime as a container + hot-reload the pack under cwd. One per pack: a second exits 3 ("already running"), saying where the first is.
- [`kindgi console`](https://docs.kindgi.com/v0.1.8/reference/cli/console.md): Open the runtime's console in your browser.
- [`kindgi build`](https://docs.kindgi.com/v0.1.8/reference/cli/build.md): Bundle + build + sign a pack image. Emits deploy-envelope.json for `kindgi deploy`. `--local` builds the image with this machine's Docker instead: no build service, no signing; with `--push`, it pushes the image, signs it, and writes the envelope.
- [`kindgi deploy`](https://docs.kindgi.com/v0.1.8/reference/cli/deploy.md): Deploy a signed pack image to Kindgi. Reads deploy-envelope.json (or runs `kindgi build` inline) + POSTs to /v1/deployments.
- [`kindgi test`](https://docs.kindgi.com/v0.1.8/reference/cli/test.md): Run the pack's tests via vitest. Ergonomic wrapper over `vitest run`.
- [`kindgi env`](https://docs.kindgi.com/v0.1.8/reference/cli/env.md): Manage env values: the pack's local env files, and with --scope the runtime's (a tool's `ctx.env`, per project, org or tenant).
- [`kindgi secrets`](https://docs.kindgi.com/v0.1.8/reference/cli/secrets.md): Manage per-environment secrets via the /v1/secrets/\* wire.
- [`kindgi sso`](https://docs.kindgi.com/v0.1.8/reference/cli/sso.md): Sign-in with your organization's identity provider (single sign-on).
- [`kindgi key`](https://docs.kindgi.com/v0.1.8/reference/cli/key.md): Manage Ed25519 signing keys: the local pairs under \~/.kindgi/keys/, and the runtime's trust list.
- [`kindgi license`](https://docs.kindgi.com/v0.1.8/reference/cli/license.md): Your Kindgi license key: enroll a deployment once, then renew its key when you run renew (by hand or on your own schedule).
- [`kindgi mcp`](https://docs.kindgi.com/v0.1.8/reference/cli/mcp.md): Manage MCP server entries in .mcp.json (add / list / remove / presets).
- [`kindgi mcp-launch`](https://docs.kindgi.com/v0.1.8/reference/cli/mcp-launch.md): Spawn an MCP server subprocess with secrets injected from Kindgi. Invoked by MCP clients via .mcp.json — not for direct use.
- [`kindgi projects`](https://docs.kindgi.com/v0.1.8/reference/cli/projects.md): Find projects, for the commands that take `--project=<id>` (list / get-default / get), and put one in production (production).
- [`kindgi runs`](https://docs.kindgi.com/v0.1.8/reference/cli/runs.md): Manage kernel runs — the single execution primitive.
- [`kindgi agents`](https://docs.kindgi.com/v0.1.8/reference/cli/agents.md): Manage agent registrations and which version runs where.
- [`kindgi conversations`](https://docs.kindgi.com/v0.1.8/reference/cli/conversations.md): Conversations: multi-turn threads with one agent version (list / get / open / close / messages).
- [`kindgi tools`](https://docs.kindgi.com/v0.1.8/reference/cli/tools.md): Manage tool registrations.
- [`kindgi guardrails`](https://docs.kindgi.com/v0.1.8/reference/cli/guardrails.md): Manage guardrail registrations.
- [`kindgi memory`](https://docs.kindgi.com/v0.1.8/reference/cli/memory.md): Memory: the facts agents remember, by type and scope, and erasing a person's words.
- [`kindgi proposals`](https://docs.kindgi.com/v0.1.8/reference/cli/proposals.md): Improvement proposals: new content for a data block an agent pins, for one scope; evaluated on a test set, then promoted through the scope's gate (list / get / draft / evaluate / request / rollback / withdraw / improve / passes).
- [`kindgi provenance`](https://docs.kindgi.com/v0.1.8/reference/cli/provenance.md): Provenance records: each run's graph of what ran (list / get / export, signed).
- [`kindgi exports`](https://docs.kindgi.com/v0.1.8/reference/cli/exports.md): Signed exports: check one (an audit bundle, provenance, compliance evidence).
- [`kindgi artifacts`](https://docs.kindgi.com/v0.1.8/reference/cli/artifacts.md): Files kept in the runtime, each in a project: list, get, upload, download, delete.
- [`kindgi flows`](https://docs.kindgi.com/v0.1.8/reference/cli/flows.md): Manage flow registrations: publish, list, versions, unregister, reinstate.
- [`kindgi schedules`](https://docs.kindgi.com/v0.1.8/reference/cli/schedules.md): Run agents and flows on a schedule: create, list, get, update, pause, resume, run-now, fires, take-ownership, unregister.
- [`kindgi webhooks`](https://docs.kindgi.com/v0.1.8/reference/cli/webhooks.md): Start flow runs from signed webhooks (WooCommerce, Drupal, GitHub, Shopify, Standard Webhooks): register, list, get, update, pause, resume, fires, take-ownership, unregister.
- [`kindgi approvals`](https://docs.kindgi.com/v0.1.8/reference/cli/approvals.md): Review HITL approvals, and export their signed audit bundles.
- [`kindgi reviewers`](https://docs.kindgi.com/v0.1.8/reference/cli/reviewers.md): Manage HITL reviewers.
- [`kindgi judgments`](https://docs.kindgi.com/v0.1.8/reference/cli/judgments.md): Judge items of a run's output, yes or no (add / list / show / remove).
- [`kindgi judge-classes`](https://docs.kindgi.com/v0.1.8/reference/cli/judge-classes.md): Manage judge classes, the weighted kinds of judge (list / add / set / remove).
- [`kindgi eval-runs`](https://docs.kindgi.com/v0.1.8/reference/cli/eval-runs.md): Eval runs: run an eval suite, or compare an agent version on a test set (start / show / list / cancel / rescore).
- [`kindgi eval-suites`](https://docs.kindgi.com/v0.1.8/reference/cli/eval-suites.md): Eval suites and test sets built from judgments (list / show / from-judgments / cases).
- [`kindgi blocks`](https://docs.kindgi.com/v0.1.8/reference/cli/blocks.md): Data blocks: versioned prompts and settings agent versions pin (list / show / versions / publish / unregister / reinstate).
- [`kindgi gate-policies`](https://docs.kindgi.com/v0.1.8/reference/cli/gate-policies.md): Gate policies: what a promotion of an agent must show before a version goes live for a scope (list / show / versions / publish / unregister / reinstate).
- [`kindgi tokens`](https://docs.kindgi.com/v0.1.8/reference/cli/tokens.md): API keys for you, a person or a service account: create (its secret shown once), list, get, revoke.
- [`kindgi service-accounts`](https://docs.kindgi.com/v0.1.8/reference/cli/service-accounts.md): Service accounts: non-human principals with their own grants, acting through API keys (create / list / get / grant / ungrant / unregister).
- [`kindgi people`](https://docs.kindgi.com/v0.1.8/reference/cli/people.md): The tenant's people: add one, list, get, their grants, tenant admin given or taken (grant / ungrant), and remove one.
- [`kindgi capabilities`](https://docs.kindgi.com/v0.1.8/reference/cli/capabilities.md): The features an agent can require, what each means, and your models that have them.
- [`kindgi providers`](https://docs.kindgi.com/v0.1.8/reference/cli/providers.md): Manage model providers.
- [`kindgi adapters`](https://docs.kindgi.com/v0.1.8/reference/cli/adapters.md): Manage adapter lifecycle (prepare / warmup). Read-side lives on `kindgi providers`.
- [`kindgi skills`](https://docs.kindgi.com/v0.1.8/reference/cli/skills.md): Manage the pack's skills, in `.claude/skills/` and `.agents/skills/`.
- [`kindgi feedback`](https://docs.kindgi.com/v0.1.8/reference/cli/feedback.md): Report framework friction Claude Code diagnosed — bugs, wire schema gaps, misleading errors, UX cliffs.
- [`kindgi health`](https://docs.kindgi.com/v0.1.8/reference/cli/health.md): Ping the API server (GET /health).
- [`kindgi doctor`](https://docs.kindgi.com/v0.1.8/reference/cli/doctor.md): Check this machine and folder are ready to run Kindgi: Node, Docker, access to the runtime image, the project, its model key, the runtime and a provider. Each check says what it found and, when it fails, the exact fix. Exits 1 when any check fails; --json for a coding agent.
- [`kindgi version`](https://docs.kindgi.com/v0.1.8/reference/cli/version.md): Print CLI + SDK versions (and API version if reachable).

## Global flags

Every command takes these:

| Option            | Default                                                                                                                         | Description                                                            |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `--help`, `-h`    | off                                                                                                                             | Show help.                                                             |
| `--json`          | on when no format flag is given: pretty JSON (commands for people, such as `kindgi dev`, print JSON only when asked)            | Output pretty-printed JSON (the default).                              |
| `--quiet`         | off                                                                                                                             | Print nothing: the exit code alone reports the result.                 |
| `--raw`           | off                                                                                                                             | Output compact, one-line JSON.                                         |
| `--table`         | off; a command with no table prints JSON                                                                                        | Output a table, for commands that list.                                |
| `--token <value>` | `KINDGI_API_TOKEN`, then `./.kindgirc.json`, then `~/.kindgi/config.json`; none of them set: a command that calls the API fails | The API token. Overrides `KINDGI_API_TOKEN` and the config files.      |
| `--url <value>`   | `KINDGI_API_URL`, then `./.kindgirc.json`, then `~/.kindgi/config.json`; none of them set: a command that calls the API fails   | The Kindgi API's URL. Overrides `KINDGI_API_URL` and the config files. |
| `--verbose`, `-v` | off                                                                                                                             | Show more detail when a command fails.                                 |
| `--version`       | off                                                                                                                             | Print the CLI's version.                                               |

## Exit codes

- `0`: the command succeeded.
- `1`: the API refused the call, or what the command ran failed: a failed run (`kindgi runs start`), a failing check (`kindgi doctor`).
- `2`: a usage error: an unknown command, subcommand or flag, a missing argument or flag, or a value a flag can't take. The error says which.
- `130`: you stopped it with Ctrl+C while it waited (`kindgi runs start`, a starting `kindgi dev`).