CLI reference

AlienMonster ships 12 commands via npx alienmonster. This page covers every one.

Run npx alienmonster --help from a terminal for the built-in help.

Setup commands

init

$ npx alienmonster init [name]

Scaffolds .alienmonster/ in a new or existing repo. Two modes:

• init my-project — creates ./my-project/ with .alienmonster/,ALIENMONSTER.md, agent config files, and a git commit.
• init (no args) — adds .alienmonster/ and agent config files to the current directory. Idempotent: safe to re-run to refresh managed sections.

Runs entirely offline — no auth needed.

Exit codes: 0 success; 1 invalid name / dir exists.

login

$ npx alienmonster login

Device-flow OAuth. Opens your browser, prompts for a device code, stores credentials in ~/.alienmonster/credentials.json.

Flags: --server <url> defaults to alienmonster.ai — override only for dev.

Exit codes: 0 success; 1 auth error.

logout

$ npx alienmonster logout
  ✅ Logged out. Local credentials removed.

Deletes local credentials. Exit code: 0.

whoami

$ npx alienmonster whoami
  👾 Logged in as you@example.com
     Server: https://alienmonster.ai
     Expires: 2026-05-24T12:00:00Z

Shows the logged-in user, server URL, and token expiry. Reads local credentials only — no network. Exit code: 0.

connect

$ npx alienmonster connect
  👾 Connecting AlienMonster MCP...
  ✅ Claude Code: registered via `claude mcp add`
  ✅ Cursor: updated ~/.cursor/mcp.json

Registers the AlienMonster MCP server with Claude Code and/or Cursor. Prompts interactively if both are available. Requires login.

Exit codes: 0 success; 1 auth expired or MCP token fetch failed.

new

$ npx alienmonster new my-saas
  ✅ Created project "my-saas" at /projects/abc123
     Strategy repo seeded with CLAUDE.md, tasks.md, assumptions.md,
     decisions.md, context.md, strategy.json.

Creates a server-side project (alternative to creating via the dashboard). Requires login. Required arg: project name.

Exit codes: 0 success; 1 missing name / create failed.

Sync commands

status

$ npx alienmonster status
  👾 Project: my-project
     Auth: ok (you@example.com)
     Local revision: 42
     Server revision: 42
     Status: up-to-date

The sync trust surface. Shows cache freshness, auth state, lock state, and local modifications. See Sync model.

Flags: --porcelain (key=value), --json, --repo (legacy status-repo), --project <id>.

Exit codes: 0 success; 2 invalid flag combo.

sync

$ npx alienmonster sync
  Local revision: 42, server revision: 43
  Refreshing .alienmonster/... ✓

Manual refresh. No-op if the server hasn't advanced. Acquires a single-writer lock. --force re-exports regardless (equivalent to export).

Exit codes: 0 success; 1 no .alienmonster/ or no project; 2 lock held; 3 auth expired or server unreachable.

watch

$ npx alienmonster watch
  👾 Watching for strategy changes...
  → revision-advanced, syncing...
  ✓ Updated to revision 44

Long-running SSE subscriber. Auto-syncs on revision-advanced events. Polling fallback on disconnect. Graceful shutdown on SIGINT/SIGTERM.

Exit codes: 0 success; 1 no .alienmonster/; 3 auth expired; 4 access denied (403).

export

$ npx alienmonster export
  sync.export.start projectId=abc123 rev=42
  ✅ Wrote .alienmonster/decisions.md (3 primitives)
  ✅ Wrote .alienmonster/assumptions.md (2 primitives)
  ...

Unconditional full rewrite of .alienmonster/ from the server. Writes rendered markdown + JSON with chmod 444 and banners. Acquires a lock.

Exit codes: 0 success (including the "no strategy data yet" case — fresh project with no primitives writes nothing and exits cleanly); 1 missing .alienmonster/ or no project; 2 lock held.

Account and reference

projects

$ npx alienmonster projects
  my-saas          /projects/abc123   (12 sessions, updated 2d ago)
  side-project     /projects/def456   (3 sessions, updated 2w ago)

Lists projects you have access to. Requires login.

Exit codes: 0 success; 1 auth expired.

insights

$ npx alienmonster insights --days 7
  Langfuse snapshot — last 7 days
  Sessions: 14 total, 12 completed
  Top suggestions:
    → Probe harder on 'who' dimension (P75 latency up 20%)
    → 3 unresolved assumptions across 2 projects

Observability / learning-loop tool. Pulls Langfuse aggregates and surfaces suggestions. Flag: --days <n> (default 7).

This is an admin tool — not part of the primary user workflow.

Exit codes: 0 success; 1 Langfuse not configured.

Exit codes

Common flags

• --help / -h — show command help.
• --project <id> — override the default project (used by status, sync, watch, export).
• --json — machine-readable output (on status).
• --porcelain — scripting-friendly output (on status).
• --force — override guards (on sync).