mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-09-06 08:16:03 +00:00
d62d9cc5ac
Document the Supermemory CLI (npx supermemory) — previously undocumented. Adds a "Command Line (CLI)" group under the Developer Platform tab: - cli/overview: install, auth, config scopes, the cloud-CLI vs local-server split - cli/commands: full command/flag reference (add, search, tags, keys, etc.) - cli/local: npx supermemory local, cross-linked to self-hosting docs Also moves SMFS from a standalone top-level anchor into a group inside the main Developer Platform anchor so it's embedded rather than feeling detached. Page URLs are unchanged, so no redirects are needed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
318 lines
8.9 KiB
Text
318 lines
8.9 KiB
Text
---
|
|
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'
|
|
```
|