Skip to content

Latest commit

 

History

History
293 lines (231 loc) · 12.1 KB

overview.md

File metadata and controls

293 lines (231 loc) · 12.1 KB
sidebar_position 1
title Commands Overview

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