CLI reference

kya-os --help and kya-os <command> --help list everything the installed version supports.

setup

A live sign-in on the same Checkpoint is reused, so a second run doesn't open the browser. If the project you name isn't part of that sign-in, setup signs in again with it preselected so you can grant it. A name no project has yet is offered on the consent page instead, to create and grant in one step. With nothing named, the offer is this repository's name, and a granted project by that name is linked without asking.

detect install

Without a sign-in, detect install uses the project you name as given, since the pixel and beacon need only the project ID; it says so. What it writes:

With --surface sdk and no CHECKPOINT_API_KEY in the app's .env.local or .env, a signed-in detect install offers to mint the app's key. It asks first; --yes skips the prompt, and a dry run only says it would. It adds the env file to .gitignore, then mints a key named kya-os CLI · sdk · <host> - <repository>, returned once, with read permission, and writes it to .env.local (Next.js) or .env (Express). The plan's API key limit applies, as it does to dashboard keys. ASP.NET and Java keep their key in their own secret store, so there the CLI prints where it goes.

Existing files only ever gain one block, marked Checkpoint Detect. A file that already has it is left alone, so a second run changes nothing. An existing middleware.ts or proxy.ts is never overwritten; the lines to compose into it are printed instead. A failed package install stops the run before anything that imports the package is written.

login, logout, whoami, projects

The sign-in is a management session for a person. It lists your projects and links repositories to them, and Checkpoint's runtime API refuses it, so it can never stand in for an app's API key. Access tokens last 15 minutes and renew silently; the session ends after 30 days without use, and after 90 days regardless. On Linux the session needs a Secret Service keyring (GNOME Keyring or KWallet); see Troubleshooting for machines without one.

mcp create

kya-os mcp create <name> runs @kya-os/create-mcpi-app for Cloudflare Workers, the runtime that pulls per-tool protection from Checkpoint. It's pre-filled with the linked project and your repository's package manager, and runs with no prompts. When you're signed in, it then mints the server's key (read and write, for proofs and tool discovery) into the new server's gitignored .dev.vars. The key never goes on the scaffolder's command line.

Without a terminal, pass --yes or --no-key: the key is decided before anything is scaffolded, so a server is never left half set up. The scaffolder needs Node.js 22.12 or newer.

Then run it locally with npm run dev (the CLI prints your package manager's form). Before the first npm run deploy, sign wrangler in once with npx wrangler login, then upload the server's secrets, the key among them, with npx wrangler secret bulk .dev.vars.

govern

kya-os govern install --agent claude adds a Claude Code PostToolUse hook to this repository. After every tool call, Claude Code runs kya-os hook post in the background, and the call appears in the project's Activity feed as an observed verdict. Nothing is blocked.

• Sent: the tool's name, the session, and the call's ID. The tool's input and output are never sent, since they can hold file contents and secrets.
• Never in the way: the hook runs asynchronously, gives up after three seconds, and exits 0 on any failure.
• Key: the project's read-only runtime key, read from the repository's gitignored .env.local or .env. If the key is only in your shell's CHECKPOINT_API_KEY, install saves it to .env.local, because the hook runs inside Claude Code, which may not see your shell. When there's no key and you're signed in, install mints one.
• Origin: the hook reports only to the Checkpoint it was installed for (hook post --origin …), so a later edit to the committed link can't redirect the key.

Your other hooks and settings are kept, and a second install changes nothing, unless the hook points at another Checkpoint or another kya-os binary: then it's replaced, and the state is updated. kya-os govern uninstall --scope <scope> removes only the kya-os hook.

How --project resolves

Every command that needs a project takes the first of:

1. the --project flag;
2. the KYA_OS_PROJECT environment variable;
3. the nearest .kya-os/project.json, from the current directory up to the repository root;
4. the only project the sign-in covers.

A value matches a project by ID, or by exact name, ignoring case. A name shared by several projects is refused with the list of matches, and with several projects and nothing selected, setup asks, offering a new project too (or, without a terminal, lists them and stops). Only a project ID preselects a project on the consent page; any other value is matched there by name, or offered as the name of a new project.

Environment variables

The installer's own variables are on Installation.

Files

{
  "schema": "kya-os.project-link.v1",
  "origin": "https://kya.vouched.id",
  "organizationId": "5b1f3a9e-…",
  "projectId": "9c2d7e41-…",
  "name": "acme-web"
}

A link that names another Checkpoint origin (staging, a local server) is ignored, with a message, rather than resolved against the wrong one.

JSON output

With --json, a command prints one JSON document on stdout, and progress, prompts, and package-manager output go to stderr. setup reports the link and what Detect did:

{
  "origin": "https://kya.vouched.id",
  "signedInNow": true,
  "organizationId": "5b1f3a9e-…",
  "project": { "id": "9c2d7e41-…", "name": "acme-web" },
  "link": { "path": "/home/me/acme-web/.kya-os/project.json", "state": "written" },
  "detect": {
    "status": "applied",
    "report": {
      "surface": "pixel",
      "outcomes": [{ "outcome": "applied", "description": "edit app/layout.tsx (before </body>)" }],
      "notes": ["…"]
    }
  }
}

Exit codes