Skip to content
Kindgi

CLI

View as Markdown

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

Section titled “Commands”
  • kindgi auth: Manage local auth: the API's URL and token, and the runtime image's registry.
  • kindgi init: 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: 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: 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: Open the runtime's console in your browser.
  • kindgi build: 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. --hosted (or the env block's build: 'hosted') builds on Kindgi hosted's build service, at the API's address under /cloud, with your API key; the image goes to your workspace's own repository.
  • kindgi deploy: Deploy a signed pack image to Kindgi. Reads deploy-envelope.json (or runs kindgi build inline) + POSTs to /v1/deployments. --hosted (or the env block's build: 'hosted') deploys to Kindgi hosted: an inline build runs on the hosted build service (as kindgi build --hosted), and after the deploy it waits, up to 5 minutes, for the deployment's pack service to be ready. A deploy into the Default project with a pack tool whose id is an MCP endpoint's tool's is refused (tool-kind-mismatch), and nothing is deployed.
  • kindgi deployments: See what's deployed: list, get. get shows a deployment's pack service now, and what to do when it runs on the values it was last given.
  • kindgi promote: Move a build to the next environment of its environment order, staging to prod, say: the same signed image, with the edits made since to its agents and flows. Prints what moves, then each value the build needs there that isn't set, with the command that sets it; exits 1 while one isn't. --check stops before moving anything. In a pack, --from and --to are its environment names; outside one, project ids or slugs.
  • kindgi test: Run the pack's tests via vitest. Ergonomic wrapper over vitest run.
  • kindgi env: The values in one environment — a value set: the pack's local env files, and with --scope the runtime's (a tool's ctx.env, per project, org or tenant). For the order projects go live through, see kindgi environments.
  • kindgi environments: The order of your environments.
  • kindgi secrets: Manage per-environment secrets via the /v1/secrets/* wire.
  • kindgi sso: Sign-in with your organization's identity provider (single sign-on).
  • kindgi sign-in: The workspace's sign-in settings: whether signing in takes a second factor.
  • kindgi sites: Sites that sign their own people in to a project (the Kindgi WordPress plugin): register, code, list, get, update, pause, resume, revoke-key, unregister. Tenant admins only.
  • kindgi key: Manage Ed25519 signing keys: the local pairs under ~/.kindgi/keys/, and the runtime's trust list.
  • kindgi license: 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: Manage MCP server entries in .mcp.json (add / list / remove / presets).
  • kindgi mcp-launch: Spawn an MCP server subprocess with secrets injected from Kindgi. Invoked by MCP clients via .mcp.json — not for direct use.
  • kindgi projects: Find projects, for the commands that take --project=<id> (list / get-default / get), make and rename them (create / rename), and put one in production (production).
  • kindgi runs: Manage kernel runs — the single execution primitive.
  • kindgi agents: Manage agent registrations and which version runs where.
  • kindgi conversations: Conversations: multi-turn threads with one agent version (list / get / open / close / messages).
  • kindgi tools: Manage tool registrations.
  • kindgi guardrails: Manage guardrail registrations.
  • kindgi memory: Memory: the facts agents remember, by type and scope, and erasing a person's words.
  • kindgi proposals: 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: Provenance records: each run's graph of what ran (list / get / export, signed).
  • kindgi exports: Exports: create an export of the whole workspace as files, or verify a signed one.
  • kindgi artifacts: Files kept in the runtime, each in a project: list, get, upload, download, delete.
  • kindgi flows: Manage flow registrations: publish, list, versions, unregister, reinstate.
  • kindgi schedules: Run agents and flows on a schedule: create, list, get, update, pause, resume, run-now, fires, take-ownership, unregister.
  • kindgi webhooks: Start flow runs from signed webhooks (WooCommerce, Drupal, GitHub, Shopify, Standard Webhooks): register, list, get, update, pause, resume, fires, take-ownership, unregister.
  • kindgi approvals: Review HITL approvals, and export their signed audit bundles.
  • kindgi reviewers: Manage HITL reviewers.
  • kindgi judgments: Judge items of a run's output, yes or no (add / list / show / remove).
  • kindgi judge-classes: Manage judge classes, the weighted kinds of judge (list / add / set / remove).
  • kindgi eval-runs: Eval runs: run an eval suite, or compare an agent version on a test set (start / show / list / cancel / rescore).
  • kindgi eval-suites: Eval suites and test sets built from judgments (list / show / from-judgments / cases).
  • kindgi blocks: Data blocks: versioned prompts and settings agent versions pin (list / show / versions / publish / unregister / reinstate).
  • kindgi gate-policies: 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: API keys for you, a person or a service account: create (its secret shown once), list, get, revoke.
  • kindgi service-accounts: Service accounts: non-human principals with their own grants, acting through API keys (create / list / get / grant / ungrant / unregister).
  • kindgi people: The tenant's people: add one, send their invitation again, list, get, their grants, tenant admin given or taken (grant / ungrant), their second factor (read, or reset for a lost phone), and remove one.
  • kindgi capabilities: The features an agent can require, what each means, and your models that have them.
  • kindgi providers: Manage model providers.
  • kindgi adapters: Manage adapter lifecycle (prepare / warmup). Read-side lives on kindgi providers.
  • kindgi skills: Manage the pack's skills, in .claude/skills/ and .agents/skills/.
  • kindgi feedback: Report framework friction Claude Code diagnosed — bugs, wire schema gaps, misleading errors, UX cliffs.
  • kindgi egress: Print the IP addresses this deployment's calls to other sites come from, for a site that admits only known addresses: the server's own calls (such as to MCP servers and model providers, and webhook deliveries) and calls made by your deployed code. Every tenant on the deployment calls from the same addresses, so keep your site's own credentials too. --json prints both lists.
  • kindgi health: Ping the API server (GET /health).
  • kindgi doctor: 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: Print CLI + SDK versions (and API version if reachable).

Global flags

Section titled “Global flags”

Every command takes these:

Option Default Description
--help, -h off Show help.
--hosted off, unless the env the command acts in has build: 'hosted' in kindgi.config.ts (--env, else staging for kindgi build and kindgi deploy) Go to the CLI's own address (--url, KINDGI_API_URL or the one kindgi auth login stored), never a kindgi dev runtime's .kindgirc.json; kindgi build and kindgi deploy then use the hosted build service. An env block's build: 'hosted' does the same for the env a command acts in. kindgi dev refuses it: a dev runtime is never hosted.
--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 a stored key: ./.kindgirc.json's, then ~/.kindgi/config.json's, and when those are for different addresses, the one stored with the API URL. A stored key goes only to the address stored with it: a command that would send it elsewhere is refused before it sends anything. With --hosted, a kindgi dev runtime's ./.kindgirc.json isn't read. None of them set: a command that calls the API fails The API token. Overrides KINDGI_API_TOKEN and the config files, and goes to the address the command does.
--url <value> KINDGI_API_URL, then ./.kindgirc.json, then ~/.kindgi/config.json; with --hosted, a kindgi dev runtime's ./.kindgirc.json isn't read. None of them set: a command that calls the API fails The Kindgi API's URL. Overrides KINDGI_API_URL and the config files. A stored key goes only to the address stored with it.
--verbose, -v off Show more detail when a command fails.
--version off Print the CLI's version.

In a folder where kindgi dev ran, its .kindgirc.json points every command at the dev runtime, ahead of kindgi auth login; --hosted goes to the CLI's own address in its place. A command that goes to the dev runtime while another address is in reach says so first, on stderr:

kindgi auth whoami goes to the kindgi dev runtime at http://127.0.0.1:4000 (…/.kindgirc.json says so). For https://platform.kindgi.com, pass --hosted.
Excerpt

When the key was given with --token or KINDGI_API_TOKEN and nothing else is signed in, the line ends To send it to the address your key is for, pass --url <that address> or export KINDGI_API_URL. in place of the --hosted sentence. There's no line when --url or KINDGI_API_URL named the address, or when the dev runtime is the only one in reach.

Exit codes

Section titled “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).