CLI Reference

Story workflow

The day-to-day loop — status, stories, next, implement, check, show, done, stop, and add.

This is the command group you'll use most: picking up a story, proving its acceptance criteria pass, and marking it done.

intent status

intent status

Displays a progress bar (percent complete), a story count breakdown (done / in-progress / todo), per-activity completion, and the last five activity log entries.

intent stories

intent stories
intent stories --filter todo
intent stories --status done
intent stories --kanban

Status aliases accepted by both flags: todo; in-progress, in_progress, or wip; done.

intent next

intent next
intent next --skip-wip
intent next --story-id a1b2c3
intent next --open

Selection logic:

1. If --story-id is given, resolve that story directly.
2. Otherwise, if any story is already in-progress (and --skip-wip wasn't passed), surface it and stop — finish what's in flight before starting something new.
3. Otherwise, pick the first todo story whose dependencies are all done, sorted by build sequence → release → priority (must > should > could) → effort (S > M > L > XL).
4. If every remaining todo has unfinished dependencies, prints an error naming what's blocking.
5. If everything is done, prints a completion message.

Prints title, activity, priority, effort, release, build sequence, acceptance criteria, ID, and the spec URL.

intent implement <id>

intent implement a1b2c3
intent implement a1b2c3 --stub

Picks up a story: marks it in_progress, and writes its working context to .intent/stories/<id>.md. Errors if the story is already done; warns (but proceeds) if it's already in progress. Blocks — with the list of what's outstanding — if the story has unfinished dependencies. Warns if the story has no acceptance criteria at all, since acceptance criteria are what define "done." For an XL-effort story, asks for confirmation before proceeding (a nudge to break it down first).

--stub: for each acceptance criterion that doesn't yet have an executable verification command, sends the criterion text to Claude Haiku and asks it to suggest one. Writes the suggestions to .intent/stories/<id>.checks.md for you to review, copy into the criterion's verification.command on the web UI, and then run with intent check. This does not generate test files or a failing test skeleton in your codebase — it's a text suggestion, and it's skipped silently if no Anthropic key is configured.

intent check [idPrefix]

intent check                    # checks the in-progress story
intent check a1b2c3
intent check --report

Runs every acceptance criterion whose verification method is executable and has a command attached, locally, and prints ✅/❌ per criterion (plus the first line of any failure output). Criteria with method agent_self_check, visual_render, or founder_confirm — or an executable criterion missing a command — are printed with a ⬜ and skipped, since there's nothing to run.

If you don't pass an ID, it resolves the single in-progress story; it errors if there's zero or more than one story in progress and you didn't disambiguate. Exits with status code 1 if any executable criterion failed, so it's usable as a CI gate.

intent show <id>

intent show a1b2c3

Prints the full spec for a story: activity, type, priority, effort, release, the user story broken into as-a/i-want/so-that, acceptance criteria as checkboxes, notes, and evidence. Also (re)writes .intent/stories/<id>.md, so this doubles as "load this story's context locally" even outside the next/implement flow.

intent done <id>

intent done a1b2c3
intent done a1b2c3 --screenshot ./screenshot.png

Marks a story done. Before it does:

• Must-criteria guard: if any must-priority acceptance criterion isn't reported as passing (failing, blocked, or never reported via report_criteria/intent check --report), it lists them and asks "Mark done anyway?" — you can override, which is recorded as forced: true. should and legacy (unprioritized) criteria never block.
• Implementation context: pulls the implementation notes and relevant-files list out of .intent/stories/<id>.md, if present, and attaches them to the completion record.
• Screenshot: if --screenshot is given, uploads that file. Otherwise, if the project has an appUrl configured, it auto-captures one via a headless browser. Either way, failure here is non-fatal — it won't block marking the story done.
• Decision prompt: after marking done, prompts you for a decision or lesson learned; if you provide one, logs it the same way intent decide would.

If the story completes the last item in its release, prints a celebration message with the release name and story count.

intent stop <id>

intent stop a1b2c3

Resets an in-progress story back to todo and stamps a cancelled_at timestamp — the signal any AI agent working the story (via MCP or CLI) should watch for to stop immediately. Errors if the story isn't currently in progress.

intent add <title>

intent add "Password reset flow"
intent add "Password reset flow" --activity Auth --priority must --effort L

Creates a new story directly from the terminal — useful when you spot a requirement mid-implementation and don't want to break flow to open the web UI.