@kya-os/cli

kya-os is the Checkpoint CLI. It signs you in to Checkpoint, links a repository to a project, adds Checkpoint Detect to your app, scaffolds KYA-OS MCP servers, and reports what a coding agent does in your repository.

Install

You need Node.js 20.19 or later on macOS (arm64 or x64) or Linux (x64 or arm64, glibc). Windows is not supported.

npm install -g @kya-os/cli
kya-os --version

To run it without installing, name the binary with -p:

npx -p @kya-os/cli kya-os --version

The package ships more than one binary and none is named cli, so a bare npx @kya-os/cli fails with could not determine executable to run.

Without Node.js, the installer puts the same binary on your PATH:

curl -fsSL https://kya.vouched.id/install | sh

First run

Connect this repository

kya-os setup

setup signs you in to Checkpoint, links this repository to a project and adds Checkpoint Detect to your app.

• Sign-in opens your browser; add --device to approve from any browser with a code.
• The link is written to .kya-os/project.json, which holds no secret and is safe to commit.
• Detect is added as a pixel by default (no key, no dependency); --surface beacon or --surface sdk choose another form.
• Browser posture is part of every Checkpoint project. setup and detect install confirm the project's posture key at the keys endpoint and print the verifier config for your stack; --origins replaces the list of extra page origins allowed to carry posture (https only; https://*.example.com covers subdomains). The command exits non-zero, with each gap listed, when posture is not fully set up (not signed in, posture unavailable, no usable page origin, key not confirmed, or no verifier config for --surface sdk); --dry-run never fails for these. A real --surface beacon install needs beacon 1.4.3 or later and leaves your pages and dependencies unchanged until it is published.
• --dry-run prints the plan and changes nothing, and signs nothing in.
• Without a terminal, nothing is applied unless you pass --yes (browser posture is still read and confirmed); --json prints one JSON document for scripts.

Then check where you are:

kya-os whoami
kya-os projects list

Commands

Run kya-os <command> --help for every option.

| Command | What it does | | -------------------------------- | --------------------------------------------------------------------------------------------------- | | setup | Sign in, link this repository to a Checkpoint project and install Detect | | login / logout | Sign in to Checkpoint (browser, or --device), or revoke this machine's sign-in | | whoami | Who is signed in, to which organization, and which projects it covers | | projects list / projects use | List the projects this sign-in covers, or link this repository to one | | detect install | Add Checkpoint Detect (pixel, beacon or server SDK) to the app in this directory | | mcp create <name> | Scaffold a KYA-OS MCP server for Cloudflare Workers, tied to this repository's Checkpoint project | | govern install | Report a coding agent's tool calls in this repository to the project's activity feed (observe only) | | checkpoint key | Set, show or clear this app's runtime API key in .env.local | | checkpoint credentials | Management sign-in, grants, delegations, organization model keys and workload keys | | checkpoint connection | Inspect the current project, organization identity and configured services | | doctor | Check an MCP server project's packages, environment and registry connectivity |

Configuration

| Variable | Effect | | -------------------- | --------------------------------------------------------------------------------- | | CHECKPOINT_API_URL | Checkpoint origin (default https://kya.vouched.id) | | KYA_OS_PROJECT | Project, by ID or name, for commands that take --project | | CHECKPOINT_API_KEY | This app's runtime API key; kya-os checkpoint key set stores it in .env.local |

Where state lives

| Location | Holds | | ---------------------------------------------------------- | ------------------------------------------------------------------------------------ | | OS credential store (macOS Keychain, Linux Secret Service) | Your Checkpoint sign-in; never written to a file | | .kya-os/project.json | This repository's project link; no secret, safe to commit | | .env.local | This app's runtime API key; kya-os checkpoint key set gitignores it before writing |

Troubleshooting

kya-os: command not found, or you are looking for mcpi

The mcpi binary was removed in 2.x; kya-os is the entry point. Existing .mcpi/ state keeps working. Check that npm installed the platform package for your machine, for example npm ls @kya-os/cli-darwin-arm64; reinstall if it is missing.

A global install fails with a permission error

Use npx -p @kya-os/cli kya-os, or point npm at a directory you own (see npm's guide to resolving EACCES errors) instead of installing with sudo.

License

MIT