Command Reference

Atomic provides a focused set of commands for managing repositories, recording changes, collaborating with remotes, and integrating with AI coding agents.

Every command listed here corresponds to a real subcommand in the atomic CLI binary. Run atomic <command> --help for full usage details.

Quick Reference

Command	Description
init	Initialize a new Atomic repository
status	Show working copy status
conflicts	List files in a conflicted state
add	Add files to be tracked
remove	Remove files from tracking
move	Move or rename tracked files
record	Record changes from the working copy
revise	Revise a change in-place
diff	Show differences in the working copy
blame	Show line-level ownership for a tracked text file
log	Show change history
change	Inspect a specific change
op	Inspect the immutable repository operation journal
compact	Reclaim unused space in the repository database
insert	Insert changes into a view
restore	Restore working copy to last recorded state
stage	Stage worktree content into the Git index (colocated mode)
unstage	Move Git index entries back to the baseline (colocated mode)
split	Create a new view from an existing one
view	Manage views (create, switch, list, delete)
stash	Temporarily save uncommitted changes
tag	Manage tags (create, list, show, delete)
push	Push changes to a remote
pull	Pull changes from a remote
clone	Clone a remote repository
remote	Manage named remote repositories
server	Manage server profiles (staging, production, etc.)
repo	Inspect local repository identity and metadata (no dedicated page yet)
org	Manage Atomic Storage organizations and members
workspace	Manage hosted workspaces [alias: ws]
project	Manage hosted projects and project remotes [alias: proj]
team	Manage organization teams and team members
identity	Manage user identities and signing keys
agent	Manage AI agent integration
doctor	Verify working-copy consistency and repair indexes
diagnostics	Print a read-only support report (no dedicated page yet)
git	Git interoperability (import, push, hooks)
git shim	Colocated Git shim (reconcile, verify, publish, bindings)
sandbox	Provision concurrent agent sandboxes (copy-on-write working trees)
session	Inspect the agent session ledger
query	Query the knowledge graph
vault	Manage the vault (shared project knowledge store)
intent	Record the "why": validate, attest, and verify intents
memory	Record durable memories: validate, attest, and verify
provenance	W3C PROV projections for changes
unrecord	Remove the last change from the current view
update	Check for available CLI updates
triage	Review a feature view's candidate changes against a target
completions	Generate a shell completion script

Command Categories

Working with Changes

The core workflow — track files, record changes, review diffs:

atomic add src/main.rs           # Track a file
atomic status                     # See what changed
atomic diff                       # Review the diff
atomic record -m "Add main"       # Record a change
atomic log                        # View history

• add — Add files to be tracked
• remove / rm — Remove files from tracking
• move / mv — Move or rename tracked files
• status — Show modified, added, deleted, and untracked files
• conflicts — List files in a conflicted state on the current view
• diff — Show differences between working copy and last recorded state
• blame — Show line-level ownership for a tracked text file
• record — Create a new change from tracked file modifications
• revise — Modify a previously recorded change in-place
• unrecord — Remove the last change (or a specific change) from the current view
• log — Display the history of changes on the current view
• change — Inspect details of a specific change by hash or sequence number
• op — Inspect the immutable repository operation journal (op log/show/undo/restore)
• compact — Reclaim unused space in the repository database

Repository Management

Create, clone, and restore repositories:

atomic init myproject             # Create a new repo
atomic clone https://...          # Clone from remote
atomic restore --force            # Discard uncommitted changes

• init — Initialize a new Atomic repository
• clone — Clone an existing repository from a remote
• restore — Restore the working copy to the last recorded state
• split — Create a new view from an existing one
• git — Import Git repositories into Atomic and sync back to Git
• git shim — Colocated Git shim: reconcile, verify, switch, publish, and bind Git HEAD ↔ Atomic view state (0.20.0+)
• stage / unstage — Project the Git index from Atomic state in colocated mode

Knowledge Graph & Vault

Search the knowledge graph and manage the shared project knowledge store:

atomic query search "authentication"   # Keyword search over the graph
atomic query code "issue_token" -t rs  # Search source content
atomic vault context --intent PIMO-1   # Memories relevant to a task

• query — Search the knowledge graph (keywords, neighbors, code, RAG)
• vault — Manage the shared knowledge store (memories, intents, goals)
• provenance — Project and sign W3C PROV for a change

Views

Views are Atomic's equivalent of branches — but they're filtered perspectives on the same graph, not forks:

atomic view create feature-auth   # Create a view
atomic view switch feature-auth   # Switch to it
atomic view list                  # List all views
atomic view delete old-feature    # Delete a view

• view — Create, switch, list, and delete views
• stash — Temporarily save uncommitted changes to an orphan view
• triage — Project a feature view's candidate change set against a target for review

Remote Operations and Atomic Storage

Synchronize with remote repositories and manage hosted organizations, workspaces, projects, and teams:

atomic identity new alice-acme --email alice@acme.com --set-default
atomic identity register https://atomic.storage
atomic org create acme --email team@acme.com
atomic workspace create platform --visibility private --org acme
atomic project create api --workspace platform --kind rust --org acme
atomic team create engineering --visibility visible --org acme

atomic project init api --workspace platform --kind rust --org acme
atomic push                       # Push changes to default remote
atomic pull                       # Pull changes from default remote

• org — Create organizations and manage members
• workspace — Create, list, update, and delete hosted workspaces
• project — Create hosted projects and configure local remotes
• team — Create teams and manage team members
• push — Upload local changes to a remote
• pull — Download and insert changes from a remote
• clone — Create a new local repository from a remote
• remote — Add, remove, list, and configure named remotes
• server — Manage server profiles (staging, production, etc.)

Tags

Named state snapshots for marking releases and sync points:

atomic tag create v1.0.0 -m "Release 1.0"
atomic tag list
atomic tag show v1.0.0

• tag — Create, list, show, and delete tags

Identity

Manage user identities for signing changes and Atomic Storage authentication:

atomic identity new alice-acme --email alice@acme.com --set-default
atomic identity register https://atomic.storage
atomic identity list
atomic identity whoami

• identity — Create, list, show, register, and delete identities

AI Agent Integration

Turn-level recording for AI coding agents with full provenance:

atomic agent enable --agent claude-code
atomic agent status --verbose
atomic agent explain <session-id> --all --save

• agent — Enable, disable, and manage AI agent hooks for all supported agents (see the integration matrix)
• agent lifecycle — Declare and track managed runs for orchestrated agents
• agent identity — Select or inspect the agent identity that recording hooks sign as
• agent repair — Resume a managed session under leases while retaining durable evidence
• session — Inspect, fork, and rebuild the agent session ledger
• sandbox — Provision concurrent agent sandboxes and OCI images

Diagnostics

Inspect and verify repository state:

atomic conflicts                  # List files in a conflicted state
atomic doctor check               # Verify the working copy matches the graph

• conflicts — List conflicted files, with the kind and line of each conflict
• doctor — Verify working-copy consistency (materialization drift + conflict honesty) and repair derived indexes
• diagnostics — Print a read-only support report for issue triage
• update — Check for available CLI updates and print the upgrade path

Global Options

These flags are available on every command:

Flag	Description
-v, --verbose	Enable verbose output for debugging
--no-color	Disable colored output (useful for piping)
-V, --version	Print version information
-h, --help	Display help for a command

Basic Workflow

# 1. Initialize
atomic init myproject
cd myproject

# 2. Create and track files
echo 'fn main() {}' > src/main.rs
atomic add src/main.rs

# 3. Record
atomic record -m "Initial commit"

# 4. Create a view for a feature
atomic view create feature-auth --switch

# 5. Make changes, record, review
atomic status
atomic diff
atomic record -m "Add authentication module"

# 6. Push to remote
atomic remote add origin https://api.atomic.dev/acme/project/code
atomic push

AI-Assisted Workflow

# 1. Enable agent hooks
atomic agent enable --agent claude-code

# 2. Work with your AI agent — turns are recorded automatically

# 3. Review what happened
atomic log
atomic agent status --verbose

# 4. Generate reasoning summaries
atomic agent explain <session-id> --all --save

# 5. Push everything (changes + provenance + session data)
atomic push

Getting Help

# Top-level help
atomic --help

# Help for a specific command
atomic record --help
atomic view --help
atomic agent enable --help