CLI Reference · 4.7

Story maps

Plan a change as stories with propose, and move a whole story map in from an existing codebase with map extract and map import.

These commands add stories in bulk. propose plans one change. map extract and map import build a story map from a codebase that already exists. map schema prints the file format they share.

`intentdocs propose`

Plans a change as stories on your map and saves a local copy of the proposal.

intentdocs propose [name] [--from <file>]

Argument	Meaning
`name`	The change's name, such as `add-dark-mode`. Optional; the CLI prompts for it, or takes it from the file with `--from`.

Option	Default	Meaning
`--from <file>`	none	Read the proposal from a Markdown file instead of prompting

intentdocs propose add-dark-mode
intentdocs propose --from proposal.md

Needs a valid login and a connected checkout.

Interactively, it asks for the problem, the solution, an activity (General when you leave it blank) and a priority (should by default). Then it asks for stories one at a time: a title, an effort (M by default) and acceptance criteria, one per line. An empty title ends the list. It shows a summary and creates the stories when you confirm.

With --from, it reads the file, prints the stories it found, and creates them without asking. The file looks like this:

# Proposal: add-dark-mode
 
**Problem:** The app is hard to read at night.
**Solution:** A theme toggle that follows the system setting.
**Activity:** Settings
**Priority:** should
 
## Add a theme toggle
**Effort:** S
- The toggle persists across sessions
- The default follows prefers-color-scheme
 
## Theme the checkout pages
**Effort:** M
**Priority:** must
- Every checkout page passes contrast checks in dark mode

# sets the change name. A name you pass on the command line wins; without either, the file name is used.
**Problem:**, **Solution:**, **Activity:** and **Priority:** above the first story set the defaults.
Each ## heading starts a story. **Effort:**, **Activity:** and **Priority:** under it override the defaults for that story.
Each - line under a story is an acceptance criterion. A leading [ ] is removed.

Either way, it writes intent-changes/<name>/proposal.md with the problem, solution and stories, each tagged with its new story ID. If creating the stories fails, it still saves the local file.

Behaviour to know:

The name is lowercased, spaces become hyphens, and other characters outside a-z, 0-9 and - are dropped.
With --from, it exits 1 when the file is missing or has no ## stories.
New stories have no place in the build order. Sequence them on the Plan view before intentdocs next will offer them.
If the project has a .gitignore that does not already cover intent-changes/, both flows add an intent-changes/ line to it, once.

`intentdocs map extract`

Prints a prompt that has your coding agent build a story map from an existing codebase.

intentdocs map extract

No arguments or options. Needs a connected checkout, but makes no network calls.

Paste the printed prompt into your coding agent from the repository root. It tells the agent to read the code (routes, auth, the API, the data model, the stack and billing), describe what users do in their own words, and write storymap.json in the format intentdocs map schema describes. Features the agent cannot confirm go into open_questions rather than the map. The prompt ends by telling the agent to run intentdocs map import ./storymap.json.

For more on this flow, see Brownfield agent prompt.

`intentdocs map import`

Validates a storymap.json file and adds it to your story map.

intentdocs map import <file> [--yes]

Argument	Meaning
`file`	Path to the `storymap.json` file

Option	Default	Meaning
`--yes`	off	Import without asking for confirmation

intentdocs map import ./storymap.json
intentdocs map import ./storymap.json --yes

The CLI checks the file before it sends anything. The first problem it finds stops the import, with a message naming the field. The rules:

Field	Rule
`schema_version`	Must be `"1"`
`product_summary`	Required, up to 1,000 characters
`backbone`	1 to 20 activities
Activity	Only `activity` (up to 200 characters) and `tasks` (1 to 30)
Task	Only `task` (up to 200 characters) and `stories` (1 to 50)
Story	Only `story`, `evidence`, `confidence` and `plan_gate`. `story` must start with `As a` or `As an` . `story` and `evidence` are required, up to 500 characters each.
`confidence`	`high`, `medium` or `low`
`plan_gate`	`free`, `pro`, `team` or `null`
`open_questions`	Up to 50 strings, up to 500 characters each
Top level	Only `schema_version`, `source`, `product_summary`, `backbone`, `data_model`, `build_order`, `critical_assumptions`, `open_questions` and `stack`

Text fields cannot be empty or contain control characters.

It then prints a summary (the product summary, counts of activities, tasks and stories, the confidence breakdown and the number of open questions) and asks Import this storymap into your story map?. After the import, it prints how many stories, activities and steps it created, and how many open questions wait for you in the web app.

Behaviour to know:

Any 402 or 403 response prints the plan upgrade message from AI features, even when the cause is your access to the project. Check that with intentdocs projects.
Without a terminal to answer the prompt, pass --yes, or the import is cancelled.
A 401 from the server means your login is no longer valid. The CLI tells you to run intentdocs login, then re-run the import, and exits 1.

`intentdocs map schema`

Prints the JSON Schema for storymap.json.

intentdocs map schema

No arguments or options, and no connected checkout needed. The output goes to standard output, so you can save it:

intentdocs map schema > storymap.schema.json

Use it to validate a storymap.json your own tooling produces before you run intentdocs map import.