The Supermemory CLI is the complete interface to Supermemory from the terminal. It lets you add memories, search, manage documents, configure projects, connect external data sources, and administer teams — all programmatically. Installation & Auth

Install globally

npm install -g @supermemory/cli

Authenticate (opens browser OAuth flow)

supermemory login

Or use an API key directly

supermemory login --api-key sm_abc_xxx

Check auth status

supermemory whoami Configuration The CLI supports three config scopes: Scope File Use Case project .supermemory/config.json (gitignored) Per-machine secrets, API keys team .supermemory/team.json (committed) Shared tag, team-wide defaults global ~/.config/supermemory/config.json All projects on this machine

Interactive setup wizard

supermemory init

Non-interactive

supermemory init --scope project --tag my-bot supermemory init --scope team --tag shared-project supermemory init --scope global --output json

View/set config values

supermemory config supermemory config set tag my-project supermemory config set verbose true supermemory config get tag Environment Variables Variable Description SUPERMEMORY_API_KEY API key for authentication SUPERMEMORY_TAG Override default container tag OTEL_EXPORTER_OTLP_ENDPOINT OpenTelemetry collector endpoint Global Flags Flag Description --json Force JSON output (machine-readable) --tag Override default container tag for this command --help Show help for any command Core Commands add — Ingest content Ingest text, files, or URLs and extract memories into a container tag.

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

supermemory add "Design doc v2" --metadata '{"category": "engineering", "priority": "high"}'

Custom document ID

supermemory add "My doc" --id custom-doc-id --tag project

Batch mode (JSONL from stdin, each line: {"content": "...", "tag": "..."})

cat batch.jsonl | supermemory add --batch Options: --tag — Container tag --stdin — Read content from stdin --title — Document title --metadata — JSON metadata object --id — Custom document ID --batch — Batch mode, reads JSONL from stdin search — Search memories Semantic search across memories with filtering and reranking.

Basic search

supermemory search "authentication patterns"

Scoped to a tag with limit

supermemory search "auth" --tag api --limit 5

With reranking for better relevance

supermemory search "database migrations" --rerank

Query rewriting (LLM rewrites query for better results)

supermemory search "how do we handle auth" --rewrite

Different 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

supermemory search "api design" --include summary,chunks,memories

Metadata filtering

supermemory search "design" --filter '{"AND": [{"key": "category", "value": "engineering"}]}'

Similarity threshold (0-1)

supermemory search "preferences" --threshold 0.5 Options: --tag — Filter by container tag --limit — Max results (default: 10) --threshold — Similarity threshold 0-1 (default: 0) --rerank — Enable reranking for better relevance --rewrite — Rewrite query using LLM --mode — memories | hybrid | documents (default: memories) --include — Fields: summary, chunks, memories, document --filter — Metadata filter object remember — Store a memory directly Store a specific fact or memory without ingesting a full document.

Store a memory

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

Mark as permanent/static (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"}' Options: --tag — Container tag --static — Mark as permanent memory --metadata — JSON metadata forget — Delete a memory

Forget by memory ID

supermemory forget mem_abc123 --tag default

Forget by content match

supermemory forget --content "outdated preference" --tag default

With reason

supermemory forget mem_abc123 --reason "User corrected this information" Options: --tag — Container tag --reason — Reason for forgetting --content — Forget by content match instead of ID update — Update an existing memory supermemory update mem_123 "Updated preference: prefers Bun over Node" supermemory update mem_123 "New content" --metadata '{"updated": true}' Options: --tag — Container tag --metadata — Updated metadata --reason — Reason for update profile — Get user profile Retrieve the auto-generated user profile for a container tag.

Get profile for default tag

supermemory profile

Get profile for specific tag

supermemory profile user_123

Search within the profile

supermemory profile user_123 --query "programming preferences" Returns static facts (long-term) and dynamic context (recent activity). Document Management docs — Manage documents

List documents

supermemory docs list --tag default --limit 20

Get a specific document

supermemory docs get doc_abc123

Check processing status

supermemory docs status doc_abc123

View document chunks

supermemory docs chunks doc_abc123

Delete a document

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.

List all tags

supermemory tags list

Get tag info (memory count, doc count, etc.)

supermemory tags info user_123

Create a new tag

supermemory tags create my-new-project

Set context on a tag (injected into profile responses)

supermemory tags context user_123 --set "This user is a premium customer"

Clear context

supermemory tags context user_123 --clear

Merge tags (moves all memories from source to target)

supermemory tags merge old-tag --into new-tag --yes

Delete a tag

supermemory tags delete old-tag --yes Subcommands: list , info , create , delete , context , merge API Keys keys — Manage API keys

List all keys

supermemory keys list

Create a new key

supermemory keys create --name my-agent --permission write

Create a scoped key (restricted to one container tag)

supermemory keys create --name bot-key --tag user_123 --expires 30

Revoke a key

supermemory keys revoke key_abc123 --yes

Toggle a key on/off

supermemory keys toggle key_abc123 Subcommands: list , create , revoke , toggle Connectors connectors — External data sources Connect Google Drive, Notion, OneDrive, and other services to automatically sync documents.

List connected services

supermemory connectors list

Connect a service (opens OAuth flow)

supermemory connectors connect google-drive --tag docs supermemory connectors connect notion --tag notes

Trigger a sync

supermemory connectors sync conn_abc123

View sync history

supermemory connectors history conn_abc123 --limit 10

List synced resources

supermemory connectors resources conn_abc123

Disconnect

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.

List available plugins

supermemory plugins list

Connect a plugin (with auto-configuration)

supermemory plugins connect claude-code --auto-configure supermemory plugins connect cursor --auto-configure

Check plugin status

supermemory plugins status claude-code

Revoke a plugin connection

supermemory plugins revoke claude-code --yes Subcommands: list , connect , revoke , status Team Management team — Manage team members

List team members

supermemory team list

Invite a member

supermemory team invite user@example.com --role admin supermemory team invite user@example.com --role member

Change a member's role

supermemory team role member_123 admin

Remove a member

supermemory team remove member_123 --yes

View pending invitations

supermemory team invitations Subcommands: list , invite , remove , role , invitations Monitoring status — Account dashboard supermemory status supermemory status --period 7d

24h, 7d, 30d, all

Shows memory count, document count, API usage, and storage. logs — Request logs

Recent logs

supermemory logs

Filter by time period

supermemory logs --period 7d

Filter by status

supermemory logs --status error

Filter by request type

supermemory logs --type search

Get a specific log entry

supermemory logs get req_abc123 billing — Usage and billing supermemory billing

Overview

supermemory billing usage

Detailed usage breakdown

supermemory billing invoices

Past invoices

Utility Commands

Open Supermemory console in browser

supermemory open supermemory open graph

Memory graph view

supermemory open billing supermemory open settings supermemory open docs supermemory open 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 using a scoped API key (restricted to a single container tag), only these commands are available: search , add , remember , forget , update , profile , whoami The tag is automatically set from the key's scope — no need to pass --tag . Common Patterns Pipe content from other tools

Ingest git log

git log --oneline -20 | supermemory add --stdin --tag git-history

Ingest command output

curl -s https://api.example.com/docs | supermemory add --stdin --tag api-docs

Pipe search results to jq

supermemory search "auth" --json | jq '.results[].memory' Scripting with JSON output

All commands support --json for machine-readable output

supermemory search "query" --json supermemory tags list --json supermemory profile user_123 --json supermemory status --json CI/CD integration

Use env var for auth

export SUPERMEMORY_API_KEY = sm_abc_xxx

Ingest docs on deploy

supermemory add ./docs/api-reference.md --tag api-docs --id api-ref-latest

Check status

supermemory status --json | jq '.memoryCount'