Skip to main content
The AtomicMemory CLI (@atomicmemory/cli) is a human- and agent-friendly command-line tool for interacting with AtomicMemory memory workflows directly from your terminal or from automation scripts. It is a distinct package from @atomicmemory/mcp-server: the MCP server (atomicmemory-mcp) is a stdio protocol process designed to be launched by agent hosts, while the CLI (atomicmemory) is a conventional command-line program you run interactively or call from shell scripts and CI pipelines.

​
Installation

Install the CLI globally with npm, or run it on demand with npx without a global install: 
npm install -g @atomicmemory/cli

# Or run without installing:
npx @atomicmemory/cli
The binary name is atomicmemory. The CLI requires Node.js 18 or later.
Running atomicmemory with no arguments in an interactive terminal opens the built-in Ink UI. Use atomicmemory help for a plain text command reference, or pass --no-interactive to suppress the UI in scripts.

​
Initializing your config

After installing, run init to point the CLI at your AtomicMemory Core instance and set your default user scope: 
atomicmemory init --api-url http://127.0.0.1:17350 --user "$USER"
This writes ~/.atomicmemory/config.json. You can inspect or edit it at any time with atomicmemory config.
Pass --api-key-stdin instead of including your API key in the command to avoid writing it into shell history.

​
Command groups

The CLI surface is organized into four logical groups:

setup

Configure your installation. Commands: init, config, hooks, completion.

diagnose

Inspect connection health and validate your config. Commands: doctor, status, validate.

agent

Manage agent-facing resources. Commands: skill, help, version.

memory

Work with memories directly. Commands: add, ingest, search, package, list, get, delete, import.
Run atomicmemory help --json to get the full machine-readable command tree, which is useful for driving the CLI from automation.

​
Configuration and precedence

The CLI resolves settings in the following priority order — higher entries win:
  1. CLI flags passed at invocation time
  2. ATOMICMEMORY_* environment variables
  3. ~/.atomicmemory/config.json — the local config file written by init
  4. Command defaults built into the CLI
Every memory command requires an explicit scope user. The CLI will not invent one — supply it via --user, the ATOMICMEMORY_SCOPE_USER environment variable, or your config file. You can override provider and scope settings on any individual command: 
atomicmemory search "release policy" \
  --provider atomicmemory \
  --api-url http://127.0.0.1:17350 \
  --user "$USER" \
  --namespace my-project

​
Agent output mode

When calling the CLI from automation scripts or agent pipelines, pass --agent to receive stable, machine-parseable JSON envelopes instead of human-formatted output: 
atomicmemory --agent search "prior decisions"
A successful response looks like: 
{
  "status": "success",
  "command": "search",
  "duration_ms": 12,
  "profile": "default",
  "scope": { "user": "pip" },
  "count": 1,
  "data": {}
}
Errors in --agent mode are written to stdout (not stderr) and exit with a non-zero code, making them easy to detect in any scripting environment.
Always use --agent when calling atomicmemory from another program or CI step. The human-facing output format may change between versions; the JSON envelope is the stable contract.