📝 docs(guide): add CLI reference section to user manual

via [HAPI](https://hapi.run)

Author: chaizhenhua

docs/guide/user-manual.md

@@ -1207,3 +1207,175 @@ Oversight provides 53 tools that agents can use during execution. Tools are orga
 | Tool | Description |
 |------|-------------|
 | `parse_document` | Parse a Markdown file into structured sections by heading hierarchy |
+
+---
+
+## 11. Command-Line Reference
+
+For users who prefer the terminal, Oversight ships a comprehensive `oversight` CLI that mirrors most of what the web UI offers. Install once, then manage projects, tasks, workflows, agents, and knowledge from your shell — pipe-friendly output, scriptable, SSH-safe.
+
+### Getting started
+
+Build the CLI binaries:
+
+```bash
+cargo build -p oversight-cli --release
+# Binary lands at target/release/oversight
+```
+
+First-time setup:
+
+```bash
+# Log in (creates ~/.config/oversight/config.toml with your bearer token)
+oversight auth login --username admin
+
+# Pick a default project so you don't have to pass --project every time
+oversight projects list
+oversight projects use <project-id>
+
+# Shell tab-completion (one-time)
+oversight completion bash > /etc/bash_completion.d/oversight       # or zsh / fish / powershell / elvish
+```
+
+### Global options
+
+These flags work on every subcommand:
+
+| Flag | Purpose |
+|------|---------|
+| `--profile <name>` | Switch the active config profile for this invocation |
+| `--server <url>` | Override the server URL |
+| `-p, --project <id>` | Override the active project |
+| `-f, --format <fmt>` | Output format: `auto` (default), `table`, `json`, `yaml`, `csv`, `name` |
+
+`auto` picks `table` when stdout is a TTY and `json` when piped — so `oversight tasks list | jq` works without extra flags.
+
+### Subcommand overview
+
+| Group | What it does |
+|-------|--------------|
+| `auth` | Log in/out, show current user |
+| `config` | Manage ~/.config/oversight/config.toml + named profiles |
+| `completion` | Print a shell completion script |
+| `projects` | List / describe / create / set default project |
+| `tasks` | All 12 task verbs: list, tree, board, describe, create, transition, comment, update, delete, assign, relate, attach |
+| `workflows` | Inspect workflows and their automation rules |
+| `agents` | Browse agent definitions, show stats |
+| `inbox` | Clear pending tool-permission approvals; accept/reject proposed tasks |
+| `cycles` | Sprints / iterations — CRUD |
+| `milestones` | Release targets — CRUD |
+| `schedules` | Cron-scheduled agent runs — CRUD + run-now |
+| `collections` | Knowledge base containers |
+| `docs` | Knowledge documents (Markdown content) |
+| `search` | Cross-entity search (tasks, documents, projects) |
+| `system` | Health check, global stats, agent activity log |
+| `init` / `run` / `worker` | Local CLI agent integration (legacy path, unchanged) |
+
+Run `oversight <group> --help` for detailed verbs and flags on any group.
+
+### Common recipes
+
+**Triage the backlog:**
+
+```bash
+oversight tasks list --status backlog --priority P0
+```
+
+**See the board:**
+
+```bash
+oversight tasks board
+```
+
+**Tree-view a feature:**
+
+```bash
+oversight tasks tree TASK-abc123
+```
+
+**Create a task, then transition it:**
+
+```bash
+oversight tasks create --title "Add password reset" --type feature
+# → task-4f2e...
+oversight tasks transition task-4f2e... in_progress
+```
+
+**Approve a pending tool-permission request:**
+
+```bash
+oversight inbox approvals                    # list pending
+oversight inbox approvals approve <tool-call-id>
+```
+
+**Comment on a task via `$EDITOR`:**
+
+```bash
+oversight tasks comment task-4f2e...         # opens $EDITOR for Markdown
+```
+
+**Pipe JSON to `jq` for scripting:**
+
+```bash
+oversight tasks list --format json \
+  | jq '.[] | select(.status == "backlog") | .id' \
+  | xargs -I {} oversight tasks transition {} ready
+```
+
+**Switch between environments:**
+
+```bash
+oversight config configurations create prod --server https://oversight.prod.example
+oversight auth login --profile prod
+oversight --profile prod tasks list         # one-off override
+oversight config use-profile prod           # switch persistent default
+```
+
+**Search knowledge base:**
+
+```bash
+oversight search "oauth login" --types document --limit 10
+```
+
+**Monitor agent activity:**
+
+```bash
+oversight system status                     # server health
+oversight system stats                      # doc / edge counts
+oversight system activities --agent coder --limit 20
+```
+
+### Configuration file
+
+The CLI config lives at:
+
+| Platform | Path |
+|----------|------|
+| Linux / macOS | `~/.config/oversight/config.toml` |
+| Override | `OVERSIGHT_CONFIG_HOME=/path/to/dir` |
+
+Tokens are stored in the OS keyring (libsecret / Keychain / Credential Manager). On systems without a keyring, the CLI falls back to a `chmod 600` file beside `config.toml`.
+
+### Full verb list
+
+The sections below show every verb. For details run `oversight <subcommand> --help`.
+
+- `auth`: `login`, `logout`, `whoami`
+- `config`: `set`, `get`, `list`, `unset`, `use-profile`, `configurations {list,create,describe,delete}`
+- `completion`: `bash`, `zsh`, `fish`, `powershell`, `elvish`
+- `projects`: `list`, `describe`, `create`, `use`
+- `tasks`: `list`, `tree`, `board`, `describe`, `create`, `transition`, `comment`, `update`, `delete`, `assign`, `relate`, `attach`
+- `workflows`: `list`, `describe`, `rules {list}`
+- `agents`: `list`, `describe`, `stats`
+- `inbox approvals`: `list`, `approve`, `deny`
+- `inbox proposals`: `list`, `accept`, `reject`
+- `cycles`: `list`, `describe`, `create`, `update`, `delete`
+- `milestones`: `list`, `describe`, `create`, `update`, `delete`
+- `schedules`: `list`, `describe`, `create`, `update`, `delete`, `run-now`
+- `collections`: `list`, `describe`, `create`, `delete`
+- `docs`: `list`, `describe`, `show`, `create`, `delete`
+- `search <query>`: `--mode lexical/semantic/hybrid`, `--types`, `--limit`
+- `system`: `status`, `stats`, `activities`
+- `init --agent claude|codex|hermes` (legacy CLI agent integration)
+- `run <agent-type> --task T|--title T` (launch a local CLI agent on a task)
+- `worker` (start a worker daemon; distributed mode)

docs/guide/user-manual.zh-CN.md

@@ -1209,3 +1209,175 @@ Oversight 提供 53 个代理可在执行期间使用的工具。工具按类别
 | 工具 | 描述 |
 |------|------|
 | `parse_document` | 按标题层级将 Markdown 文件解析为结构化章节 |
+
+---
+
+## 11. 命令行参考
+
+对于偏好终端操作的用户，Oversight 提供了完整的 `oversight` CLI，覆盖 Web 界面提供的大部分功能。一次安装，即可在 shell 中管理项目、任务、工作流、代理和知识库 —— 输出对管道友好、可脚本化、SSH 安全。
+
+### 快速上手
+
+构建 CLI 二进制：
+
+```bash
+cargo build -p oversight-cli --release
+# 二进制位于 target/release/oversight
+```
+
+首次配置：
+
+```bash
+# 登录（在 ~/.config/oversight/config.toml 中创建带 bearer token 的 profile）
+oversight auth login --username admin
+
+# 设置默认项目，免去后续每次都加 --project
+oversight projects list
+oversight projects use <project-id>
+
+# Shell 自动补全（一次设置）
+oversight completion bash > /etc/bash_completion.d/oversight       # 或 zsh / fish / powershell / elvish
+```
+
+### 全局选项
+
+以下 flag 对所有子命令均可用：
+
+| Flag | 用途 |
+|------|------|
+| `--profile <name>` | 本次调用使用指定 profile |
+| `--server <url>` | 覆盖服务器 URL |
+| `-p, --project <id>` | 覆盖当前项目 |
+| `-f, --format <fmt>` | 输出格式：`auto`（默认）、`table`、`json`、`yaml`、`csv`、`name` |
+
+`auto` 在 stdout 是 TTY 时使用 `table`，重定向/管道时自动切换 `json` —— 因此 `oversight tasks list | jq` 不需要额外 flag。
+
+### 子命令一览
+
+| 命令组 | 作用 |
+|--------|------|
+| `auth` | 登录 / 登出 / 显示当前用户 |
+| `config` | 管理 ~/.config/oversight/config.toml + 多 profile |
+| `completion` | 生成 shell 补全脚本 |
+| `projects` | 列出 / 查看 / 创建 / 设置默认项目 |
+| `tasks` | 12 个任务动词：list/tree/board/describe/create/transition/comment/update/delete/assign/relate/attach |
+| `workflows` | 查看工作流和自动化规则 |
+| `agents` | 浏览代理定义、查看统计 |
+| `inbox` | 处理待审批的工具权限请求；接受/拒绝提案任务 |
+| `cycles` | Sprint / 迭代周期 — CRUD |
+| `milestones` | 发布里程碑 — CRUD |
+| `schedules` | Cron 定时代理任务 — CRUD + run-now |
+| `collections` | 知识库集合 |
+| `docs` | 知识文档（Markdown 内容） |
+| `search` | 跨实体搜索（任务、文档、项目） |
+| `system` | 健康检查、全局统计、代理活动日志 |
+| `init` / `run` / `worker` | 本地 CLI 代理集成（保留的旧路径） |
+
+通过 `oversight <group> --help` 查看任意命令组的详细动词和 flag。
+
+### 常用配方
+
+**整理待办：**
+
+```bash
+oversight tasks list --status backlog --priority P0
+```
+
+**查看看板：**
+
+```bash
+oversight tasks board
+```
+
+**查看功能树：**
+
+```bash
+oversight tasks tree TASK-abc123
+```
+
+**创建并推进任务：**
+
+```bash
+oversight tasks create --title "添加密码重置" --type feature
+# → task-4f2e...
+oversight tasks transition task-4f2e... in_progress
+```
+
+**审批待处理的工具权限请求：**
+
+```bash
+oversight inbox approvals                    # 列出待处理项
+oversight inbox approvals approve <tool-call-id>
+```
+
+**用 `$EDITOR` 给任务写评论：**
+
+```bash
+oversight tasks comment task-4f2e...         # 打开 $EDITOR 编辑 Markdown
+```
+
+**用 `jq` 处理 JSON 输出做脚本：**
+
+```bash
+oversight tasks list --format json \
+  | jq '.[] | select(.status == "backlog") | .id' \
+  | xargs -I {} oversight tasks transition {} ready
+```
+
+**在不同环境间切换：**
+
+```bash
+oversight config configurations create prod --server https://oversight.prod.example
+oversight auth login --profile prod
+oversight --profile prod tasks list         # 一次性覆盖
+oversight config use-profile prod           # 持久切换默认 profile
+```
+
+**搜索知识库：**
+
+```bash
+oversight search "oauth 登录" --types document --limit 10
+```
+
+**监控代理活动：**
+
+```bash
+oversight system status                     # 服务器健康
+oversight system stats                      # 文档 / 边数量
+oversight system activities --agent coder --limit 20
+```
+
+### 配置文件
+
+CLI 配置位置：
+
+| 平台 | 路径 |
+|------|------|
+| Linux / macOS | `~/.config/oversight/config.toml` |
+| 覆盖 | `OVERSIGHT_CONFIG_HOME=/path/to/dir` |
+
+Token 存储在系统 keyring（libsecret / Keychain / Credential Manager）中。无 keyring 的系统上回退到与 `config.toml` 同目录的 `chmod 600` 文件。
+
+### 完整动词列表
+
+下面列出所有动词。详细参数请运行 `oversight <subcommand> --help`。
+
+- `auth`: `login`, `logout`, `whoami`
+- `config`: `set`, `get`, `list`, `unset`, `use-profile`, `configurations {list,create,describe,delete}`
+- `completion`: `bash`, `zsh`, `fish`, `powershell`, `elvish`
+- `projects`: `list`, `describe`, `create`, `use`
+- `tasks`: `list`, `tree`, `board`, `describe`, `create`, `transition`, `comment`, `update`, `delete`, `assign`, `relate`, `attach`
+- `workflows`: `list`, `describe`, `rules {list}`
+- `agents`: `list`, `describe`, `stats`
+- `inbox approvals`: `list`, `approve`, `deny`
+- `inbox proposals`: `list`, `accept`, `reject`
+- `cycles`: `list`, `describe`, `create`, `update`, `delete`
+- `milestones`: `list`, `describe`, `create`, `update`, `delete`
+- `schedules`: `list`, `describe`, `create`, `update`, `delete`, `run-now`
+- `collections`: `list`, `describe`, `create`, `delete`
+- `docs`: `list`, `describe`, `show`, `create`, `delete`
+- `search <query>`: `--mode lexical/semantic/hybrid`, `--types`, `--limit`
+- `system`: `status`, `stats`, `activities`
+- `init --agent claude|codex|hermes`（旧路径：本地 CLI 代理集成）
+- `run <agent-type> --task T|--title T`（在任务上启动本地 CLI 代理）
+- `worker`（启动 worker 守护进程，分布式模式）