# CLI Reference The `tokst` CLI is the primary interface for interacting with the TokST memory system. All commands are grouped below by function. > Many commands accept `--atlas` as shorthand for `--atlas-id`. Pass `--json` to any command for machine-readable output. For Claude, Pi, Codex, and other command-executing agents, set `TOKST_AGENT=1` or pass `--agent`. This additive mode uses compact bounded JSON, hard network deadlines, deterministic stream flushing, and skips interactive version checks. Add `--full` to receive the complete existing JSON response and `--stdin` for delayed input pipes. --- ## Authentication | Command | Description | |---|---| | `tokst version [--verbose]` or `tokst --version` | Show the installed version; `--verbose` also shows the active installation channel and executable. | | `curl -fsSL https://tokst.com/install.sh \| bash` | Install or upgrade the checksum-verified standalone CLI. Existing authorization stays in place. | | `irm https://tokst.com/install.ps1 \| iex` | Install or upgrade the checksum-verified standalone CLI on Windows PowerShell. | | `tokst update` | Update through the current install channel: verified standalone binary, npm, or Bun. | | `tokst login --key ` | Authenticate with an API key (`tk_live_xxxx`). Credentials are saved to `~/.tokst/config.json`. | | `tokst logout` | Clear the stored session credentials. | | `tokst doctor [--fix-path]` | Check authentication, optional repository and Atlas binding, Agent integration files, and command priority. `--fix-path` prioritizes a standalone CLI in zsh or bash. | ```bash curl -fsSL https://tokst.com/install.sh | bash # Windows PowerShell irm https://tokst.com/install.ps1 | iex tokst version tokst update tokst doctor tokst login --key tk_live_abc123def456 tokst logout ``` The installer supports macOS Apple Silicon, macOS Intel, Linux x64, Linux ARM64, Windows x64, Windows ARM64, and WSL. It requires only `curl` on macOS/Linux or PowerShell on Windows, verifies SHA-256 before activation, and retains an existing local connection. The Unix executable lives in `~/.local/bin`; Windows uses `%LOCALAPPDATA%\\TokST\\bin`. `tokst update` keeps the active install channel: standalone installations download a verified binary, npm installations run `npm update -g @tokst/cli`, and Bun installations run `bun add -g @tokst/cli@latest`. `setup` is the recommended interactive flow. It opens `tokst.com`, confirms the signed-in account, then returns a one-time credential directly to the waiting CLI. It never selects a workspace or Atlas: choose scope explicitly per command, use `tokst workspace switch` when a terminal needs an active workspace, or bind an Atlas only for a directory that belongs to one project. API-key login remains available for CI, servers, and unattended scripts. ## Help `tokst --help` shows the daily workflow. Use `tokst memory --help`, `tokst atlas --help`, `tokst workspace --help`, or `tokst agent --help` for a complete command group. `tokst help ` provides the same grouped reference. ## Local Agent Setup Generate local instructions for the agents that work in this directory. ```bash tokst init --agents codex,claude,cursor,opencode,pi tokst doctor ``` `tokst init` only writes local Agent instructions and works in any directory. Existing instruction files are preserved; use `--force` to refresh them intentionally. Create an Atlas with `tokst atlas init`, then bind a directory with `tokst atlas bind --atlas-id ` when project routing is needed. `tokst doctor` reports authentication, optional repository and Atlas binding, and integration-file checks. --- ## Atlas Management Atlases are named knowledge bases that hold related memories. | Command | Description | |---|---| | `tokst atlas init --name ` | Create a new atlas | | `tokst atlas bind --atlas-id [--path ]` | Bind an existing Atlas to a directory; Git metadata is optional | | `tokst atlas list` | List all atlases in the active workspace | | `tokst atlas rename --atlas-id --name ` | Rename an atlas | | `tokst atlas profile --atlas-id --keywords a,b,c` | Set keyword profile for auto-routing | | `tokst atlas delete --atlas-id ` | Delete an atlas and all its memories | ```bash tokst atlas init --name "Project Alpha" tokst atlas bind --atlas-id tokst atlas list tokst atlas profile --atlas-id --keywords architecture,backend,api tokst atlas rename --atlas-id --name "Project Alpha v2" tokst atlas delete --atlas-id ``` --- ## Workspace Management Workspaces group atlases together for organizational separation (e.g., personal vs. team). | Command | Description | |---|---| | `tokst workspace create --name ` | Create a new workspace | | `tokst workspace list` | List all workspaces you belong to | | `tokst workspace switch ` | Switch the active workspace | | `tokst workspace members ` | List workspace members and roles | | `tokst workspace invite ` | Invite up to 100 people to a Team workspace; supports `--role` and `--expires-in-days` | Cloud Team workspace creation uses the account's available Team workspace quota. Request or purchase quota in the dashboard before running `tokst workspace create --name --type team`. Local mode keeps its independent local workspace model. | `tokst workspace invitations ` | List invitations sent by a workspace | | `tokst workspace inbox` | List your pending invitations | | `tokst workspace respond --accept\|--decline` | Accept or decline an invitation | | `tokst workspace revoke --confirm` | Revoke a pending invitation | | `tokst workspace leave --confirm` | Leave a workspace | | `tokst workspace role --role admin\|member --confirm` | Change a member role | | `tokst workspace remove --confirm` | Remove a member | | `tokst workspace transfer-owner --confirm` | Transfer workspace ownership | ```bash tokst workspace create --name "Team Engineering" tokst workspace list tokst workspace switch tokst workspace invite alice@example.com,bob@example.com --expires-in-days 7 tokst workspace inbox ``` `tokst workspace list` marks the saved active workspace and prints pending invitations with their accept and decline commands. `tokst workspace switch` saves the selection; subsequent `tokst atlas init` commands create the Atlas in that workspace. Accept an invitation first, then switch to the newly joined workspace. ## Agent Identity and Handoffs `TOKST_AGENT=1` or `--agent` uses the trusted Agent identity bound to the current API Key. TokST creates a stable `agt_...` code on the first trusted call. `--source` remains a display label. | Command | Description | |---|---| | `tokst agent list [workspace-id]` | List trusted Agents in a workspace | | `tokst agent listen [--workspace ] [--json]` | Keep a real-time Agent event stream open; emits JSON Lines for Agent runtimes | | `tokst message send "text" --to agt_...` | Send to one or more Agents | | `tokst message send "text" --broadcast` | Fan out to active workspace Agents | | `tokst message inbox [--workspace ]` | Read all Agent inbox messages, or filter to one workspace | | `tokst message acknowledge ` | Acknowledge a message | | `tokst message close ` | Close a message | Direct messages are visible to the sender, recipients, and workspace Owner/Admin. Broadcast messages are visible to workspace members and their Agent recipients. Run `TOKST_AGENT=1 tokst agent listen --json` as a small sidecar beside a long-running Agent. It reconnects automatically and emits an initial unread-message snapshot after each connection. Call `tokst message acknowledge` only after the Agent accepts the work, then call `tokst message close` after completion. --- ## Memory Operations The core of TokST — storing, retrieving, and managing memories. ### Remember Store a new memory. This is the most frequently used command. ```bash tokst remember "Your content here" --type note ``` Short facts can remain plain text. Use Markdown for decisions, architecture, meeting notes, and tasks. For long content, pass a Markdown file through stdin: ```bash tokst remember --type decision --tags api,auth --stdin < decision.md ``` Use headings, lists, task checkboxes, links, tables, and code blocks when they make a memory easier to review. Keep credentials, private keys, raw reasoning, and transient tool output outside TokST. | Option | Description | |---|---| | `--type` | Memory type: `fact`, `decision`, `preference`, `task`, `architecture`, `note` (default: `note`) | | `--tags` | Comma-separated tags for filtering (e.g., `--tags deploy,production`) | | `--source-type` | Source type: `human`, `agent`, `import`, `system` (default: `human`) | | `--source` | Source name, such as `codex` or `import` | | `--atlas` | Target atlas ID (shorthand for `--atlas-id`) | | `--title` | Optional title for the memory | | `--file` | Attach one or more files (repeatable: `--file a.png --file b.pdf`) | | `--evidence` | Evidence URL or source file path | | `--confidence` | Confidence from `0` to `1` | | `--valid-until` | ISO expiry date-time for time-bound information | ### List, Get, Update, Append ```bash tokst memory list # List recent memories tokst memory update --content "Updated content" tokst memory append --content "Additional information" ``` ### Archive, Restore, Delete Memories follow a lifecycle: active -> archived -> deleted. ```bash tokst memory archive # Archive (soft-hide) tokst memory restore # Restore from archive tokst memory delete # Permanent deletion ``` ### Verify and Supersede Mark a record as verified with its supporting evidence, confidence, and optional expiry. When new information replaces an existing record, preserve the relationship instead of losing the previous decision trail. ```bash tokst memory verify --evidence https://example.com/source --confidence 0.95 tokst memory verify --valid-until 2027-01-01T00:00:00Z tokst memory supersede ``` ### File Attachments ```bash tokst memory attach --file document.pdf tokst memory download # Download all attachments to ~/Downloads tokst memory download --out ./files # Specify output directory tokst memory download --attachment-id # Download a specific attachment ``` --- ## Search & Context ```bash tokst search "keyword query" # Adaptive auto mode (default) tokst search "query" --search-mode keyword tokst search "query" --search-mode semantic tokst search "query" --search-mode hybrid tokst search "query" --type fact # Filter by type tokst search "query" --tags api # Filter by tag tokst search "query" --limit 20 # Limit results (default: 10) tokst search "query" --json # Machine-readable output tokst context # Snapshot of active atlas context tokst context --atlas # Context for a specific atlas tokst context --limit 50 # Include up to 50 recent memories ``` `tokst context` returns a formatted summary of recent memories in the active atlas — useful for providing conversation context to AI agents. `--json` includes `meta.requestedMode`, `meta.resolvedMode`, embedding cache level, and keyword/embedding/vector/total timing. Set `SEARCH_DEFAULT_MODE=keyword` for an immediate keyword-only rollback. --- ## Batch Import Import files from a folder (or a single file) as memories. Text files are extracted automatically; binary files are uploaded as attachments with the filename as content. ```bash tokst import ./docs # Import all files in a folder tokst import report.pdf # Import a single file tokst import ./code --type architecture # Set default memory type tokst import ./docs --tags imported,docs # Add tags to all imported memories tokst import ./large-dir --max 50 # Limit to 50 files tokst import ./docs --dry-run # Preview without importing tokst import ./docs --no-attach # Text only, skip file uploads ``` **Supported text formats** (auto-extracted): txt, md, json, csv, yaml, xml, html, css, js, ts, tsx, py, go, rs, java, sql, sh, and 15+ more. **Binary formats** (uploaded as attachment): pdf, png, jpg, docx, xlsx, and all others. | Option | Description | |--------|-------------| | `--type` | Default memory type for all imports (default: `note`) | | `--tags` | Comma-separated tags added to all imports | | `--atlas-id` | Target atlas (default: auto-route or first atlas) | | `--source` | Source name (default: `import`) | | `--dry-run` | Scan and preview without importing | | `--max` | Maximum number of files to import | | `--no-attach` | Create text memories only, skip uploading original files | --- ## Utilities | Command | Description | |---|---| | `tokst status` | Display plan, usage, storage, personal workspace and Atlas quotas, Team workspace quota, and memory stats | | `tokst status --json` | Same, in JSON format for scripting | | `tokst migrate` | Migrate data between schemas (admin use) | | `tokst sync` | Force sync local state with the server | ```bash tokst status ``` Example output (cloud mode): ``` Mode: Cloud (Supabase) Endpoint: https://pdjpdivokmcevxdrvtfb.supabase.co Plan: pro 206 / 10,000 calls this month (2% used, resets Jul 1) Storage: 673 KB / 10.00 GB 7 files (0% used) Quotas: Personal workspaces: 2 / 10 8 available Personal Atlases: 7 / 200 193 available (20 per workspace) Team workspaces: 3 / 5 2 available to create Summary: Workspaces: 2 Atlases: 7 Memories: 248 active Workspaces: kueen personal Atlases: TokST in kueen 43 mem (fact=13, architecture=18, decision=9, note=3) ... ``` The `Plan:`, `Storage:`, and `Quotas:` lines appear only in cloud mode. `--json` adds an `account` block with `plan`, `monthlyLimit`, `periodResetAt`, `usage`, `storage`, and `quota` fields. A quota with no limit is shown as `unlimited`. --- ## Common Options | Option | Description | |---|---| | `--json` | Output results as JSON instead of formatted text | | `--atlas` | Alias for `--atlas-id`, specifies target atlas | | `--help` | Show help for any command | | `--version` | Show CLI version | All commands support `--help` for detailed usage: ```bash tokst remember --help ``` ## Session Memory Use Session Memory for a task that spans multiple tool calls or needs a durable handoff. | Command | Description | |---|---| | `tokst session start` | Create a session and return scoped context | | `tokst session capture` | Save a durable candidate memory | | `tokst session checkpoint` | Save a compact progress checkpoint | | `tokst session finalize` | Create a snapshot and compile candidates | | `tokst session status` | Read session state, candidates, checkpoints, and context | | `tokst session list` | List your sessions, or the managed workspace view for Owner/Admin | | `tokst session candidates` | List the workspace candidate review queue | | `tokst session candidate` | Compile, dismiss, or revert one candidate memory | | `tokst session archive` | Archive a session while retaining its history | | `tokst auto on\|off\|status` | Enable, disable, or inspect automatic memory bridges on this device | | `tokst auto repair --agent ` | Repair the selected native bridge and refresh its absolute TokST command path | | `tokst auto privacy --retain-raw 0\|24h` | Choose immediate local deletion or a 24-hour local recovery window | | `tokst acp proxy -- ` | Transparently connect an ACP Agent through TokST automatic memory | ```bash TOKST_AGENT=1 tokst session start --atlas-id --task "Implement session memory" --json TOKST_AGENT=1 tokst session capture --session "Use idempotency keys" --kind decision --tags api,reliability --json TOKST_AGENT=1 tokst session checkpoint --session "Server routes complete" --json TOKST_AGENT=1 tokst session finalize --session "Completed the server routes and contract." --json ``` `session finalize` compiles candidates by default. Add `--no-compile` to retain candidates for review. Owner and Admin can use `session list --scope managed`, then compile, dismiss, or revert candidates. Reverting archives the formal memory and preserves the audit trail. ### Automatic memory Automatic memory remains off until enabled once on the device. `tokst auto on` detects WorkBuddy, OpenCode, Pi, Codex, and Claude Code, installs their native bridges, and starts the local service. The OpenCode global plugin loads in both the terminal and macOS App; Pi uses a global extension; Codex and Claude Code use managed Hook entries that preserve existing user Hooks. The ACP Host entrypoint remains available for external ACP clients. TokST removes sensitive data locally and creates one structured memory in a private compiler session. ```bash tokst auto on --agent all tokst acp proxy -- [args] tokst auto status tokst auto verify --agent all --json ``` For OpenCode terminal and macOS App, install the global plugin once, then restart OpenCode. The same native session updates one automatic memory when resumed with `opencode -s`: ```bash tokst auto on --agent opencode tokst acp opencode --doctor # OpenCode starts normally; the global plugin is loaded automatically. # An external ACP Host can use: command=tokst, args=["acp", "opencode"] ``` Use `tokst auto repair --agent ` to refresh an installed bridge, `tokst auto off --agent ` to remove only that bridge, and `tokst auto logs --agent ` for local diagnostics. `tokst acp opencode --repair` retains the ACP Host repair workflow. `tokst acp pi --doctor` reports the direct Pi bridge and optional ACP Host adapter state. TokST installs its local automatic-memory service after enablement. It queues sanitized events during network interruptions and retries using stable ACP event IDs. Raw content is discarded by default; use `tokst auto privacy --retain-raw 24h` when a short local recovery window is required. `tokst session list` excludes diagnostics by default. Each completed native or ACP session writes one reversible formal memory only when it contains durable confirmed material. Claude Desktop remains an MCP-assisted integration and uses explicit Session tools. Read the [Session Memory guide](/docs/sessions) for the complete lifecycle, retry keys, Local workflow, dashboard governance, and MCP mapping.