klok

The command line client for the Klok integration platform. It runs tasks on your tenant's Klok agent, publishes documentation, keeps your workspace in sync, and exposes the platform to your IDE and coding agents over MCP and A2A.

npm install -g @klok-integration/cli
klok --help

Node 22.14 or newer. The package has no dependencies and runs no install scripts.

First run

klok config set agentUrl https://agent.klok.dev
klok login                     # device flow; add --browser for the browser flow
klok whoami
klok                           # opens the terminal UI

Configuration lives in ~/.config/klok/config.json. Every value can be overridden by an environment variable: KLOK_AGENT_URL, KLOK_TENANT, KLOK_DOMAIN, KLOK_DEV_URL, KLOK_KEYCLOAK_ISSUER, KLOK_KEYCLOAK_CLIENT_ID, KLOK_GIT_URL, KLOK_GIT_LOCAL_WORKSPACE, KLOK_GIT_APIKEY. Run klok config list to see what is set and where it comes from.

The GitLab token can be stored with klok config set klokApiKey: it asks Enter API key: and shows a * for each character, so the token stays off the screen and out of the shell history. It is shown as **** everywhere unless you run klok config get klokApiKey --reveal, and the file is kept at mode 0600.

Credentials are written to ~/.config/klok/credentials.json with mode 0600.

Commands

| Command | What it does | | --- | --- | | klok | Terminal UI. j/k or arrows move, enter opens a task, a asks a question, b shows beads, r refreshes, q quits. | | klok login, klok logout, klok whoami | Session against your tenant's identity provider. | | klok config list\|get\|set\|delete | Configuration. | | klok agent ask "<question>" | Ask a question about the integration landscape and get a cited answer. | | klok agent impact <nodeId\|datamodel> --change minor\|major\|remove | Impact analysis. | | klok agent plan <solutionKey> --change-request <file\|-> | Integration plan following the Klok process. | | klok agent tasks, klok agent open <taskId>, klok agent cancel <taskId> | Work with tasks. | | klok agent answer <taskId> --question <qid> --text "..." | Answer a clarification and continue. | | klok agent serve [--port 3091] | Loopback MCP and A2A proxy for IDEs and other agents. | | klok agents init | Write the Klok agent instructions, the platform skills and your tenant's skills into a repository, with a Claude Code hook that keeps them fresh. | | klok agents update [--check] [--global] | Fetch what moved in the platform and tenant catalogs; --check writes nothing and exits 5 when something is outdated. | | klok agents status | Per file and per catalog: current, outdated, missing or unreachable. | | klok bead list\|show\|report | Progress beads in the current repository. | | klok docs list | The documentation projects on docs.klok.dev you may read, by doc id. | | klok docs read <doc-id> | Print a documentation project's llm.txt from docs.klok.dev, read with your GitLab token and cached. | | klok docs id [path] | The doc id of a repository path. | | klok docs publish | Build this repository's znai documentation and upload it to the docs portal. | | klok docs build | Build this repository's klok-docs/ with znai the way its documentation project will, uploading nothing. | | klok solutions next | The next free solution id of the tenant, from the registry, its open merge requests and the route classes on every branch of the workspace. | | klok solutions new "<name>" | Reserve the next solution id by a merge request in the registry, from a task worktree. | | klok solutions validate | Check the descriptors of an integration solution registry against the descriptor contract and, in a merge request, that no solution is removed and no solution id reused or taken twice. | | klok ci env | Show what klok-cli detected about the CI job it runs in. | | klok fleet status\|rebuild | Every deployed service: what it was built from, whether that is the latest commit and the catalog's broker client, and which clients the broker sees; rebuild the stale ones one pipeline at a time. | | klok manifest update | Set a container's image in a deploy manifest of your GitOps repository, then commit and push. | | klok pin update | Pin a released artifact (its version and the sha256 of the published file) in an infrastructure repository, through a merge request opened by push options. | | klok sync clone\|pull\|status | Clone and refresh every repository you can see, in one workspace folder. |

Global flags: --json, --no-tui, --stream, --tenant <slug>, --domain <slug>, --agent-url <url>.

Scripting

klok prints a terminal UI when stdout is a terminal, and a single JSON document otherwise, so it works unchanged in a shell pipeline or a CI job.

klok agent ask "which routes consume CustomerV1?" --json | jq -r '.result.answer'
klok agent plan KLK002 --change-request ./change.md --stream    # NDJSON events, then the result

| Exit code | Meaning | | --- | --- | | 0 | ok | | 1 | error | | 2 | the task needs input; the document carries details.questionId and details.question | | 3 | denied by policy; details.decisions lists capability, decision and reason | | 4 | not authenticated; run klok login |

Use it from your IDE and coding agents

klok agent serve            # 127.0.0.1:3091

• http://127.0.0.1:3091/mcp — MCP over streamable HTTP, with tools for context search, impact analysis, planning, issues, beads and task control. Long tasks send progress notifications.
• http://127.0.0.1:3091/a2a — Agent2Agent JSON-RPC proxied to your tenant's cloud agent with your identity.
• http://127.0.0.1:3091/.well-known/agent-card.json — the agent card.

claude mcp add klok --transport http http://127.0.0.1:3091/mcp
codex mcp add klok --url http://127.0.0.1:3091/mcp

Cursor (.cursor/mcp.json):

{ "mcpServers": { "klok": { "url": "http://127.0.0.1:3091/mcp" } } }

Agent instructions

klok agents init writes KLOK-AGENTS.md with the rules, one managed row in every harness file (AGENTS.md, CLAUDE.md, GEMINI.md, .cursorrules, .clinerules or a file inside a .clinerules/ directory, .github/copilot-instructions.md), the klok named rule files (.cursor/rules, .agents/rules) and the Klok skills. KLOK-AGENTS.md, the klok rule files and the klok-* skills belong to Klok and are replaced wholesale; every other file keeps its content and only has its single row created or replaced, so an update can never duplicate text. Klok skills the CLI no longer ships are removed. Your tenant's skills (<tenant>-context and one skill per documented repository) come from the tenant's private catalog with your GitLab token (KLOK_GIT_APIKEY); they are installed, kept out of git, and refreshed by klok agents update. klok agents status shows whether a repository is up to date with the catalogs. After you install or update the CLI, the first interactive run tells you when the instructions you installed with klok agents init --global or --workspace are older than the CLI, and prints the commands that update them.

Licence and support

Proprietary. See LICENSE.md in this package; third party notices are in THIRD-PARTY-NOTICES.md.

Documentation: https://docs.klok.dev — support: https://klok.dev/support