CLI Reference · 4.1

CLI overview

Every intentdocs command in one table, plus how the CLI signs in, names stories and writes files.

The intentdocs CLI connects a repository to its story map. You use it to pick up stories, run acceptance criteria, mark work done, log decisions, and wire up your coding agent and CI.

Install and run

The npm package is intentdocs. It installs two commands, intentdocs and intent, which run the same program. intentdocs is the canonical name. intent is a shorter alias that may collide with other tools on your machine.

npm install -g intentdocs
intentdocs --help

You can also run any command without installing it:

npx intentdocs status

The CLI's own messages use the npx intentdocs form. This reference writes intentdocs.

Command index

Command	What it does	Reference
`intentdocs login`	Sign in through the browser and store a token on this machine	Auth and keys
`intentdocs logout`	Delete the stored token	Auth and keys
`intentdocs projects`	List the projects your token can reach	Auth and keys
`intentdocs keys set [key]`	Save your Anthropic API key for AI features	Auth and keys
`intentdocs keys status`	Show whether a key is saved, masked	Auth and keys
`intentdocs keys remove`	Delete your saved key	Auth and keys
`intentdocs start`	Guided flow from a problem to a new project	Project setup
`intentdocs scope [projectId]`	Generate a blueprint and story map, then connect this directory	Project setup
`intentdocs templates [name]`	List story map templates, or preview one	Project setup
`intentdocs init`	Connect this directory to an existing story map	Project setup
`intentdocs sync`	Refresh `INTENT.md`, or the `CLAUDE.md` context file with `--context`	Project setup
`intentdocs setup`	Configure Claude Code or Cursor for this project	Project setup
`intentdocs status`	Show progress for the connected story map	Story workflow
`intentdocs stories`	List stories, filtered or as a kanban board	Story workflow
`intentdocs next`	Show the next story to build	Story workflow
`intentdocs implement <id>`	Mark a story in progress and write its context file	Story workflow
`intentdocs check [idPrefix]`	Run a story's executable criteria on your machine	Story workflow
`intentdocs show <id>`	Print a story's full spec	Story workflow
`intentdocs done <id>`	Mark a story done	Story workflow
`intentdocs stop <id>`	Stop an in-progress story and signal agents to stop	Story workflow
`intentdocs add <title>`	Create a story	Story workflow
`intentdocs decide [title]`	Log a decision	Decisions and memory
`intentdocs decide list`	List logged decisions	Decisions and memory
`intentdocs decide amend <id>`	Change a decision's title, description or category	Decisions and memory
`intentdocs decide delete <id>`	Retract a decision (alias `retract`)	Decisions and memory
`intentdocs note <storyId> [note]`	Add a note to a story	Decisions and memory
`intentdocs example`	Add a before/after code example to the project	Decisions and memory
`intentdocs complexity [storyId]`	Score story complexity with AI	AI features
`intentdocs research [query]`	Research a question with AI, using your project context	AI features
`intentdocs import [file]`	Turn a PRD or spec into stories	AI features
`intentdocs propose [name]`	Plan a change as stories and save a local proposal	Story maps
`intentdocs map extract`	Print a prompt that has your agent extract a story map from code	Story maps
`intentdocs map import <file>`	Import a `storymap.json` file	Story maps
`intentdocs map schema`	Print the JSON Schema for `storymap.json`	Story maps
`intentdocs mcp`	Run the local MCP server over stdio	Integrations
`intentdocs openclaw-register`	Register the local MCP server with OpenClaw	Integrations
`intentdocs ci`	Set up CI test reporting for this project	Integrations

Every command also takes -h, --help. The root command takes -V, --version.

How the CLI signs in

There is one credential: the token intentdocs login stores in ~/.intent/auth.json. Every call to your story map sends it. The server checks your access to the project on each call, and every change is recorded as yours.

Sync tokens are retired. intentdocs init takes no token. A checkout connected the old way has no map id in its config, and commands tell you to remove .intent/config.json, log in, and run intentdocs init again.
A token is either personal or bound to one workspace. You choose in the browser when you log in. See Workspaces and tokens.
Reading needs access to the project. Writing (status changes, criteria results, notes, decisions, new stories) also needs edit rights. When the server refuses, the CLI prints its reason.

How to name a story

Every command that takes a story accepts its key, such as PB-42, when the project has keys, its full ID, or the start of its ID. Keys match regardless of case. That covers show, implement, done, stop, check, next --story-id, note, complexity and decide --story.

A prefix matches the first story whose ID starts with it, so use enough characters to be unique. intentdocs stories prints each story's key, or the first eight characters of its ID when it has no key.

Files the CLI writes

Path	Written by	What it holds
`~/.intent/auth.json`	`login`	Your token, user id, and the workspace the token is bound to. One per machine, shared by every project.
`.intent/config.json`	`init`, `scope`	The API base, project id, map id, map title, and the workspace this checkout belongs to. No secret.
`INTENT.md`	`init`, `scope`, `sync`	The story map as Markdown, for your agent to read.
`.intent/stories/<id>.md`	`implement`, `show`, `sync`	One story's working context: criteria, plan, notes and relevant files.
`CLAUDE.md` or `.claude/CLAUDE.md`	`setup`, `sync --context`	The project's assembled agent context.

Commands look for .intent/config.json in the current directory, then in each parent directory, the way Git finds .git. You can run them from any subdirectory of a connected repository. init adds .intent/ to an existing .gitignore.

Exit codes

Commands exit 0 on success and 1 when they cannot do what you asked. A few cases are worth knowing:

intentdocs check exits 1 when any executable criterion fails, so you can use it as a gate.
intentdocs done exits 1 when a must criterion blocks it and there is no terminal to confirm an override, and when the server does not confirm the story is done.
intentdocs implement exits 1 when the server refuses to start the story, for example because the project's build gate has not cleared it. It prints the server's reason.
intentdocs implement and stop exit 1 when no story matches. next --story-id prints a message and exits 0.
Most commands that need a connected checkout exit 1 with Not initialized. Run: npx intentdocs init when they find no .intent/config.json. setup and propose say the directory is not connected to a project and exit 0.