---
title: CLI
description: Install the memoria CLI to wire up Claude Code in one line — including Claude Code on the web. Handles install, auth, and MCP config, and teaches the agent the mental model.
order: 3
---

# CLI

The `memoria` CLI is a single binary that handles **install + auth + MCP config** in one step. Run it once per machine (or once per cloud environment) and every Claude Code session can call Memoria's tools — and already understands what brains, episodes, entities, edges, and playbooks are, because `memoria init` also installs a Claude Code skill that teaches the agent.

It's open source at [github.com/premex-ab/memoria-cli](https://github.com/premex-ab/memoria-cli).

> Prefer the browser OAuth flow on your laptop? You don't need the CLI for that — see [MCP server](/docs/mcp). The CLI shines for API-key and **cloud** setups, like Claude Code on the web (see below).

## Install

```bash
curl -fsSL https://api.memoria.premex.se/install.sh | sh
```

This downloads the right binary for your OS and architecture (macOS and Linux, `arm64` and `amd64`) to `~/.local/bin/memoria`. Make sure `~/.local/bin` is on your `PATH`.

## Connect

Mint a `mem_live_*` key in the dashboard under **Brains → your brain → Keys**, then:

```bash
memoria init mem_live_…
```

`init` validates the key, prints which brain it's bound to, stores the token, writes the `memoria` MCP entry into `~/.claude.json`, and installs the skill into `~/.claude/skills/memoria/`. Open a Claude Code session and try `recall("hello world")` to confirm.

The token never lands in `~/.claude.json`. The MCP entry references a helper command (`memoria headers`) that resolves the `Authorization` header at connection time:

```json
{
  "mcpServers": {
    "memoria": {
      "type": "http",
      "url": "https://api.memoria.premex.se/mcp",
      "headersHelper": "memoria headers"
    }
  }
}
```

`init` stores the token in your OS keychain on macOS, or in `~/.config/memoria/credentials` (mode `600`) otherwise. When a key rotates, re-run `memoria init <new-key>` — everything downstream keeps working.

## Claude Code on the web

[Claude Code on the web](https://code.claude.com/docs/en/claude-code-on-the-web) runs each session in an isolated, ephemeral cloud container — no persistent keychain, no browser for an interactive OAuth flow. The CLI's **env-var mode** fits perfectly: provide the API key through the environment's configuration, and a short setup script installs the CLI, wires the MCP server, and installs the skill on every fresh container. No committed config file, no secret in your repo.

**1. Add your API key to the environment's variables.** In the environment configuration, set:

```
MEMORIA_API_KEY=mem_live_…
```

Bind the key to the brain you want web sessions to read and write — typically a per-project brain.

**2. Set the environment's setup script to:**

```bash
#!/bin/bash
set -e
curl -fsSL https://api.memoria.premex.se/install.sh | sh
memoria init "$MEMORIA_API_KEY"
```

On each fresh container this installs the binary, then runs `init`, which sees `MEMORIA_API_KEY` in the environment and enters **env-var mode**: it validates the key, writes the MCP entry, and installs the skill — but never writes the token to disk. `memoria headers` reads the key straight from the environment at connect time.

**3. Allow the right hosts in the network policy.** Web environments enforce an outbound [network policy](https://code.claude.com/docs/en/claude-code-on-the-web). The setup and runtime need to reach:

- `github.com` and `objects.githubusercontent.com` — the installer downloads the binary from GitHub Releases.
- `api.memoria.premex.se` — the install redirect, key validation, and the `/mcp` endpoint.

Pick a policy that permits those, or allowlist them — otherwise the setup script can't fetch the binary.

That's it. The first session comes up with the Memoria tools available and the `memoria` skill auto-loaded, so the agent already knows the mental model, the bi-temporal "two clocks", brain isolation, and what each tool costs.

## Command reference

| Command | What it does |
|---------|--------------|
| `memoria init <token>` | Validate the key, store it, write the MCP entry, install the skill. |
| `memoria init --token-env MEMORIA_API_KEY` | Same, reading the token from an env var — env-var mode, for cloud and CI. |
| `memoria headers` | Internal. Resolves the `Authorization` header for the MCP server at connect time (env → keychain → file). |
| `memoria status` | Show the bound brain, where the token is stored, and whether the MCP entry and skill are in place. |
| `memoria update` | Self-update to the latest release. |
| `memoria mcp print` | Print the MCP JSON entry without writing anything. |
| `memoria --version` / `--help` | Standard. |

## Troubleshooting

- **`claude mcp list` doesn't show memoria.** Run `memoria status` to confirm the MCP entry is present. Current Claude Code versions ignore `~/.claude/settings.json` for MCP config — user-scope servers live in `~/.claude.json`, which `memoria init` writes for you.
- **Tools fail to connect in a web session.** Almost always the network policy or a missing/mistyped `MEMORIA_API_KEY`. Run `memoria status` in the session — it reports whether the token resolved and which brain it's bound to.
- **`init` exits with a 401.** The key is invalid, revoked, or for a brain that no longer exists. Mint a fresh one from the dashboard.

## See also

- [MCP server](/docs/mcp) — the tool catalog and the browser OAuth flow.
- [Brains](/docs/brains) — how keys and tokens bind to an isolated workspace.
- [Quickstart](/docs/quickstart) — store and recall your first memory.