CLI 參考

tokst CLI 是與 TokST 記憶系統互動的主要介面。以下所有指令按功能分組。

許多指令接受 --atlas 作為 --atlas-id 的簡寫。為任何指令傳入 --json 可取得機器可讀的輸出。

Claude、Pi、Codex 等智能體執行指令時，可設定 TOKST_AGENT=1 或傳入 --agent。這個增量模式提供精簡且有上限的 JSON、網路硬截止時間、確定性輸出刷新，並略過互動式版本檢查。加入 --full 可取得完整的現有 JSON 回應；延遲輸入管線使用 --stdin。

Agent 身分與交接

TOKST_AGENT=1 或 --agent 會使用目前 API Key 綁定的可信 agt_... 身分。tokst agent listen [--workspace <id>] [--json] 保持即時事件流並為 Agent Runtime 輸出 JSON Lines；tokst message inbox 預設讀取全部工作區的持久收件匣，可使用 --workspace <id> 篩選。tokst message send 支援 --to agt_... 定向傳送或 --broadcast 廣播；tokst message acknowledge <id> 和 tokst message close <id> 管理回執。

在長期執行的 Agent 旁啟動 TOKST_AGENT=1 tokst agent listen --json 作為輕量 sidecar。重新連線後會先輸出未讀訊息快照；Agent 接受工作後再確認，完成後關閉回執。

驗證

指令	描述
`tokst version [--verbose]` 或 `tokst --version`	顯示已安裝 CLI 版本；`--verbose` 同時顯示目前安裝渠道和可執行檔。
`curl -fsSL https://tokst.com/install.sh \| bash`	安裝或升級通過 SHA-256 驗證的獨立 CLI，並保留既有授權。
`irm https://tokst.com/install.ps1 \| iex`	在 Windows PowerShell 安裝或升級通過 SHA-256 驗證的獨立 CLI。
`tokst update`	依目前安裝渠道升級：驗證後的獨立二進位、npm 或 Bun。
`tokst login --key <key>`	使用 API 金鑰進行驗證（`tk_live_xxxx`）。憑證儲存到 `~/.tokst/config.json`。
`tokst logout`	清除儲存的工作階段憑證。
`tokst doctor [--fix-path]`	檢查驗證、可選的 Git 儲存庫和知識庫綁定、智能體整合檔案與命令優先順序；`--fix-path` 可在 zsh 或 bash 中優先使用獨立 CLI。

curl -fsSL https://tokst.com/install.sh | bash
tokst version
tokst doctor
tokst login --key tk_live_abc123def456
tokst logout

setup 是建議的互動流程。它會開啟 tokst.com，確認已登入帳戶，再將一次性憑證直接交給等待中的 CLI。它不會選擇工作區或知識庫：每條指令明確指定範圍；終端需要使用中的工作區時使用 tokst workspace switch；僅在目錄固定屬於一個專案時才綁定知識庫。API Key 登入繼續適用於 CI、伺服器和無人值守指令碼。

說明

tokst --help 顯示日常工作流程。使用 tokst memory --help、tokst atlas --help、tokst workspace --help 或 tokst agent --help 查看完整指令分組；tokst help <group> 提供相同的分組參考。

本機智能體初始化

為目前目錄中的智能體產生本機指令。

tokst init --agents codex,claude,cursor,opencode,pi
tokst doctor

tokst init 只寫入本機智能體指令，可在任意目錄使用。既有指令檔案會被保留；需要更新時使用 --force。使用 tokst atlas init 建立知識庫，需要專案路由時再使用 tokst atlas bind --atlas-id <id> 綁定目錄。tokst doctor 會報告驗證、可選的 Git 儲存庫和知識庫綁定，以及整合檔案的檢查結果。

知識庫管理

知識庫是保存相關記憶的命名知識庫。

指令	描述
`tokst atlas init --name <name>`	建立新知識庫
`tokst atlas bind --atlas-id <id> [--path <path>]`	將既有知識庫綁定到目錄；Git 中繼資料可選
`tokst atlas list`	列出活躍工作區中的所有知識庫
`tokst atlas rename --atlas-id <id> --name <new>`	重新命名知識庫
`tokst atlas profile --atlas-id <id> --keywords a,b,c`	設定關鍵詞設定檔以啟用自動路由
`tokst atlas delete --atlas-id <id>`	刪除知識庫及其所有記憶

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>

工作區管理

工作區將知識庫分組，以實現組織隔離（例如，個人 vs. 團隊）。

指令	描述
`tokst workspace create --name <name>`	建立新工作區
`tokst workspace list`	列出您所屬的所有工作區
`tokst workspace switch <workspace-id>`	切換活躍工作區
`tokst workspace members <workspace-id>`	列出工作區成員和角色
`tokst workspace invite <團隊工作區-id> <email[,email,...]>`	邀請最多 100 位使用者加入團隊工作區；支援 `--role` 和 `--expires-in-days`
`tokst workspace invitations <workspace-id>`	列出該工作區已發出的邀請
`tokst workspace inbox`	列出自己待處理的邀請
`tokst workspace respond <invitation-id> --accept\|--decline`	接受或拒絕邀請
`tokst workspace revoke <invitation-id> --confirm`	撤銷待處理邀請
`tokst workspace leave <workspace-id> --confirm`	離開工作區
`tokst workspace role <workspace-id> <user-id> --role admin\|member --confirm`	修改成員角色
`tokst workspace remove <workspace-id> <user-id> --confirm`	移除成員
`tokst workspace transfer-owner <workspace-id> <user-id> --confirm`	轉讓工作區 Owner

雲端團隊工作區建立會使用帳戶的可用團隊工作區配額。執行 tokst workspace create --name <名稱> --type team 前，請先在使用者後台申請或購買配額。本地模式保留獨立的本地工作區模型。

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 會標記已儲存的目前工作區，並顯示待處理邀請及接受、拒絕命令。tokst workspace switch 會儲存選擇，後續的 tokst atlas init 將在該工作區建立知識庫。接受邀請後，再切換到新加入的工作區。

記憶操作

TokST 的核心 — 儲存、檢索和管理記憶。

記住 (Remember)

儲存一條新記憶。這是最常用的指令。

tokst remember "Your content here" --type note

短事實可以使用純文字。決策、架構、會議紀要和工作建議使用 Markdown。寫入長內容時，可透過標準輸入傳入 Markdown 檔案：

tokst remember --type decision --tags api,auth --stdin < decision.md

標題、清單、工作清單、連結、表格和程式碼區塊可以提升閱讀效率。金鑰、私鑰、原始推理和暫時工具輸出保留在 TokST 之外。

選項	描述
`--type`	記憶類型：`fact`、`decision`、`preference`、`task`、`architecture`、`note`（預設：`note`）
`--tags`	逗號分隔的標籤，用於篩選（例如：`--tags deploy,production`）
`--source-type`	來源類型：`human`、`agent`、`import`、`system`（預設：`human`）
`--source`	來源名稱，例如 `codex` 或 `import`
`--atlas`	目標知識庫 ID（`--atlas-id` 的簡寫）
`--title`	可選的記憶標題
`--file`	附加一個或多個檔案（可重複：`--file a.png --file b.pdf`）
`--evidence`	證據 URL 或來源檔案路徑
`--confidence`	可信度，取值 `0` 到 `1`
`--valid-until`	具時效性資訊的 ISO 到期時間

列表、更新、追加

tokst memory list                   # 列出最近的記憶
tokst memory update <id> --content "Updated content"
tokst memory append <id> --content "Additional information"

歸檔、恢復、刪除

記憶遵循生命週期：活躍 -> 已歸檔 -> 已刪除。

tokst memory archive <id>           # 歸檔（軟隱藏）
tokst memory restore <id>           # 從歸檔恢復
tokst memory delete <id>            # 永久刪除

驗證與取代

為記憶補充證據、可信度和可選有效期限後，可將其標記為已驗證。新資訊取代舊資訊時，保留兩條記憶之間的關聯，以便追溯原有決策。

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 <舊記憶-id> <新記憶-id>

檔案附件

tokst memory attach <id> --file document.pdf
tokst memory download <id>                       # 下載所有附件到 ~/Downloads
tokst memory download <id> --out ./files         # 指定輸出目錄
tokst memory download <id> --attachment-id <aid> # 下載指定附件

搜尋與上下文

tokst search "keyword query"        # 自適應 auto 模式（預設）
tokst search "query" --search-mode keyword
tokst search "query" --search-mode semantic
tokst search "query" --search-mode hybrid
tokst search "query" --type fact    # 按類型篩選
tokst search "query" --tags api     # 按標籤篩選
tokst search "query" --limit 20     # 限制結果數（預設：10）
tokst search "query" --json         # 機器可讀輸出

tokst context                       # 目前知識庫上下文快照
tokst context --atlas <id>          # 指定知識庫的上下文
tokst context --limit 50            # 包含最多 50 條最近記憶

tokst context 傳回目前知識庫中最近記憶的格式化摘要 — 適用於為 AI 智能體提供對話上下文。

--json 會傳回最終模式、embedding 快取層級，以及關鍵字、embedding、向量與總耗時。SEARCH_DEFAULT_MODE=keyword 可立即切換為純關鍵字預設路徑。

批量匯入

從資料夾（或單一檔案）批量匯入記憶。文字檔案自動提取內容；二進位檔案作為附件上傳，檔名作為記憶內容。

tokst import ./docs                          # 匯入資料夾中的所有檔案
tokst import report.pdf                      # 匯入單一檔案
tokst import ./code --type architecture      # 設定預設記憶類型
tokst import ./docs --tags imported,docs     # 為所有匯入的記憶新增標籤
tokst import ./large-dir --max 50            # 限制最多匯入 50 個檔案
tokst import ./docs --dry-run                # 預覽不實際匯入
tokst import ./docs --no-attach              # 僅建立文字記憶，不上傳原始檔案

支援的文字格式（自動提取）：txt、md、json、csv、yaml、xml、html、css、js、ts、tsx、py、go、rs、java、sql、sh 等 30+ 種。

二進位格式（作為附件上傳）：pdf、png、jpg、docx、xlsx 等所有其他格式。

選項	說明
`--type`	所有匯入記憶的預設類型（預設：`note`）
`--tags`	逗號分隔的標籤，新增至所有匯入記憶
`--atlas-id`	目標知識庫（預設：自動路由或第一個知識庫）
`--source`	來源名稱（預設：`import`）
`--dry-run`	掃描預覽，不實際匯入
`--max`	最多匯入的檔案數量
`--no-attach`	僅建立文字記憶，跳過原始檔案上傳

實用工具

指令	描述
`tokst status`	顯示方案、用量、儲存、個人工作區與知識庫配額、團隊工作區配額及記憶統計
`tokst status --json`	同上，JSON 格式供腳本使用
`tokst migrate`	在架構之間遷移資料（管理員使用）
`tokst sync`	強制將本機狀態與伺服器同步

tokst status

範例輸出（雲端模式）：

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

Plan:、Storage: 與 Quotas: 行僅在雲端模式顯示。--json 會額外輸出 account 區塊，包含 plan、monthlyLimit、periodResetAt、usage、storage 與 quota 欄位。無上限的配額會顯示為 unlimited。

通用選項

選項	描述
`--json`	以 JSON 格式輸出結果（而非格式化文字）
`--atlas`	`--atlas-id` 的別名，指定目標知識庫
`--help`	顯示任何指令的幫助資訊
`--version`	顯示 CLI 版本

所有指令都支援 --help 檢視詳細用法：

tokst remember --help

會話記憶

會話記憶適用於多步驟任務與智能體交接。

TOKST_AGENT=1 tokst session start --atlas-id <atlas-id> --task "實作會話記憶" --json
TOKST_AGENT=1 tokst session capture --session <ses-id> "寫入使用冪等鍵" --kind decision --tags api,reliability --json
TOKST_AGENT=1 tokst session checkpoint --session <ses-id> "伺服器路由已完成" --json
TOKST_AGENT=1 tokst session finalize --session <ses-id> "已完成伺服器路由與契約。" --json

session start 回傳目前範圍的上下文；capture 保存候選記憶；finalize 寫入會話快照，並預設將候選內容編譯為正式記憶。加入 --no-compile 可保留候選內容等待審核。使用 tokst session candidates --scope mine --status pending 檢視自己的待審核佇列。Owner 與 Admin 可使用 --scope managed 檢視整個工作區，並編譯、駁回、撤銷候選內容或封存會話。

自動記憶

自動記憶由使用者在目前裝置主動啟用。tokst auto on 會偵測 WorkBuddy、OpenCode、Pi、Codex 與 Claude Code，安裝原生橋接器並啟動本機服務。OpenCode 全域外掛涵蓋終端與 macOS App；Pi 使用全域擴充；Codex 與 Claude Code 使用受管理 Hook 並保留既有 Hook；外部 ACP Host 持續使用 ACP 入口。TokST 在本機去識別後自動儲存一筆可撤銷的正式記憶。

tokst auto on --agent all
tokst acp proxy -- <acp-agent-command> [args]
tokst auto status
tokst auto verify --agent all --json
tokst auto privacy --retain-raw 24h

OpenCode 終端與 macOS App 使用全域外掛。安裝一次後重新啟動 OpenCode；透過 opencode -s 恢復的工作階段會更新同一筆自動記憶：

tokst auto on --agent opencode
tokst acp opencode --doctor
# OpenCode 正常啟動即可自動載入外掛。
# 外部 ACP Host 可設定 command=tokst，args=["acp", "opencode"]

tokst auto repair --agent opencode 會重新產生全域外掛並更新固定的 TokST 可執行檔絕對路徑。tokst acp opencode --repair 保留 ACP Host 修復流程。

自動記憶會啟動使用者層級服務。網路中斷時已去識別事件保留在本機佇列中，並以事件 ID 安全補傳。個人工作區和預設知識庫作為預設路由；團隊工作區由使用者明確切換後生效。

完整生命週期、重試鍵、本機工作流程、後台治理和 MCP 工具對應請閱讀工作階段記憶指南。