# 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。 |

```bash
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>` 提供相同的分組參考。

## 本機智能體初始化

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

```bash
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>` | 刪除知識庫及其所有記憶 |

```bash
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` 前，請先在使用者後台申請或購買配額。本地模式保留獨立的本地工作區模型。

```bash
tokst workspace create --name "Team Engineering"
tokst workspace list
tokst workspace switch <workspace-id>
tokst workspace invite <workspace-id> alice@example.com,bob@example.com --expires-in-days 7
tokst workspace inbox
```

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

---

## 記憶操作

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

### 記住 (Remember)

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

```bash
tokst remember "Your content here" --type note
```

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

```bash
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 到期時間 |

### 列表、更新、追加

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

### 歸檔、恢復、刪除

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

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

### 驗證與取代

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

```bash
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>
```

### 檔案附件

```bash
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> # 下載指定附件
```

---

## 搜尋與上下文

```bash
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` 可立即切換為純關鍵字預設路徑。

---

## 批量匯入

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

```bash
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` | 強制將本機狀態與伺服器同步 |

```bash
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` 檢視詳細用法：

```bash
tokst remember --help
```

## 會話記憶

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

```bash
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 在本機去識別後自動儲存一筆可撤銷的正式記憶。

```bash
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` 恢復的工作階段會更新同一筆自動記憶：

```bash
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 工具對應請閱讀[工作階段記憶指南](/docs/sessions)。