docs: add Supermemory CLI docs and embed SMFS into main nav

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>
This commit is contained in:
Dhravya Shah 2026-06-15 19:31:19 -07:00
parent 5eed4bcbf3
commit d62d9cc5ac
4 changed files with 556 additions and 22 deletions

318
apps/docs/cli/commands.mdx Normal file
View file

@ -0,0 +1,318 @@
---
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'
```

86
apps/docs/cli/local.mdx Normal file
View file

@ -0,0 +1,86 @@
---
title: "Local server"
sidebarTitle: "Local server"
description: "npx supermemory local — run the full memory engine on your own machine. One binary, zero config."
icon: "server"
---
`npx supermemory local` downloads and runs Supermemory's self-hosted memory engine on your machine. It's the same engine behind the [hosted platform](https://console.supermemory.ai) — ingestion, memory extraction, hybrid semantic search, and the full API — as a single self-contained binary.
No Docker, no database to provision, no config files. It boots in seconds with everything built in, and it's [open source](https://git.new/memory).
## Run it
<Tabs>
<Tab title="npx">
```bash
npx supermemory local
```
</Tab>
<Tab title="bunx">
```bash
bunx supermemory local
```
</Tab>
<Tab title="curl">
```bash
curl -fsSL https://supermemory.ai/install | bash
```
</Tab>
</Tabs>
The installer detects your OS and architecture, downloads the right binary, verifies it, and (when run interactively) prompts you for an LLM API key. Then start the server:
```bash
supermemory-server
```
First boot sets everything up — the embedded graph engine, local embeddings, and your credentials — and prints an API key:
```
┌──────────────────────────────────────────────────┐
│ url http://localhost:6767 │
│ database ./.supermemory │
│ api key sm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx │
│ org id xxxxxxxxxxxxxxxxxxxxxx │
└──────────────────────────────────────────────────┘
```
Save that API key — it's your bearer token for every request. Then point any Supermemory SDK at your local server with a one-line change:
```typescript
const client = new Supermemory({
apiKey: "sm_...", // printed on first boot
baseURL: "http://localhost:6767", // that's the only change
})
```
## Cloud CLI vs. local server
Both ship under `npx supermemory`, but they're different things:
| | `supermemory <command>` | `supermemory local` |
|---|---|---|
| What it talks to | The [hosted platform](https://console.supermemory.ai) | A server running on your machine |
| Auth | Your account ([`login`](/cli/overview#authenticate)) | Auto-generated key on first boot |
| Use case | Manage cloud memory from the terminal | Local-first, air-gapped, privacy-sensitive workloads |
| Reference | [Command reference](/cli/commands) | This page + [Self-hosting docs](/self-hosting/overview) |
## Learn more
The local server has its own full documentation — bringing your own model (or running fully offline with Ollama), configuration, and how it compares to Enterprise:
<CardGroup cols={2}>
<Card title="Self-hosting quickstart" icon="play" href="/self-hosting/quickstart">
Install, run, and store your first memory in under two minutes.
</Card>
<Card title="Configuration" icon="settings" href="/self-hosting/configuration">
Every environment variable: LLM providers, local models, storage, tuning.
</Card>
<Card title="Overview" icon="server" href="/self-hosting/overview">
What's built in, what runs offline, and how it matches the platform API.
</Card>
<Card title="Local vs. Enterprise" icon="building-2" href="/self-hosting/local-vs-enterprise">
When to run it yourself and when to move to the managed platform.
</Card>
</CardGroup>

125
apps/docs/cli/overview.mdx Normal file
View file

@ -0,0 +1,125 @@
---
title: "Supermemory CLI"
sidebarTitle: "Overview"
description: "Supermemory from the terminal. One command — npx supermemory — for your cloud memory and a local server."
icon: "square-terminal"
---
The Supermemory CLI is the complete interface to Supermemory from your terminal. Add memories, search, manage documents, configure projects, connect data sources, administer teams — all programmatically, all from `npx supermemory`.
It does two things:
<CardGroup cols={2}>
<Card title="Manage your cloud memory" icon="cloud" href="/cli/commands">
`npx supermemory <command>` talks to the [hosted platform](https://console.supermemory.ai). Add, search, and manage memories, documents, tags, keys, connectors, and teams.
</Card>
<Card title="Run a local server" icon="server" href="/cli/local">
`npx supermemory local` downloads and runs the self-hosted memory engine on your machine — one binary, zero config.
</Card>
</CardGroup>
## Install
You can run every command through `npx` with no install:
```bash
npx supermemory whoami
npx supermemory search "authentication patterns"
npx supermemory local
```
Or install it globally and drop the `npx`:
<CodeGroup>
```bash npm
npm install -g supermemory
```
```bash bun
bun add -g supermemory
```
</CodeGroup>
```bash
supermemory whoami
```
The rest of these docs use the bare `supermemory` form — prefix with `npx` if you haven't installed globally.
## Authenticate
Most commands act on your cloud account, so authenticate first:
```bash
# Browser OAuth flow
supermemory login
# Or pass an API key directly
supermemory login --api-key sm_xxx
# Confirm who you are
supermemory whoami
```
In CI or scripts, set the API key as an environment variable instead of logging in:
```bash
export SUPERMEMORY_API_KEY=sm_xxx
```
<Note>
`npx supermemory local` does **not** require authentication — it runs entirely on your machine and generates its own API key on first boot. See [Local server](/cli/local).
</Note>
## Configuration
The CLI resolves config from three scopes, most specific wins:
| Scope | File | Use case |
|---|---|---|
| `project` | `.supermemory/config.json` (gitignored) | Per-machine secrets, API keys |
| `team` | `.supermemory/team.json` (committed) | Shared container tag, team-wide defaults |
| `global` | `~/.config/supermemory/config.json` | Defaults for all projects on this machine |
```bash
# Interactive setup wizard
supermemory init
# Non-interactive
supermemory init --scope project --tag my-bot
supermemory init --scope team --tag shared-project
# View / get / set values
supermemory config
supermemory config get tag
supermemory config set tag my-project
```
### Environment variables
| Variable | Description |
|---|---|
| `SUPERMEMORY_API_KEY` | API key for authentication |
| `SUPERMEMORY_TAG` | Override the default container tag |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OpenTelemetry collector endpoint |
### Global flags
Available on every command:
| Flag | Description |
|---|---|
| `--json` | Force machine-readable JSON output |
| `--tag <string>` | Override the default container tag for this command |
| `--help` | Show help for any command |
## Next steps
<CardGroup cols={2}>
<Card title="Command reference" icon="list" href="/cli/commands">
Every command and flag — add, search, docs, tags, keys, connectors, teams, and more.
</Card>
<Card title="Local server" icon="server" href="/cli/local">
`npx supermemory local` — run the memory engine on your own machine.
</Card>
</CardGroup>

View file

@ -71,6 +71,11 @@
"group": "Getting Started",
"pages": ["intro", "quickstart", "vibe-coding"]
},
{
"group": "Command Line (CLI)",
"icon": "square-terminal",
"pages": ["cli/overview", "cli/commands", "cli/local"]
},
{
"group": "Self-Hosting",
"pages": [
@ -131,6 +136,28 @@
"memory-api/connectors/managing-resources"
]
},
{
"group": "SMFS (Memory Filesystem)",
"icon": "database",
"pages": [
"smfs/overview",
"smfs/install",
"smfs/mount",
"smfs/bash-tool",
"smfs/bash-tool-python",
{
"group": "Providers",
"icon": "cloud",
"pages": [
"smfs/providers/daytona",
"smfs/providers/e2b",
"smfs/providers/vercel",
"smfs/providers/cloudflare"
]
},
"smfs/examples"
]
},
{
"group": "Migration Guides",
"pages": [
@ -155,28 +182,6 @@
"pages": ["supermemory-mcp/claude-desktop"]
}
]
},
{
"anchor": "SMFS",
"icon": "database",
"pages": [
"smfs/overview",
"smfs/install",
"smfs/mount",
"smfs/bash-tool",
"smfs/bash-tool-python",
{
"group": "Providers",
"icon": "cloud",
"pages": [
"smfs/providers/daytona",
"smfs/providers/e2b",
"smfs/providers/vercel",
"smfs/providers/cloudflare"
]
},
"smfs/examples"
]
}
],
"tab": "Developer Platform"