> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anonalabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Anona CLI

> The anona command line: record, retrieve and reason over memories, manage spaces, documents, jobs and settings, and connect MCP clients, from a terminal, a script or an agent harness.

`anona` is the command line for Anona Memory. It does three jobs:

* **Use memory from a shell.** `anona record`, `anona retrieve` and
  `anona reason` are the same three calls as the API, with `--json` output and
  stable exit codes, so a script, a CI job or an agent without MCP can use
  memory directly.
* **Manage what is stored.** Spaces, memories, uploaded documents, background
  jobs and per-space settings, each one command.
* **Connect an MCP client with no API key.** `anona login` signs you in once in
  a browser, and `anona mcp` is the stdio server your client launches.

```bash theme={null}
pip install -U anona
anona login
anona record "Deploys run Tuesdays at 10:00 UTC." --space ops
anona retrieve "when do we deploy" --space ops
```

## CLI, MCP or SDK

| You are | Use |
| - | - |
| An agent in a client that supports MCP (Claude Code, Cursor, Codex, Hermes, OpenClaw) | [MCP](https://docs.anonalabs.com/mcp-integration.md). The tools are already authenticated and need no shell. |
| An agent with a shell and no MCP, or a harness where MCP is not configured | The CLI, with `--json`. See [For AI agents](https://docs.anonalabs.com/cli/agents.md). |
| A script, a cron job or a CI step | The CLI, with `--json` and the [exit codes](https://docs.anonalabs.com/cli/scripting.md#exit-codes). |
| Bulk work: uploading a folder of files, ingesting a JSON Lines export | The CLI: [`documents upload`](https://docs.anonalabs.com/cli/documents) and [`record --batch`](https://docs.anonalabs.com/cli/memory#batch-ingest). |
| Application code | The [Python](https://docs.anonalabs.com/sdk/python.md) or [JavaScript](https://docs.anonalabs.com/sdk/javascript.md) SDK, with an API key. |

The CLI is a thin wrapper over the [REST API](https://docs.anonalabs.com/api-reference/overview.md): every
data command is one API call (or a short sequence, such as polling a job), and
a flag you do not give is left out of the request rather than sent as a
default.

## Install

```bash theme={null}
pip install -U anona
```

The `-U` matters. `pip install anona` over an existing copy reports success and
**leaves the old version in place**, so a machine that installed the CLI before
a command existed keeps a binary without it, and the command then fails with
`invalid choice: '<command>'`, which reads like it was never real.
`anona --help` lists what your copy actually has, and `anona --version` prints
its version.

If pip answers `error: externally-managed-environment`, it is refusing to write
to a system Python, which Debian, Ubuntu and Homebrew all do by default. Use
either of these instead:

```bash theme={null}
uvx --from anona anona start        # nothing installed, always the current version
pipx install anona                  # or an isolated install on your PATH
```

pip also suggests `--break-system-packages`, and it does work
(`pip install -U --break-system-packages anona`). It writes into the Python
your OS maintains, so prefer either command above when you have the choice.

If you have Node and no Python, the JavaScript package also installs a binary
called `anona`, with no runtime dependencies:

```bash theme={null}
npm install -g @anona-labs/memory   # then: anona login
npx @anona-labs/memory login        # or, with nothing installed
```

> [!NOTE]
>
> **Both packages install a binary called `anona`.** With both installed you get
> whichever comes first on your `PATH`. That is harmless: they share
> `~/.anona/credentials.json` (MCP) and `~/.anona/cli-credentials.json` (the
> command line), and the same locks, so a profile started with one can be
> claimed with the other, and a Python and a Node `anona mcp` refreshing at the
> same instant take turns rather than both spending the refresh token. A client
> configured with `anona mcp` keeps working if you uninstall one package only if
> the other is still on `PATH`.

## First run

pip 0.25.0; npm 0.19.0

`anona` on its own, with no arguments, prints where to start and exits `0`:
how to get a credential (`anona start`, `anona login`, `anona status`), the
three memory commands, and `anona guide` as the full reference. It reads no
credential and sends nothing. `anona --help` ends with the same pointer to
`anona guide`.

```bash theme={null}
anona          # where to start
anona guide    # every command, flag, exit code and recipe
```

Only the empty command line does this. A global option with no command after
it, such as `anona --quiet`, is still a usage error (exit `2`), since a script
wrote it. Older copies answer a bare `anona` with
`the following arguments are required: command` and exit `2`.

## What each package has

The pip package is the reference implementation. The npm package is being
brought to parity with it; until then, check this table before you rely on a
command from `npx @anona-labs/memory`.

| Command | pip `anona` | npm `@anona-labs/memory` |
| - | - | - |
| `start`, `login`, `logout`, `status`, `mcp` | yes | yes |
| `record`, `retrieve`, `reason` (the flags in pip 0.24.0) | yes | 0.19.0 |
| `spaces list` / `create` / `get`, `memories`, `jobs`, `profile`, `model`, `user-profile`, `usage` | yes | 0.19.0 |
| `record --async` / `--batch` / `--wait` | 0.25.0 | 0.19.0 |
| `retrieve --tag-groups`, `--member-id`, `--no-prefer-observations`, `--format block` | 0.25.0 | 0.19.0 |
| `spaces delete`, `documents`, `chat-settings`, `reason-settings`, `extraction-settings`, `llm-models` | 0.25.0 | 0.19.0 |
| `doctor`, `guide`, `help`, `completion` | 0.25.0 | 0.19.0 |
| `--profile`, `--timeout`, `--retries`, `--quiet` | 0.25.0 | 0.19.0 |
| Exit codes `5`-`8` | 0.25.0 | 0.19.0 (`1` before) |

A version in the table is the first release of that package with the
command. The command pages mark each command the same way.
`anona --help` on your own copy is the final word.

## Where things are stored

Everything the CLI keeps is under `~/.anona/` (or
`~/.anona/profiles/NAME/` for a [named profile](https://docs.anonalabs.com/cli/sign-in.md#named-profiles)):

| File | Holds | Written by |
| - | - | - |
| `cli-credentials.json` | the command-line login | `anona login` (or `login --cli`) |
| `credentials.json` | the MCP login, and a temporary profile | `anona login` (or `login --mcp`), `anona start` |
| `config.env` | `ANONA_API_KEY`, `ANONA_SPACE_ID`, `ANONA_BASE_URL` | you, or the [agent skills installer](https://docs.anonalabs.com/integrations/skills.md) |

All three are mode 600. No command prints a whole key or token.

## Next

> **[Sign in & credentials](https://docs.anonalabs.com/cli/sign-in.md)**
>
> API key, `anona login`, temporary profiles, and which one wins.

> **[Record, retrieve, reason](https://docs.anonalabs.com/cli/memory.md)**
>
> The three memory calls and every flag they take.

> **[Scripting & automation](https://docs.anonalabs.com/cli/scripting.md)**
>
> `--json`, exit codes, retries, waiting on jobs, batch files.

> **[For AI agents](https://docs.anonalabs.com/cli/agents.md)**
>
> `anona guide`, the `anona-cli` skill, and when to use MCP instead.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.