# CLI reference

<!-- Canonical: https://www.atlaso.ai/docs/cli -->

`atlaso` is a CLI as much as a library. Every subcommand mirrors a `Memory()` method and an MCP tool, so you can debug the same field three ways. Every data subcommand accepts `--json` for machine-readable output.

## Health & sanity

### `atlaso version`

```bash
atlaso version
```

Prints the installed SDK version.

### `atlaso check`

```bash
atlaso check
```

One-line import check — confirms `atlaso` and (if installed) `atlaso[mcp]` resolve.

### `atlaso doctor`

```bash
atlaso doctor
```

End-to-end install diagnostic. Checks import, vendored engine, resolved storage path, and runs an `add` → `recall` → `retract` round-trip in a tempdir. Returns `0` on success.

## Data operations

`--user` is the authenticated identity — never a value from a request body.

### `atlaso add`

```bash
atlaso add "Alice prefers oat milk" --user alice --tag preference
atlaso add "0.7 over-flags in prod" --user alice \
  --polarity negative --evidence observed \
  --scope-note "model=gpt-5; env=prod"
```

- `--polarity` `positive | negative | cautionary | open` — default `open`.
- `--evidence` `anecdotal | observed | replicated | verified` — default `anecdotal`.
- `--scope-note STR`, `--tag T` (repeatable).

### `atlaso recall`

```bash
atlaso recall "threshold" --user alice --limit 10 --explain
```

Prints a verdict line then one row per hit, prefixed with `⚠` for disagreement, `✓` for confident, `·` otherwise.

### `atlaso get`

```bash
atlaso get 7e3a1b2c --user alice
```

Fetch one deposit by id. Exit 1 if not found.

### `atlaso list-recent`

```bash
atlaso list-recent --user alice --limit 50 --offset 0
```

### `atlaso peek`

```bash
atlaso peek alice --limit 10
```

`user_id` is **positional** on `peek` and `health`.

### `atlaso health`

```bash
atlaso health alice --window 30
```

### `atlaso contradict`

```bash
atlaso contradict "Alice now prefers soy milk" 7e3a1b2c 9c0f1d2a \
  --user alice --reason "Apr-23 conversation update"
```

Multiple deposit IDs accepted — all marked superseded by the new deposit atomically. `--reason` is **required**.

### `atlaso retract`

```bash
# soft (default)
atlaso retract 7e3a1b2c --user alice --reason "user request"

# hard — irreversible, removes the row and clears FTS index
atlaso retract 7e3a1b2c --user alice --reason "GDPR erasure" --hard
```

`--reason` is required. `--hard` is irreversible — use only for legal erasure.

## Operational

### `atlaso mcp`

```bash
atlaso mcp
```

Starts the FastMCP stdio server. Requires `pip install "atlaso[mcp]"`. See [MCP & Hooks](./mcp-and-hooks.md).

### `atlaso install-hooks`

```bash
atlaso install-hooks --scope user
atlaso install-hooks --scope project --project-dir .
```

Writes `~/.atlaso/hooks/atlaso_recall_hook.sh` and `atlaso_deposit_hook.sh`, then merges `UserPromptSubmit` + `Stop` entries into Claude Code's `settings.json` (user or project scope). Idempotent on rerun.

### `atlaso uninstall-hooks`

```bash
atlaso uninstall-hooks --scope user
```

Removes only the atlaso hook entries from `settings.json`. Leaves the scripts at `~/.atlaso/hooks/` — delete manually if you want a clean removal.

### `atlaso demo`

```bash
atlaso demo
```

Runs the narrated end-to-end demo. Requires a source checkout (looks for `demo.py`).

---

<!-- atlaso:doc-trailer -->
**Source:** <https://www.atlaso.ai/docs/cli>  
**Edit on GitHub:** <https://github.com/imashishkh21/atlaso/tree/main/docs/cli.md>  
**Updated:** 2026-05-12