@iamu-dev/iamu

Scenario-driven development CLI — test your product as realistic personas.

Part of the iamu platform.

Installation

Run directly with npx:

npx @iamu-dev/iamu@beta <command>

Or install globally:

npm install -g @iamu-dev/iamu@beta

Prerequisites: Node.js 22+ and Google Chrome.

Quick Start

In the root of your project:

npx @iamu-dev/iamu@beta init

iamu init scaffolds the iamu/ directory and configures skills for your editor (Claude Code, Cursor, Windsurf, GitHub Copilot, Cline, Codex, RooCode, Antigravity).

Core Commands

Project & Health

| Command | Description | |---------|-------------| | iamu init [--yes] [--json] | Initialize or configure an iamu project in current workspace | | iamu status [--json] | Overview of personas, scenarios, active runs, and cloud sync status | | iamu doctor [-t <url>] [--json] | Diagnose directory structure, schemas, and missing dependencies | | iamu preflight [--cwd <path>] [--json] | Fast typecheck verification before walkthroughs | | iamu list [type] [--capability <slug>] [--json [fields]] | List personas, scenarios, findings, capabilities, or outlines | | iamu new <type> [--name <name>] [--slug <slug>] | Create a new entity (persona, outline, scenario, source, capability) | | iamu set <type> [slug] | Set fields or configuration on existing entities | | iamu edit <type> [slug] | Interactively edit an entity or context configuration | | iamu explore / iamu explore run [url] | Map the running product with a read-only crawl, and compare maps with runs | | iamu validate [path] [--all] | Validate entity files against protocol schemas | | iamu update [--host <name>] | Refresh installed editor agent skills to latest templates |

Walkthrough Execution Loop

start-run → instructions walk → browse step / step, new-finding, summary
→ complete → match / match-record → evaluate / evaluate-record
→ advise / advise-record → designer / designer-record → sync → report

| Command | Description | |---------|-------------| | iamu start-run <scenario> --target <url> | Scaffold a new walkthrough run directory with metadata | | iamu browse <command> [args] | Control Google Chrome via CDP (start, goto, click, fill, shot, snapshot) | | iamu step [run-id] --action "..." | Record a walkthrough step atomically into steps/ and screenshots/ | | iamu new-finding [run-id] | Scaffold a new finding markdown file with valid UUID and frontmatter | | iamu summary [run-id] [--json] | Record closing synthesis or early blocker reason | | iamu complete <run-id> [--json] | Assemble canonical report, evaluate provenance, and mirror to cloud | | iamu match <run-id> | Generate matching prompt to link findings to prior runs | | iamu match-record <run-id> --file <path> [--json] | Record matcher resolutions and re-derive run delta | | iamu evaluate <run-id> [--json] | Compose evaluation prompt for human-test questions | | iamu evaluate-record <run-id> --file <path> [--json] | Record evaluation verdicts into verdicts.json | | iamu advise [run-id] [--json] | Compose technical advisor prompt for code-level recommendations | | iamu advise-record [run-id] [--file <path>] [--json] | Record accepted recommendations and systemic directions | | iamu designer <run-id> [--json] | Compose design review prompt comparing screens to design docs | | iamu designer-record <run-id> [--file <path>] [--json] | Record designer review findings and rule evaluations | | iamu designer-dismiss <run-id> <finding> | Dismiss a designer finding (D) from a run's designer review | | iamu directions [set <slug>] | List structural changes proposed by the advisor, or update direction status | | iamu fix-brief [finding] | Synthesize concrete remediation brief from finding and directions |

Design & Review

| Command | Description | |---------|-------------| | iamu design status [--json] | Check recorded design docs, rules cited, and open proposals | | iamu design detect [--record] [--json] | Detect design docs, CSS/tokens, and component systems in repo | | iamu design sources <paths...> [--kind <kind>] [--applies-to <list>] | Record files or headings as authoritative design references | | iamu design review <target> [--json] | Compose design review prompt for a specific page or route | | iamu design review-record <target> [--file <path>] [--json] | Record design review answers for a reviewed page | | iamu design review-match <target> [--json] | Write prompt to check earlier designer findings after a page review | | iamu design review-match-record <target> [--file <path>] [--json] | Record match answer indicating which earlier designer findings are still present | | iamu design proposals [--json] | List design changes proposed across walkthroughs and reviews | | iamu design accept <slug> | Accept a proposed design change | | iamu design reject <slug> | Reject a proposed design change |

Findings & Review

| Command | Description | |---------|-------------| | iamu findings [--open] [--addressed] [--fix-state <state>] [--json [fields]] | List findings with triage status, fix state and severity | | iamu triage <finding-ref...> --status <status> | Triage findings (open, addressed, dismissed) | | iamu report [scenario] [--json] | View walkthrough reports and finding summaries | | iamu prune [--keep <n>] [--days <n>] | Prune old runs and reclaim disk space |

Cloud Sync & Collaboration

| Command | Description | |---------|-------------| | iamu auth login [--token <key>] | Authenticate with Iamu Cloud | | iamu auth status [--json] | Check authentication and linked cloud project status | | iamu sync [--confirm-deletes] [--json] | Push local runs and entities to cloud | | iamu pull [--preview] [--force] [--json] | Pull remote team updates into local store | | iamu open [run-id] | Open run or project in the cloud web dashboard |

Programmatic & MCP Integration

MCP Sync Server

To run the Model Context Protocol sync server for agent integration:

iamu sync-server

JSON Projection Convention

Commands supporting --json emit machine-readable JSON to stdout:

iamu list personas --json slug,name,role
iamu findings --open --json slug,severity,type

License

MIT © iamu-dev