The kimtu CLI

Query the architecture and documentation of a workspace from the terminal, or let your coding agent do it. Read-only.

Install and sign in

The CLI is published to npm as @kimtu/cli. It needs Node 22 or later and a Kimtu account.

terminal

npm install -g @kimtu/cli
kimtu login

kimtu login opens your browser. Your credentials are kept in your operating system's keychain, or in a file only you can read when there is none. On a machine with no browser, kimtu login --no-browser prints the sign-in URL instead.

Commands

Every command only reads. The CLI cannot change a workspace: the architecture comes from the repository’s own files.

kimtu login: Signs you in through your browser. kimtu logout signs you out and kimtu whoami prints who you are signed in as.
kimtu workspaces: The workspaces you belong to.
kimtu use <slug>: Chooses the default workspace, so the commands below need not name one.
kimtu overview: Counts, repositories and issues. Start here.
kimtu components: Every component, one line each.
kimtu component <id>: One component: what it sends data to and what it receives from.
kimtu docs: Every document, grouped by repository.
kimtu doc <repository> <path>: One document's markdown.
kimtu search <text>: The components and documents that match.
kimtu guide: How a coding agent should use the CLI, in the version you have installed.

Output and workspaces

Output is markdown, sized to be read by a person or a model. Add --json to any query for the API's JSON instead. Messages meant for people go to stderr, so what a command prints stays clean to pipe.

Queries run against the default workspace. Pass -w, --workspace <slug> to ask about another one for a single command.

For coding agents

Sign in once on the machine the agent runs on, then tell it the CLI exists. The prompt a workspace gives you for a repository offers to add this block to AGENTS.md after a successful sync, and changes nothing until you agree. To do it by hand, put it in AGENTS.md, CLAUDE.md or equivalent. It points at kimtu guide, which ships with the CLI, so the instructions stay current as the CLI changes.

AGENTS.md

## Kimtu

This project's architecture and documentation are in Kimtu. Before guessing
how the system fits together, run `kimtu guide` and use the `kimtu` CLI. If
it is not installed or not signed in, tell the developer instead of guessing.

Other environments

The CLI signs in to production, kimtu.dev, by default. To point it at another instance, set all three of these. Credentials are kept separately for each environment.

KIMTU_API_URL: The API to talk to.
KIMTU_ISSUER: The sign-in provider's frontend API URL.
KIMTU_CLIENT_ID: The OAuth client the CLI signs in with.