HiFox CLI
HiFox CLI 是在终端中使用 HiFox 的命令行工具。它既是人类在命令行里管理 HiFox 的入口，也是 Agent、脚本和自动化流程操作 HiFox 的入口。
通过 CLI，你可以创建任务、修改任务状态、添加评论、指派给成员 / Agent / 小队、查询组织资源，也可以在本机或远程电脑上连接本地服务，让 Agent 在这台电脑上执行任务。
如果你只是日常在网页或桌面端里创建任务、查看看板，不一定需要直接使用 CLI。通常在这些场景下会用到 CLI：
- 让 Agent 或脚本创建任务、更新任务状态、添加评论和读取任务上下文；
- 在终端中管理任务、Agent、项目、仓库、Skill 等资源；
- 在远程服务器上连接一台电脑；
- 检查本机本地服务状态和日志；
- 配置自托管或非默认 HiFox 服务地址；
- 排查电脑离线、本地服务未启动或运行时未检测到的问题。
安装前需要准备什么？
安装和使用 CLI 前，建议先确认：
- 你有 HiFox 账号；
- 电脑可以访问 HiFox API；
- 如果要让 Agent 在这台电脑上执行任务，电脑上至少安装了一个支持的 AI 编程工具，例如 Claude Code、Codex、Gemini、OpenClaw、Hermes、Cursor Agent 或 GitHub Copilot CLI；
- 如果要访问代码库，电脑上的 Git 凭证、SSH key、包管理器和内部网络访问已经准备好。
CLI 本身只负责连接和调度。真正读代码、改文件和运行命令，发生在本地服务启动的 Agent 运行时中。
安装 CLI
macOS / Linux
可以使用安装脚本安装：
默认会安装到 $HOME/.local/bin，并在需要时把这个目录加入 shell 启动文件。
安装程序可以更新启动配置，但通过 curl | bash 运行时，子进程不能修改启动它的当前 shell。安装结束时如果当前 shell 尚未包含安装目录，程序会输出一条可复制的 export PATH=... 命令。执行这条命令，或重新打开终端后，再运行 hifox version。
如果当前终端仍然提示找不到 hifox，可以检查命令发现和默认安装路径：
如果安装时使用了 --dir 指定目录，请把示例中的 $HOME/.local/bin 换成实际目录。
也可以指定安装目录，例如：
安装脚本会在执行安装逻辑前清理 BASH_ENV，所以复制命令不需要额外的 shell 环境清理参数。
安装脚本会自动识别系统和架构，下载对应包并校验 checksum。macOS 和 Linux 支持 amd64 / arm64；macOS Intel 会使用 universal 包。
安装完成后，可以检查版本：
Windows
Windows 可以使用 PowerShell 安装：
默认会安装到：
安装脚本会尝试把安装目录加入用户 PATH，并更新当前 PowerShell 会话的 PATH。
当前 Windows 安装脚本支持 Windows AMD64，不支持 Windows ARM64。
更新 CLI
macOS、Linux 和 Windows 都可以用：
当前 Windows 安装包仍是 AMD64。不要按内部下载地址或 checksum 流程手改安装文件。
登录 CLI
CLI 登录使用 个人访问令牌。当前 CLI 不使用浏览器登录流程。
推荐先在 HiFox 中创建一个个人访问令牌，然后运行：
CLI 会提示你粘贴令牌。也可以直接传入：
登录成功后，CLI 会验证令牌、保存到当前 profile，并尝试发现你所在的组织。如果当前 profile 还没有默认组织，CLI 会自动设置一个默认组织。
检查当前登录状态：
退出当前 profile 的登录：
注意：auth logout 只会移除本机保存的令牌，不会吊销服务端的个人访问令牌。如果要让令牌彻底失效，请到 设置 → 个人访问令牌 中删除对应令牌。
一步完成配置和启动
如果你是在自己的电脑上使用个人访问令牌连接 HiFox，可以使用 setup 流程：
它会完成这些动作：
- 配置 HiFox Cloud 服务地址；
- 提示你输入个人访问令牌；
- 验证账号并保存登录信息；
- 发现并设置默认组织；
- 启动本地服务。
如果已有服务地址配置，CLI 可能会询问是否覆盖。
自托管环境可以使用：
也可以先手动配置地址，再登录：
使用安装令牌连接电脑
如果你是在 HiFox 网页或桌面端里点击“连接电脑”，通常会得到一条带安装令牌的命令。这个流程应使用 computer register，而不是 login --install-token。
示例：
连接成功后，CLI 会：
- 为本机创建或复用本地电脑身份；
- 用安装令牌向 HiFox 交换电脑会话；
- 写入电脑会话元数据和密钥；
- 保存电脑连接信息；
- 尝试启动或重启本地服务，让这台电脑上线。
安装令牌通常有有效期，并且只能使用一次。如果提示令牌无效、过期或已使用，请回到 HiFox 重新生成连接命令。
安装令牌和个人访问令牌不同：
查看本地服务状态和日志
常用本地服务命令：
查看结构化状态：
查看最近日志：
持续跟随日志：
遇到电脑离线、任务不运行、运行时检测不到等问题时，优先查看：
如果需要前台运行、停止、重启或清理本地服务，可以使用高级 daemon 命令。这里的 daemon 指本地服务背后的进程。
检查磁盘占用和清理
Agent 执行任务会创建工作目录、缓存和运行产物。你可以用 CLI 查看本地服务管理目录的磁盘占用：
按组织查看：
清理过期或可清理的运行产物：
不加 --confirm 只预览，不会真正删除。
桌面端本地服务或电脑设置里还可以改清理频率、终态运行保留天数和最低可用空间。保存后需要重启本地服务，策略才会生效。CLI 手动清理和界面策略是互补的，不是互相替代。自动清理只会处理已完成 / 已取消等安全候选，不会删除进行中、排队、pinned 或仍需排查的运行，也不会自动清理 ~/.claude/worktrees。
清理前建议确认没有重要任务仍在运行，也不要手动删除不理解的本地服务目录。
配置 CLI
查看当前配置：
常见配置项：
这些 key 使用 camelCase：serverUrl、appUrl、organizationId。
配置默认保存在 HiFox 的本机配置目录中。普通用户不需要手动编辑配置文件，优先使用 hifox config show 和 hifox config set。
Profile 是什么？
Profile 是 CLI 的本机配置上下文。不同 profile 可以保存不同登录信息、服务地址、组织上下文或电脑连接信息。
常见情况：
- 默认 profile：你直接使用
hifox login --token或hifox setup --token时使用； - 电脑会话：通过
hifox computer register --install-token ...创建，本地服务使用隐藏的电脑会话状态，不依赖人工登录的 profile； - 指定 profile：使用
--profile参数切换。
例如：
排查“我明明登录了但本地服务还是离线”时，要注意人工登录 profile 和电脑会话是两条路径。个人访问令牌只提供人工 CLI 访问；本地服务上线需要通过安装令牌完成电脑会话配置。
环境变量
CLI 会优先读取 HiFox 专用环境变量，也兼容部分 APP_* 通用变量。
常用变量：
对于 token、server URL 和 organization ID，命令行参数或环境变量通常会覆盖 profile 中的配置。
用 CLI 操作 HiFox 资源
CLI 不只是用来连接电脑。它也是 Agent、脚本和自动化流程操作 HiFox 的稳定入口。
例如，Agent 在执行外部流程时，可以通过 CLI 把进展写回任务；脚本可以批量创建任务、更新状态、添加评论，或读取组织中的 Agent、项目和仓库信息。
任务操作
普通任务、缺陷或需求请使用 hifox task create。hifox request create 只用于客户请求，且需要组织已开启客户请求。
常见任务命令包括：
创建任务时，可以继续指定优先级、处理人、项目、父任务、截止日期和附件：
修改任务时，可以更新标题、正文、状态、优先级、处理人、项目、父任务和关注状态：
也可以直接向既有任务附加本地文件，而不创建评论：
--attachment 支持逗号分隔或重复传入，按输入顺序上传。若中途失败，已成功上传的附件会保留在任务上，命令会以非零退出提示结果；不会自动重试或清理。
常用状态别名包括：backlog、todo、in_progress、in_review、done、blocked、cancelled。实际可用状态仍取决于组织和空间里的任务工作流配置。
可以按任务最近一次进入当前状态的时间筛选：
--status-changed-since 是包含下界，--status-changed-before 是不包含上界；两者都接受 RFC 3339 时间戳。--status-changed-within 接受正整数加 m、h 或 d，按服务端 UTC 当前时间计算，7d 表示连续的 7 × 24 小时，且不能与显式边界同时使用。历史任务若没有可观测的状态变更时间，JSON 中的 statusChangedAt 为 null，不会从创建或更新时间推断，并会自然排除在带时间边界的查询之外。
也可以按自定义字段精确筛选：
--field 写成 字段引用=值，可重复指定。字段引用可以是自定义字段 UUID，或当前组织内唯一匹配的字段名称。名称不唯一、字段不存在或对当前账号不可见时，命令会失败并提示改用 UUID，不会猜测。
多个 --field 之间为 AND，可以和 --status、--assignee、--project 等已有条件一起用。筛选在服务端分页之前完成，--limit / --offset 基于筛选后的结果集。--output json 的结构保持兼容，任务仍返回已有的 customFields。
当前是类型感知的精确匹配：
- 文本 / URL：完整字符串相等；
- 数字：数值相等；
- 布尔：
true/false； - 日期：
YYYY-MM-DD； - 单选 / 多选：选项 UUID，或组织内唯一的选项名；多选条件表示任务包含该选项；
- 成员：与现有 CLI 人员引用一致。
任务没有该字段值时，不匹配相等条件。
评论和上下文
Agent 或脚本写回执行结果时，通常使用任务评论：
如果内容来自管道，可以使用标准输入：
也可以读取任务评论，作为自动化或 Agent 的上下文：
Resolve / reopen 讨论 thread
可以将任务中的讨论标记为已解决，或重新打开已解决的讨论：
any-comment-id 必须是完整 UUID，可以是讨论根评论或其任意回复。CLI 会先读取目标任务的 canonical ID，再在该任务范围内通过 --thread <any-comment-id> --tail 0 找到唯一根评论，并只对该根评论写入 resolved: true 或 resolved: false。因此跨任务、孤儿、无效或无法上溯的评论 ID 会失败，且不会发出状态写入。
默认输出为 PATCH 返回的 JSON 评论对象；使用 --output text 时，成功提示写到 stderr。命令是目标状态收敛的，但重复调用仍可能更新审计时间和 activity；网络错误后不要盲目重试，应先读取 thread 状态确认。Agent execution 仍只能 resolve/reopen 自己 authored 的根评论，其他根会由服务端返回 403。两个命令都不会删除评论。
JSON 输出
很多资源命令支持 --output json。这对 Agent 和脚本很重要，因为 JSON 比表格输出更适合解析。
例如：
如果命令用于自动化，建议优先使用 JSON 输出，并显式传入组织上下文：
常用命令族
可以用 help 查看当前版本支持的完整子命令：
常见命令族包括：
不同版本的 CLI 可能会增加或调整命令。以 hifox <command> --help 输出为准。
常见问题
CLI 支持浏览器登录吗？
当前 CLI 登录使用个人访问令牌。先在 HiFox 中创建个人访问令牌，再运行 hifox login --token 或 hifox setup --token。
login --install-token 为什么失败？
安装令牌不再用于 login。连接电脑时请使用：
本地服务已经启动，为什么 daemon start 报错？
如果当前 profile 的本地服务已经在运行，CLI 不会重复启动。可以用：
确认状态，或者用：
重启本地服务。
电脑在线但没有可用运行时怎么办？
检查这台电脑上是否安装了支持的 AI 编程工具，并确认它们在本地服务运行用户的 PATH 中可用。部分 Runtime 需要安装 CLI 版本，而不是桌面应用；按电脑详情页的提示安装。如果提示 Runtime 未登录或未授权，按页面给出的命令在目标电脑终端完成该 Runtime 的登录，不要把它和 hifox login --token 混成一步。安装后可以重启本地服务：
修改 PATH 后本地服务还是检测不到工具怎么办？
本地服务可能没有继承你当前终端的最新环境。重启本地服务，并确认工具可以被登录 shell 找到。必要时使用对应的 HIFOX_*_PATH 环境变量指定工具路径。
auth logout 会让电脑下线吗？
不一定。auth logout 只清除当前 profile 的个人令牌。通过安装令牌连接的电脑使用独立的电脑会话，不等同于你的个人登录。要让电脑下线，通常需要停止本地服务或在 HiFox 中删除/断开电脑。
自托管地址应该配置哪个？
serverUrl 是 CLI 和本地服务调用 API 的地址，通常是后端 API 地址。appUrl 是打开网页或认证相关页面时使用的前端地址。