---
title: "Command Reference"
sidebarTitle: "Command Reference"
description: "Every Supermemory CLI command, subcommand, and flag."
icon: "list"
---

All commands below assume you've [authenticated](/cli/overview#authenticate). Use the bare `supermemory` form if installed globally, or prefix with `npx`. Every command accepts the [global flags](/cli/overview#global-flags) `--json`, `--tag`, and `--help`.

## Core memory operations

### `add` — Ingest content

Ingest text, files, or URLs and extract memories into a container tag.

```bash
# Add text
supermemory add "User prefers TypeScript over JavaScript"

# Add a file (PDF, markdown, text, etc.)
supermemory add ./meeting-notes.pdf --tag meetings

# Add a URL
supermemory add https://docs.example.com/api --tag docs

# Read from stdin
cat file.txt | supermemory add --stdin
echo "some content" | supermemory add --stdin --tag notes

# With metadata, title, and custom ID
supermemory add "Design doc v2" \
  --title "Design Doc" \
  --metadata '{"category": "engineering", "priority": "high"}' \
  --id custom-doc-id --tag project

# Batch mode (JSONL from stdin, one {"content": "...", "tag": "..."} per line)
cat batch.jsonl | supermemory add --batch
```

| Flag | Description |
|---|---|
| `--tag <string>` | Container tag |
| `--stdin` | Read content from stdin |
| `--title <string>` | Document title |
| `--metadata <json>` | JSON metadata object |
| `--id <string>` | Custom document ID |
| `--batch` | Batch mode, reads JSONL from stdin |

### `search` — Search memories

Semantic search across memories with filtering and reranking.

```bash
# Basic search
supermemory search "authentication patterns"

# Scoped to a tag, with a limit
supermemory search "auth" --tag api --limit 5

# Reranking and LLM query rewriting for better relevance
supermemory search "database migrations" --rerank
supermemory search "how do we handle auth" --rewrite

# Search modes
supermemory search "user prefs" --mode memories    # extracted memories only
supermemory search "user prefs" --mode hybrid      # memories + document chunks
supermemory search "user prefs" --mode documents   # full documents only

# Include specific fields and filter by metadata
supermemory search "api design" --include summary,chunks,memories
supermemory search "design" --filter '{"AND": [{"key": "category", "value": "engineering"}]}'

# Similarity threshold (0-1)
supermemory search "preferences" --threshold 0.5
```

| Flag | Description |
|---|---|
| `--tag <string>` | Filter by container tag |
| `--limit <number>` | Max results (default: 10) |
| `--threshold <number>` | Similarity threshold 0-1 (default: 0) |
| `--rerank` | Enable reranking for better relevance |
| `--rewrite` | Rewrite the query using an LLM |
| `--mode <string>` | `memories` \| `hybrid` \| `documents` (default: `memories`) |
| `--include <string>` | Fields: `summary`, `chunks`, `memories`, `document` |
| `--filter <json>` | Metadata filter object |

### `remember` — Store a memory directly

Store a specific fact without ingesting a full document.

```bash
supermemory remember "User prefers dark mode" --tag user_123

# Permanent / static memory (won't decay)
supermemory remember "User is a senior engineer at Acme Corp" --static --tag user_123

# With metadata
supermemory remember "Discussed Q3 roadmap" --tag meetings --metadata '{"type": "decision"}'
```

| Flag | Description |
|---|---|
| `--tag <string>` | Container tag |
| `--static` | Mark as a permanent memory |
| `--metadata <json>` | JSON metadata |

### `forget` — Delete a memory

```bash
supermemory forget mem_abc123 --tag default
supermemory forget --content "outdated preference" --tag default
supermemory forget mem_abc123 --reason "User corrected this information"
```

| Flag | Description |
|---|---|
| `--tag <string>` | Container tag |
| `--reason <string>` | Reason for forgetting |
| `--content <string>` | Forget by content match instead of ID |

### `update` — Update an existing memory

```bash
supermemory update mem_123 "Updated preference: prefers Bun over Node"
supermemory update mem_123 "New content" --metadata '{"updated": true}'
```

| Flag | Description |
|---|---|
| `--tag <string>` | Container tag |
| `--metadata <json>` | Updated metadata |
| `--reason <string>` | Reason for the update |

### `profile` — Get a user profile

Retrieve the auto-generated user profile (static facts + dynamic context) for a container tag.

```bash
supermemory profile                                   # default tag
supermemory profile user_123                          # specific tag
supermemory profile user_123 --query "programming preferences"
```

## Document management

### `docs` — Manage documents

```bash
supermemory docs list --tag default --limit 20
supermemory docs get doc_abc123
supermemory docs status doc_abc123       # processing status
supermemory docs chunks doc_abc123       # view chunks
supermemory docs delete doc_abc123 --yes
```

**Subcommands:** `list`, `get`, `delete`, `chunks`, `status`

## Container tags

### `tags` — Manage container tags

Container tags scope memories to users, projects, or any logical grouping.

```bash
supermemory tags list
supermemory tags info user_123                                 # counts and metadata
supermemory tags create my-new-project
supermemory tags context user_123 --set "This user is a premium customer"
supermemory tags context user_123 --clear
supermemory tags merge old-tag --into new-tag --yes
supermemory tags delete old-tag --yes
```

**Subcommands:** `list`, `info`, `create`, `delete`, `context`, `merge`

## API keys

### `keys` — Manage API keys

```bash
supermemory keys list
supermemory keys create --name my-agent --permission write
supermemory keys create --name bot-key --tag user_123 --expires 30   # scoped + expiring
supermemory keys revoke key_abc123 --yes
supermemory keys toggle key_abc123                                    # enable/disable
```

**Subcommands:** `list`, `create`, `revoke`, `toggle`

## Connectors

### `connectors` — External data sources

Connect Google Drive, Notion, OneDrive, and other services to sync documents automatically.

```bash
supermemory connectors list
supermemory connectors connect google-drive --tag docs   # opens OAuth flow
supermemory connectors sync conn_abc123
supermemory connectors history conn_abc123 --limit 10
supermemory connectors resources conn_abc123
supermemory connectors disconnect conn_abc123 --yes
```

**Subcommands:** `list`, `connect`, `sync`, `history`, `disconnect`, `resources`

## Plugins

### `plugins` — IDE and tool integrations

Connect the CLI to Claude Code, Cursor, and other tools.

```bash
supermemory plugins list
supermemory plugins connect claude-code --auto-configure
supermemory plugins status claude-code
supermemory plugins revoke claude-code --yes
```

**Subcommands:** `list`, `connect`, `revoke`, `status`

## Team management

### `team` — Manage team members

```bash
supermemory team list
supermemory team invite user@example.com --role admin
supermemory team role member_123 admin
supermemory team remove member_123 --yes
supermemory team invitations
```

**Subcommands:** `list`, `invite`, `remove`, `role`, `invitations`

## Monitoring

### `status` — Account dashboard

```bash
supermemory status
supermemory status --period 7d    # 24h, 7d, 30d, all
```

Shows memory count, document count, API usage, and storage.

### `logs` — Request logs

```bash
supermemory logs
supermemory logs --period 7d
supermemory logs --status error
supermemory logs --type search
supermemory logs get req_abc123
```

### `billing` — Usage and billing

```bash
supermemory billing            # overview
supermemory billing usage      # detailed breakdown
supermemory billing invoices   # past invoices
```

## Utility

```bash
# Open the console in your browser
supermemory open
supermemory open graph     # also: billing, settings, docs, keys

# Machine-readable help (useful for LLM agents)
supermemory help --json
supermemory help --all

# Per-command help
supermemory search --help
supermemory tags --help --json
```

## Scoped keys mode

When you authenticate with a scoped API key (restricted to a single container tag), only these commands are available, and the tag is taken automatically from the key's scope — no `--tag` needed:

`search`, `add`, `remember`, `forget`, `update`, `profile`, `whoami`

## Common patterns

### Pipe content from other tools

```bash
git log --oneline -20 | supermemory add --stdin --tag git-history
curl -s https://api.example.com/docs | supermemory add --stdin --tag api-docs
supermemory search "auth" --json | jq '.results[].memory'
```

### Scripting with JSON output

Every command supports `--json` for machine-readable output:

```bash
supermemory search "query" --json
supermemory tags list --json
supermemory status --json | jq '.memoryCount'
```

### CI/CD integration

```bash
export SUPERMEMORY_API_KEY=sm_xxx

# Ingest docs on deploy, replacing the previous version by ID
supermemory add ./docs/api-reference.md --tag api-docs --id api-ref-latest

# Gate on status
supermemory status --json | jq '.memoryCount'
```