@maias/cli — the maias command

Terminal tooling for MAIAS documents, built directly on @maias/core — the CLI is argument parsing and output rendering only, so its verdicts are identical to the MCP server's and the MAIAS Browser's.

Setup

No install needed:

npx @maias/cli validate <file>   # runs the `maias` bin straight from npm
npm i -g @maias/cli              # optional: global `maias`, usable from any directory

From a clone of this repo instead:

npm install && npm run build
npx maias validate <file>        # works anywhere inside the repo
npm run link-tools               # optional: global `maias` tracking the workspace build

Undo a global install/link with npm rm -g @maias/cli @maias/mcp. (The agent-facing docs — CLAUDE.md and the skills — deliberately keep the explicit ./node_modules/.bin/maias path: it needs no PATH assumptions on a fresh clone.)

Commands

maias validate <file> [--json]

JSON Schema validation plus semantic lint (dangling targets, orphans, registry membership, duplicate ids/paths), with file:line:col positions:

$ maias validate my-app.maias.yaml
my-app.maias.yaml:42:11 error MAIAS-E003 Dangling target 'ghost' on screen 'home' (element 'Go') — no such screen
my-app.maias.yaml: invalid — 1 error, 0 warnings

--json emits the documented { file, valid, diagnostics[] } shape for scripts and CI. Exits 1 on errors (warnings pass), 2 on usage/IO problems.

maias fmt <file> [--write|--check]

Canonical formatting (spec §11: fixed key order, derived screen ordering, omit-empty). Idempotent, comment-preserving. Default prints to stdout; --write updates the file; --check exits 1 if the file isn't canonical (CI-friendly). Refuses to format a document with validation errors — fix those first.

maias rename <file> <old_id> <new_id>

Renames a screen id and cascades to every reference — flows, the navigation registry, element and navigation targets, back.target — then writes canonical form:

$ maias rename my-app.maias.yaml feed home_feed
my-app.maias.yaml: 'feed' → 'home_feed' (5 references updated)

Never rename by find-and-replace; this is the tool.

maias migrate <file> [--write]

Upgrades a ≤0.2 document to spec 0.3, deterministically and comment-preservingly: screen actions → capabilities, app.links → app.deep_links, navigation.secondary items whose target is already an element target dropped (reported per drop — the elements-first rule), header bumped, canonical form written. Default prints to stdout; --write updates the file.

maias tree <file> [--refs] [--json]

Text outline of the document: header, tab bar, one section per flow with each screen's id, title, and markers (type, tab, modal/sheet/replace, auth, deep_link, back→id). --refs appends outbound targets and declared states; --json emits the structured outline. Works on any parseable document — it's a read-only view, useful mid-edit.

$ maias tree examples/ecommerce/maias.yaml
Shopfront — 14 screens, 3 flows
Tab bar: Home · Categories · Cart · Account

Flow: browse — From storefront to product.
├─ home        Home        (marketing, tab)
…

maias diagram <file> [--flow <name>] [--format mermaid]

Mermaid flowchart of the screen graph — paste it into GitHub, Claude, Obsidian, or mermaid.live. One subgraph per flow, one node per screen, edges deduped, tabs and modals styled via classes, back links dotted (and elided when they just reverse a forward link). --flow scopes the diagram to one flow — the escape hatch for very large documents.

maias wireframe <file> [-o <path>] [--accent <hex>] [--states] [--flow <name>] [--force]

Self-contained HTML wireframe board — one file, inline CSS, no JavaScript, no external URLs. One 390×844 phone frame per screen with spec-defined chrome (status bar; header with back chevron iff back: is declared; tab bar from app.navigation.primary, hidden on modal/sheet screens), elements drawn in document order, one row per flow, and every target an in-page anchor — free click-through between frames:

$ maias wireframe my-app.maias.yaml
my-app-wireframes.html: 14 screens, 14 frames, 3 flows

-o sets the output path (default: <input>-wireframes.html next to the input). --accent swaps the wireframe grey for a brand colour. --states adds each declared empty/loading/error variant as an extra frame (full-replacement element lists per the spec). --flow renders one flow's row. Unlike tree/diagram, this command refuses documents with validation errors — a dangling target would render as a dead link — unless you pass --force.

What the CLI deliberately doesn't do

Screen add/remove and element-level edits are exposed through the MCP server (edit, edit_elements), whose structured JSON input fits those operations better than argv would — a CLI element command is deferred by design (D20). For document authoring, start from docs/spec/llms.txt or the Claude skills.

Development

npx vitest run packages/cli   # exit codes, output shapes, rename behaviour