mem0/docs/platform/cli.mdx

---
title: CLI
description: "Manage memories from your terminal. Available for Python and Node.js."
icon: "terminal"
iconType: "solid"
---

The mem0 CLI lets you add, search, list, update, and delete memories directly from the terminal. It works with the Mem0 Platform API and is available as both a Python package and an npm package.

Both implementations provide identical behavior — same commands, same options, same output formats.

## Installation

<CodeGroup>
```bash pip
pip install mem0-cli
```

```bash npm
npm install -g @mem0/cli
```
</CodeGroup>

## Authentication

Run the interactive setup wizard to configure your API key:

```bash
mem0 init
```

This prompts for your API key and a default user ID, validates the connection, and saves the configuration locally.

For CI/CD or non-interactive environments, pass both values as flags:

```bash
mem0 init --api-key m0-xxx --user-id alice
```

You can also set your API key via environment variable:

```bash
export MEM0_API_KEY="m0-xxx"
```

## Quick start

```bash
# Add a memory
mem0 add "I prefer dark mode and use vim keybindings" --user-id alice

# Search memories
mem0 search "What are Alice's preferences?" --user-id alice

# List all memories for a user
mem0 list --user-id alice

# Get a specific memory
mem0 get <memory-id>

# Update a memory
mem0 update <memory-id> "I prefer light mode now"

# Delete a memory
mem0 delete <memory-id>
```

## Commands

### `mem0 init`

Interactive setup wizard. Prompts for your API key and default user ID.

```bash
mem0 init
mem0 init --api-key m0-xxx --user-id alice
```

### `mem0 add`

Add a memory from text, a JSON messages array, a file, or stdin.

```bash
mem0 add "I prefer dark mode" --user-id alice
mem0 add --file conversation.json --user-id alice
echo "Loves hiking on weekends" | mem0 add --user-id alice
```

| Flag | Description |
|------|-------------|
| `-u, --user-id` | Scope to a user |
| `--agent-id` | Scope to an agent |
| `--messages` | Conversation messages as JSON |
| `-f, --file` | Read messages from a JSON file |
| `-m, --metadata` | Custom metadata as JSON |
| `--categories` | Categories (JSON array or comma-separated) |
| `--graph / --no-graph` | Enable or disable graph memory extraction |
| `-o, --output` | Output format: `text`, `json`, `quiet` |

### `mem0 search`

Search memories using natural language.

```bash
mem0 search "dietary restrictions" --user-id alice
mem0 search "preferred tools" --user-id alice --output json --top-k 5
```

| Flag | Description |
|------|-------------|
| `-u, --user-id` | Filter by user |
| `-k, --top-k` | Number of results (default: 10) |
| `--threshold` | Minimum similarity score (default: 0.3) |
| `--rerank` | Enable reranking |
| `--keyword` | Use keyword search instead of semantic |
| `--filter` | Advanced filter expression (JSON) |
| `--graph / --no-graph` | Enable or disable graph in search |
| `-o, --output` | Output format: `text`, `json`, `table` |

### `mem0 list`

List memories with optional filters and pagination.

```bash
mem0 list --user-id alice
mem0 list --user-id alice --category preferences --output json
mem0 list --user-id alice --after 2024-01-01 --page-size 50
```

| Flag | Description |
|------|-------------|
| `-u, --user-id` | Filter by user |
| `--page` | Page number (default: 1) |
| `--page-size` | Results per page (default: 100) |
| `--category` | Filter by category |
| `--after` | Created after date (YYYY-MM-DD) |
| `--before` | Created before date (YYYY-MM-DD) |
| `-o, --output` | Output format: `text`, `json`, `table` |

### `mem0 get`

Retrieve a specific memory by ID.

```bash
mem0 get 7b3c1a2e-4d5f-6789-abcd-ef0123456789
mem0 get 7b3c1a2e-4d5f-6789-abcd-ef0123456789 --output json
```

### `mem0 update`

Update the text or metadata of an existing memory.

```bash
mem0 update <memory-id> "Updated preference text"
mem0 update <memory-id> --metadata '{"priority": "high"}'
echo "new text" | mem0 update <memory-id>
```

### `mem0 delete`

Delete a single memory, all memories for a scope, or an entire entity.

```bash
# Delete a single memory
mem0 delete <memory-id>

# Delete all memories for a user
mem0 delete --all --user-id alice --force

# Delete all memories project-wide
mem0 delete --all --project --force

# Preview what would be deleted
mem0 delete --all --user-id alice --dry-run
```

| Flag | Description |
|------|-------------|
| `--all` | Delete all memories matching scope filters |
| `--entity` | Delete the entity and all its memories |
| `--project` | With `--all`: delete all memories project-wide |
| `--dry-run` | Preview without deleting |
| `--force` | Skip confirmation prompt |

### `mem0 import`

Bulk import memories from a JSON file.

```bash
mem0 import data.json --user-id alice
```

The file should be a JSON array where each item has a `memory` (or `text` or `content`) field and optional `user_id`, `agent_id`, and `metadata` fields.

### `mem0 config`

View or modify the local CLI configuration.

```bash
mem0 config show              # Display current config (secrets redacted)
mem0 config get api_key       # Get a specific value
mem0 config set user_id bob   # Set a value
```

### `mem0 entities`

List or delete entities (users, agents, apps).

```bash
mem0 entities list
mem0 entities list --type agent --output json
mem0 entities delete --user-id alice --force
```

### `mem0 status`

Verify your API connection and display the current project.

```bash
mem0 status
```

### `mem0 version`

Print the CLI version.

```bash
mem0 version
```

## Output formats

All commands support the `--output` flag to control how results are displayed:

| Format | Description |
|--------|-------------|
| `text` | Human-readable output with colors and formatting (default for most commands) |
| `json` | Structured JSON, suitable for piping to `jq` or consumption by AI agents |
| `table` | Tabular format (default for `list`) |
| `quiet` | Minimal output — just IDs or status codes |

Example with JSON output:

```bash
mem0 search "user preferences" --user-id alice --output json | jq '.data.results[].memory'
```

## Use with AI agents

The CLI is designed to be used by AI agents and automation tools. Two features make this straightforward:

- **`--output json`** returns structured data that agents can parse directly
- **`mem0 help --json`** returns the full command tree as JSON, so agents can discover available commands programmatically

```bash
# Agent adds a memory
mem0 add "User prefers concise responses" --user-id user-42 --output quiet

# Agent searches memories and parses results
mem0 search "response preferences" --user-id user-42 --output json
```

For non-interactive environments (CI, agent runtimes), use `mem0 init --api-key --user-id` or set the `MEM0_API_KEY` environment variable to skip interactive prompts.

## Environment variables

| Variable | Description |
|----------|-------------|
| `MEM0_API_KEY` | API key (overrides config file) |
| `MEM0_BASE_URL` | API base URL |
| `MEM0_USER_ID` | Default user ID |
| `MEM0_AGENT_ID` | Default agent ID |
| `MEM0_APP_ID` | Default app ID |
| `MEM0_RUN_ID` | Default run ID |
| `MEM0_ENABLE_GRAPH` | Enable graph memory (`true` / `false`) |

Environment variables take precedence over values in the config file, which take precedence over defaults.

## Global flags

These flags are available on all commands that interact with the API:

| Flag | Description |
|------|-------------|
| `--api-key` | Override the configured API key for this request |
| `--base-url` | Override the configured API base URL for this request |
| `-o, --output` | Set the output format |

## What's next

<CardGroup cols={3}>
<Card title="Quickstart" icon="bolt" href="/platform/quickstart">
Store your first memory in under five minutes using the SDK or CLI
</Card>

<Card title="Memory Operations" icon="database" href="/core-concepts/memory-operations/add">
Learn about add, search, update, and delete operations in depth
</Card>

<Card title="API Reference" icon="code" href="/api-reference/memory/add-memories">
See the complete REST API documentation
</Card>
</CardGroup>