CLI

In an app that installed Atlas: npx atlas <command> --dir src/capabilities. Inside the Atlas repository: node bin/atlas.ts <command>. Every command accepts --dir <folder> to point at another capabilities folder.

usage: atlas <command> [--dir <capabilities-folder>]

  map [--json|--mermaid]   what exists and how it connects
  context <name> [--json]  what to know before changing <name>, and what breaks if you do
  check [--json]           is the system consistent? (exit 1 on errors)
  test                     run every handler example (exit 1 on failure)
  new <name>               scaffold src/capabilities/<name>.ts
  schema [--openapi]       JSON Schema of every contract (or OpenAPI 3.1 paths of the HTTP adapter)
  rebuild <view> --db <postgres-url>
                           replay a view from the outbox into a shadow table, then swap it in
  cursor list --db <postgres-url>
                           every consumer cursor, and the capability that owns it
  cursor copy <from> <to> --db <postgres-url> [--force]
                           start consumer <to> where <from> is (a split or a renamed consumer)
  compact --db <postgres-url> --older-than <30d|12h|90m>
                           delete tombstones of removed records older than that (at least 1h)

Development commands

Command	Answers	Exit
map [--json|--mermaid]	Every capability with its intent, commands, facts, reactions, views and queries; --mermaid draws a diagram.	0
context <name> [--json]	The file, contracts, upstream shapes and the field-level downstream blast radius of one capability.	1 for an unknown name (it lists the available ones)
check [--json]	Diagnostics ATLAS000-028, each with why and fix.	1 on any error
test	Runs every handler and query example; one line per example and a summary.	1 on any failure
new <name>	Scaffolds a kebab-case capability with a command and examples.	1 if the file exists or the name is invalid
schema [--openapi]	JSON Schema of every command input, query input and output, fact and view row; or OpenAPI 3.1 paths.	0

Operations commands (Postgres)

They need --db <postgres-url> (compact also reads DATABASE_URL).

Command	Does
rebuild <view>	Replays the view from the outbox into a shadow table and swaps it in atomically with the owning consumer’s cursor.
cursor list	Every consumer cursor, its position and the capability that owns it ((no capability) for orphans).
cursor copy <from> <to> [--force]	Starts <to> where <from> is: for a split or a renamed consumer. Refuses a target that already advanced unless --force.
compact --older-than <30d|12h|90m>	Deletes tombstones of removed records older than that, in batches of 1,000 short transactions. Refuses less than one hour.