Altitude

CLI reference

The altitude command-line surface — everyday commands plus the scope and connection authoring twins of the canvas tools.

Every command supports --json for machine-readable output, and most accept --cwd <path> to point at a project other than the current directory. Run altitude <command> --help for the full flag list.

Everyday commands

altitude init

Adopt Altitude into an app — writes .altitude/ config, the starter Templates, a guarded ## Altitude section in CLAUDE.md, and a pre-commit guard. --force re-runs over an existing .altitude/.

altitude init

altitude ui

Open the board in your browser. Cloud-free by default (renders off your committed .altitude/ files).

altitude ui [--cloud] [--port <n>] [--no-open] [--detached]
  • --cloud — turn on catalogue search sync (the Meilisearch mirror).
  • --detached — keep the server running after the launching command returns (use this when an agent starts the board in the background).

altitude mcp

Start the per-worktree MCP server (stdio) for any external agent.

altitude mcp --cwd /abs/path/to/worktree [--allow-ui-control]

--allow-ui-control permits mutating tools (writing to the board, driving your open tab). Omit it for read-only.

altitude map

Read the whole map — scopes, connections, and any drift, pending changes, or uninstructed code changes. The exact CLI twin of the get_map tool.

altitude map

altitude check

Re-run the board’s own surface resolver and fail on any scope surface with no content behind it (a missing file, a dead resolver, an unknown Template). This is what the pre-commit guard runs.

altitude check

altitude search <query>

Search the cloud catalogue and local code in one shot.

altitude search "login form" [--template <t>] [--repo <name>] [--limit <n>]

altitude agreement

End a turn: stage the board and code changes and commit them as one, carrying the Altitude-Agreement trailer.

altitude agreement [--message "<subject>"]

altitude session list / altitude session export

Read and export the local session recorder’s history. Export writes a session artifact folder.

altitude session list
altitude session export [--session <id>] [--out <dir>]

altitude id --backfill

Add a UUID id to every manifest that lacks one.

altitude id --backfill

altitude template create

Scaffold a new Template handler at .altitude/templates/<template>/handler.ts.

altitude template create --name <template> [--description "<d>"]

Board authoring — scope & connection

These are the CLI twins of the canvas tools. They write the same committed board YAML, so a shell-only agent has the whole build loop without MCP.

Scopes

# create a folder-less scope record (can group others)
altitude scope create --name "<name>" [--parent <id>] [--template <t>] [--status proposed|built]

# propose a scope — a spec with no code yet (renders in blueprint state)
altitude scope propose --template <t> --name "<name>" [--description "<d>"] [--surfaces a,b]

# report a scope's lifecycle status (built = the completion flip)
altitude scope status --scope <id> --status proposed|built|stale

# light the under-construction presence on scope(s) — comma-separated for a batch; --off clears
altitude scope building --scope <ids> [--off]

# mark a built scope for removal — the board's "remove this"; --off cancels
altitude scope removal --scope <ids> [--off]

# move a scope into another scope's members (its home) / drop it back to the top level
altitude scope add  --scope <id> --member <id>
altitude scope drop --scope <id> --member <id>

# discard a proposed scope (refuses a built scope) / delete a record
altitude scope remove --scope <id>
altitude scope delete --scope <id>

# list scope records as a containment tree
altitude scope tree

Connections

# add a connection between two scopes
altitude connection add --from <id> --to <id> --type <t> [--description "<d>"] [--status proposed|built]

# report a connection's status (its own truth — never derived from endpoints)
altitude connection status --connection <id> --status proposed|built|stale

# under-construction presence on connection(s) — comma-separated batch; --off clears
altitude connection building --connection <ids> [--off]

# mark a built connection for removal; --off cancels
altitude connection removal --connection <ids> [--off]

# discard / delete a connection
altitude connection remove --connection <id>
altitude connection list

Offline render check

For a repo with no Node toolchain, the render check also ships as a standalone altitude-validate binary — a strict superset of altitude check (the same render verdict plus map-integrity: dangling connections, a malformed scope tree). It reads only .altitude/ YAML and runs nothing in your project, so it drops into a commit hook on any language.