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

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 <group> provides the same grouped reference.

Local Agent Setup

Generate local instructions for the agents that work in this directory.

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 <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.

tokst atlas init --name "Project Alpha"
tokst atlas bind --atlas-id <id>
tokst atlas list
tokst atlas profile --atlas-id <id> --keywords architecture,backend,api
tokst atlas rename --atlas-id <id> --name "Project Alpha v2"
tokst atlas delete --atlas-id <id>

Workspace Management

Workspaces group atlases together for organizational separation (e.g., personal vs. team).

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 <name> --type team. Local mode keeps its independent local workspace model. | tokst workspace invitations <workspace-id> | List invitations sent by a workspace | | tokst workspace inbox | List your pending invitations | | tokst workspace respond <invitation-id> --accept\|--decline | Accept or decline an invitation | | tokst workspace revoke <invitation-id> --confirm | Revoke a pending invitation | | tokst workspace leave <workspace-id> --confirm | Leave a workspace | | tokst workspace role <workspace-id> <user-id> --role admin\|member --confirm | Change a member role | | tokst workspace remove <workspace-id> <user-id> --confirm | Remove a member | | tokst workspace transfer-owner <workspace-id> <user-id> --confirm | Transfer workspace ownership |

tokst workspace create --name "Team Engineering"
tokst workspace list
tokst workspace switch <workspace-id>
tokst workspace invite <workspace-id> [email protected],[email protected] --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.

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.

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:

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.

List, Get, Update, Append

tokst memory list                   # List recent memories
tokst memory update <id> --content "Updated content"
tokst memory append <id> --content "Additional information"

Archive, Restore, Delete

Memories follow a lifecycle: active -> archived -> deleted.

tokst memory archive <id>           # Archive (soft-hide)
tokst memory restore <id>           # Restore from archive
tokst memory delete <id>            # 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.

tokst memory verify <id> --evidence https://example.com/source --confidence 0.95
tokst memory verify <id> --valid-until 2027-01-01T00:00:00Z
tokst memory supersede <older-id> <replacement-id>

File Attachments

tokst memory attach <id> --file document.pdf
tokst memory download <id>                       # Download all attachments to ~/Downloads
tokst memory download <id> --out ./files         # Specify output directory
tokst memory download <id> --attachment-id <aid> # Download a specific attachment

Search & Context

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 <id>          # 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.

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.

Utilities

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

All commands support --help for detailed usage:

tokst remember --help

Session Memory

Use Session Memory for a task that spans multiple tool calls or needs a durable handoff.

TOKST_AGENT=1 tokst session start --atlas-id <atlas-id> --task "Implement session memory" --json
TOKST_AGENT=1 tokst session capture --session <ses-id> "Use idempotency keys" --kind decision --tags api,reliability --json
TOKST_AGENT=1 tokst session checkpoint --session <ses-id> "Server routes complete" --json
TOKST_AGENT=1 tokst session finalize --session <ses-id> "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.

tokst auto on --agent all
tokst acp proxy -- <acp-agent-command> [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:

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 <name> to refresh an installed bridge, tokst auto off --agent <name> to remove only that bridge, and tokst auto logs --agent <name> 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 for the complete lifecycle, retry keys, Local workflow, dashboard governance, and MCP mapping.