CLI guide

The CLI is the default interface for Aictx. It is the quickest path for setup, routine memory work, inspection, recovery, export, documentation, and the local viewer.

Most days, an agent only needs:

aictx load "task summary"
aictx save --stdin
aictx diff

The rest of the CLI is there for setup, review, recovery, and maintenance.

Quick checks

aictx check
aictx diff
aictx view --open

• check validates canonical memory and generated index health.
• diff shows memory changes, including untracked files in Git projects.
• view --open starts the local read-only browser viewer.

Setup and bootstrap

aictx init
aictx setup
aictx setup --apply
aictx patch review bootstrap-memory.json

• init creates .aictx/ and optional repo-level agent guidance.
• setup guides first-run onboarding and bootstrap memory preview.
• setup --apply applies the conservative bootstrap memory patch immediately.
• patch review reviews a structured memory patch without writing it.

Tip

If memory is empty after init, use aictx setup before hand-writing memory. The bootstrap flow is designed for exactly that first-run gap.

Routine memory work

aictx load "change auth routes"
aictx search "auth route conventions"
aictx inspect decision.auth-route-conventions
aictx suggest --after-task "change auth routes" --json
aictx audit --json
aictx save --stdin

The routine loop is narrow load, work, and save only durable knowledge as active memory. A task that produced no reusable project knowledge does not need a save.

Commands that support structured output accept --json:

aictx check --json

Inspection and debugging

aictx stale
aictx graph <id>

stale lists stale and superseded memory. graph shows a one-hop relation neighborhood for debugging retrieval and provenance.

Maintenance

aictx check
aictx rebuild
aictx upgrade
aictx reset
aictx reset --all

rebuild regenerates indexes from canonical memory. reset backs up and clears local .aictx/ storage. reset --all resets every project in the user-level registry; add --destroy only when you intend to delete each registered .aictx/ without backup.

Git inspection and recovery

aictx diff
aictx history
aictx restore <commit>
aictx rewind

Aictx writes local files and never commits automatically. Git remains the source of truth for history and rollback when the project is inside a Git worktree.

Export, viewer, and docs

aictx export obsidian
aictx projects list
aictx view --open
aictx docs
aictx docs getting-started
aictx docs demand-driven-memory
aictx docs agent-integration --open

aictx view starts a local, read-only memory viewer. aictx docs lists bundled public docs topics. aictx docs <topic> prints bundled Markdown for that topic. --open opens the hosted docs site.

CLI and MCP

MCP is available when the agent client has launched and connected to aictx-mcp.

MCP exposes exactly load_memory, search_memory, inspect_memory, save_memory_patch, and diff_memory. Setup, maintenance, recovery, export, registry, viewer, docs, suggest, audit, stale, and graph workflows are CLI-only in v1. These CLI-only commands are part of the v1 integration model rather than MCP parity gaps.

Local MCP is the near-term integration path for local agent harnesses. Remote MCP, hosted sync, cloud auth, cloud hosting, and ChatGPT App SDK UI are future work. Future ChatGPT-compatible search/fetch names are adapter aliases over search and inspect behavior, not local MCP tool names.