命令行参考
hanafubuki-agent 的所有命令、参数和选项。
hanafubuki-agent [选项] [提示词]
hanafubuki-agent [选项] <命令> [参数]不带命令时打开终端界面,提示词作为第一条消息。hanafubuki-agent --help 和 hanafubuki-agent <命令> --help 打印同样的信息,-V(--version)打印版本。
全局选项
全局选项可以写在命令之前或之后,对所有命令有效。
| 选项 | 作用 |
|---|---|
-c、--config 键=值 | 本次运行覆盖 config.toml 的一个键,可重复,后面的优先。值按 TOML 解析,不是合法 TOML 时作为字符串 |
-p、--profile 名字 | 在用户设置之上读取配置档 [profiles.名字];配置文件中没有这个配置档时报错 |
-m、--model 模型 | 新会话(以及恢复的会话)使用的模型,在默认 Provider 上运行,代替模型策略中的模型 |
--role 名字 | 终端界面或 exec 的新会话采用的角色,代替 default;未知的角色报错 |
-C、--cd 目录 | 工作目录:第一个工作区目录;它所在的 Git 仓库根目录决定读取哪个项目配置 |
--add-dir 目录 | 再添加一个工作区目录,可重复 |
--permission-mode manual|auto-review|full-access | 本次运行的权限模式,相当于 -c permissionMode=...,优先于 -c |
--log-level off|error|warn|info|debug|trace | 本次运行的日志级别,相当于 -c logLevel=...,优先于 -c |
--data-dir 目录 | 数据目录(历史、记忆、Skill、日志),代替平台默认位置或 HANAFUBUKI_AGENT_HOME 指定的位置 |
--no-alt-screen | 终端界面把对话写入终端的滚动历史;其他命令忽略它 |
--safe-mode | 以安全模式启动 Agent:只运行核心,不运行任何插件行(disabledPlugins 不变),也不加载任何已安装插件的内容 |
选项中的值使用连字符(auto-review、full-access),而配置文件和 -c
中使用下划线(auto_review、full_access)。
配置的分层和优先级见配置分层。
终端界面
| 命令 | 作用 |
|---|---|
hanafubuki-agent [提示词] | 在新会话中打开终端界面 |
resume [ID] [提示词] | 在终端界面中恢复会话 ID;不给 ID 时打开恢复选择器 |
resume --last [提示词] | 恢复最近一个运行过回合的会话;没有时开始新会话。--last 不能和会话 ID 一起使用 |
--no-alt-screen 让本次运行的界面不使用终端的备用屏幕:对话写入终端的滚动历史(Scrollback),不管 tui.fullscreenTranscript 和 tui.alternateScreen 如何设置。其他命令忽略它。
没有终端时,两者都以退出码 2 退出。见终端界面。
正常退出且有打开的会话时,界面会在恢复终端状态、关闭 Agent 后打印 hanafubuki-agent resume ID。显式指定的 --data-dir 会保留在命令中。见退出。
之前的更新检查发现了更新的版本时,两者都会在 Agent 启动之前先显示更新提示;给出了 提示词 时不显示。选择其中的 Update now 会运行 update,并以 update 的退出码结束程序:更新成功或没有需要安装的版本时为 0,无法更新时为 1;此时不会打开界面。Skip 和 Skip until next version 照常打开界面。
exec
hanafubuki-agent exec [选项] [提示词|-]| 选项 | 作用 |
|---|---|
提示词 | 消息。-,或者不给且标准输入不是终端时,从标准输入读取 |
--json | 每个事件输出一行 JSON |
--approve 策略 | 如何回答审批:deny(默认)、ask、allow:工具[,工具…] |
-o、--output-last-message 文件 | 把回合的最终回答写入文件 |
见 exec 和 exec --json 事件。
config
| 命令 | 作用 |
|---|---|
config path | 打印 config.toml、providers.toml、mcp.toml、数据目录和日志文件的位置 |
config get [键] | 打印应用所有分层后的值:字符串原样输出,其他值输出为 TOML;不给键时输出全部设置。代理 URL 中的凭据显示为 *** |
config set 键 值 | 把一个键写入用户的 config.toml:任何设置、profiles.名字.键、projects."路径".trustLevel。值按 TOML 解析,否则作为字符串;设置的值按它的类型、范围和可选值检查 |
config edit | 用 $VISUAL 或 $EDITOR 打开用户的 config.toml |
见配置。
providers
| 命令 | 作用 |
|---|---|
providers list | 打印模型策略中的模型,以及每个 Provider 的 ID、名称、是否默认、是否禁用、协议、地址、是否设置了令牌和请求头的名字 |
providers add 名称 --base-url URL [--protocol responses|chat-completions|anthropic-messages] [--api-key-env 变量] [--header 名称=值]… [--disabled] | 添加 Provider 并打印它的 ID。协议默认为 responses。令牌从环境变量读取;--header 添加一个请求头。第一个添加的成为默认 Provider |
providers remove ID | 删除 Provider;删除的是默认 Provider 时,默认改为另一个 |
providers default ID [--model 模型] | 设为默认 Provider,并可同时设置模型策略中的模型 |
providers forget ID [--model 模型] | 遗忘该 Provider 的拒绝教给这个模型(或它全部模型)的信息:更小的窗口、不读图、不接受推理参数、不支持结构化输出(遗忘学到的信息);打印有多少个模型有可遗忘的信息 |
见 Provider 与模型。
mcp
| 命令 | 作用 |
|---|---|
mcp list | 打印每个服务器的 ID、是否禁用、传输方式和目标、环境变量或请求头的名字(不打印值);然后是启用的已安装插件运行的服务器,每行以 (plugin ID) 结尾(它们用 plugins 修改,不在这里修改);最后是已设置的凭据 |
mcp add ID --url URL [--oauth disabled|optional|required] [--disabled] | 添加一个 Streamable HTTP 服务器;--oauth 设置它是否用 OAuth 登录(默认 disabled) |
mcp add ID [--env 键=值]… [--disabled] -- 程序 [参数]… | 添加一个 stdio 服务器,-- 之后是程序和参数。启用的服务器添加后立即连接,并打印连接结果 |
mcp remove ID | 断开并删除服务器 |
mcp connect ID | 连接服务器并打印它的状态和工具数量;没有达到 ready 时失败 |
mcp login ID | 用 OAuth 登录服务器:打印要在本机浏览器中打开的 URL,最多等待 5 分钟完成授权,然后打印服务器的状态 |
服务器 ID 只能包含 1 到 128 个字母、数字、-、_ 和 .。凭据需要编辑 mcp.toml,见 MCP。
sessions
| 命令 | 作用 |
|---|---|
sessions list [--archived] [--json] | 列出会话,最新的在前;--archived 列出已归档的;--json 每行一个会话摘要 |
sessions show ID [--json] | 打印会话最近的 200 项记录;--json 输出这一页的 JSON |
sessions archive ID | 归档会话 |
sessions delete ID | 删除会话及其历史 |
见会话。
skills
| 命令 | 作用 |
|---|---|
skills list | 列出 Skill 的 ID、是否禁用和说明;目录中的问题打印到标准错误 |
skills install 目录 [--overwrite] | 安装目录中的 Skill;--overwrite 替换已安装的同名 Skill |
skills remove ID | 删除一个安装的 Skill |
见 Skill。
plugins
已安装插件是 Codex、Claude Code、Cursor 或 Agent Plugins 格式的包:安装并启用后,它们的 Skill、MCP 服务器、hook 和角色加入 Agent。插件来自用户添加的市场(marketplace),或来自一个目录;本项目格式的插件还可以运行代码(编写插件)。模型能看到每个插件提供的内容;插件存放的位置和相关设置见配置参考,它们能做什么、如何失败见插件。
| 命令 | 作用 |
|---|---|
plugins list [--available] [--json] | 列出已安装插件:ID、enabled 或 disabled、版本和来源。--available 改为在每个已添加的市场下列出它的插件(installed, enabled、installed, disabled、not installed、not installable),然后列出不由任何市场提供的已安装插件。--json:{"installed": [...], "marketplaces": [...]} |
plugins add 插件@市场、plugins add 插件 --marketplace 市场 | 安装市场中的插件并启用它([plugins."插件@市场"] enabled = true);打印它的根目录、读取时略过的内容、由命令转换成的 Skill,以及有多少 hook 等待信任(用 /hooks 或 /plugins 信任)。--json 打印完整结果 |
plugins add 目录 [--marketplace 名字] | 安装目录中的插件,归入市场 名字(不指定时为 local):它的 ID 是 <清单中的名字>@local |
plugins remove ID [--purge-data] | 卸载插件并删除它的 [plugins] 条目;除非加 --purge-data,它的数据目录会保留。已链接的插件被取消链接,目录保留 |
plugins enable ID、plugins disable ID | 启用或停用一个已安装插件;所属市场被关闭的插件不能启用 |
plugins update ID | 从插件的市场(按市场当前的内容;git 市场先升级)或它原来的目录重新安装;内容变化的插件的 hook 需要重新信任。已链接的插件被拒绝:它从不更新 |
plugins info ID [--json] | 显示插件:状态、版本、格式、来源、它的 Skill、MCP 服务器、hook 和角色、等待信任的 hook、它的代码的状态(等到命令自己的 Agent 启动了它,最多 30 秒;code: running、blocked 等;安全模式下或 plugins 行停用时立即显示 stopped)以及问题 |
plugins retry ID | 重新加载已安装插件,代码失败时重新启动它,并像 info 一样,在代码启动后显示该插件 |
plugins grant ID | 授予插件代码其清单请求的权限(网络、工作区、环境变量)并打印它们;程序访客在获得授权前处于 blocked 状态;WebAssembly 访客不需要授权,对它执行此命令会失败 |
plugins settings ID [--get]、plugins settings ID --set JSON | 打印插件代码的设置([plugins."ID"].settings)和它的 configSchema;--set 用一个按 schema 检查的 JSON 对象替换设置,--set null 删除它们;访客会带着新设置重新启动 |
plugins new 名字 [--lang rust|python] [--target process|wasm] [--dir 目录] | 在 目录(默认 ./名字)中创建一个带代码的插件:package/ 中的包(声明一个工具等贡献、权限和 configSchema 的清单),以及用 kardia-guest 或 pykardia 编写的访客源码;--target wasm(仅 Rust)写出构建 WebAssembly 模块的 crate(编写插件) |
plugins validate 目录 [--run] [--json] | 像安装那样检查 目录 中的插件,并像 Agent 运行它那样检查它的代码;--run 还会把它安装到临时主目录、授权并启动它的访客。有任何问题或访客没有运行时退出码为 1(检查) |
plugins dev 目录 [--grant] | 把 目录 中的插件安装为 名字@local 并启用,询问是否授予它的代码请求的权限(--grant 直接授予),然后每当它的文件改动就重新安装,直到 Ctrl+C(开发) |
plugins link 目录 [--marketplace 名字] [--json] | 把 目录 中的插件链接为 名字@local(或归入市场 名字)并启用:目录就是包,不复制、不以内容哈希固定,列出时来源为 linked 目录;运行中的 Agent 在每次改动后重新读取它并重启它的代码(链接)。已安装的 ID 会被拒绝,plugins add 也拒绝已链接的 ID;plugins remove 取消链接 |
plugins marketplace add 来源 [--ref 引用] [--sparse 路径]… | 添加一个市场:本地目录(原地使用),或 git 仓库(owner/repo[@ref]、HTTPS 或 SSH URL、file://),克隆到数据目录的 plugins/marketplaces/ 下;--sparse 只检出这些路径。再次添加相同来源不会有任何变化 |
plugins marketplace list [--json] | 列出已添加的市场:名字、local 或 git、on、off 或 unreadable,以及根目录 |
plugins marketplace upgrade [名字] | 把 git 市场 名字(或所有已添加的 git 市场)更新到远程的最新提交;其中已安装的插件保持不变,直到执行 plugins update |
plugins marketplace remove 名字 | 删除市场(以及 git 市场的检出);从它安装的插件仍然保留 |
插件 ID 是 插件@市场。命令行中 --marketplace 没有简写 -m:-m 是全局的 --model。
memory
| 命令 | 作用 |
|---|---|
memory status | 打印记忆是否启用、读过的会话数、提取的记忆数、运行中的任务和最近的错误 |
memory reset | 忘记记忆中的所有内容 |
见记忆。
roles
| 命令 | 作用 |
|---|---|
roles list | 按名字列出每个角色:它的来源和描述的第一行(不可派生时加 (not spawnable)),或 unusable: 及原因;读取和解析角色时的问题输出到标准错误 |
roles show 名字 | 打印角色的来源和继承链,然后是继承链解析后的每个字段,以及决定它的角色([from reader, explorer]);不可用的角色打印原因。没有任何来源定义的名字以 1 退出 |
-p 会同时读取配置档的角色。两个命令都列出开启的已安装插件的角色(插件的角色),--safe-mode 时不列出;两个命令都不启动 Agent,读取插件时也不向它们的目录写入任何东西。会话用全局的 --role 名字 或终端界面中的 /role 名字 取得角色。见角色。
doctor
| 命令 | 作用 |
|---|---|
doctor | 检查配置、沙箱、Provider、MCP 服务器、角色、密钥环和数据目录,每项一行;有 FAIL 时以退出码 1 退出 |
doctor --online | 还会启动 Agent,列出默认 Provider 的模型及对每个模型所知道的信息(每个模型一行 model,取自列表调用本身的回答:窗口、最大输出、思考(已知时列出档位)和视觉,各自附上来源:configured、learned、reported、models.dev 或 built-in,如 gpt-5.1: window 272000 (built-in)),并连接每个启用的 MCP 服务器 |
见故障排查。
update
| 命令 | 作用 |
|---|---|
update | 按这个可执行文件的安装方式(见下文)把它更新到最新发布版本:步骤输出到标准错误,结果输出到标准输出 |
update --check | 只查询并报告最新发布版本:当前版本、最新版本、可执行文件、安装方式、发布说明,以及 update 会做什么。不下载二进制文件、不更改安装 |
update --force | 最新发布版本与当前版本相同时也重新安装。任何情况下都不会安装更旧的版本:比最新发布版本还新的构建保持不变 |
--check 会把成功的查询结果保存到 TUI 启动时读取的更新缓存,即使原缓存尚未过期也会刷新;查询失败时保留原缓存。从设置中检查还会刷新当前 TUI 的会话信息框。
同时使用 --check 和 --force 是用法错误(退出码 2)。
$ hanafubuki-agent update --check
Current version 0.2.0
Latest release 0.3.0
Executable /home/me/.local/bin/hanafubuki-agent
Installed as a released binary
Release notes https://github.com/licyk/hanafubuki-agent/releases/tag/v0.3.0
An update is available: run `hanafubuki-agent update` to install 0.3.0.
$ hanafubuki-agent update
Updating hanafubuki-agent 0.2.0 → 0.3.0 at /home/me/.local/bin/hanafubuki-agent
Downloading hanafubuki-agent-0.3.0-x86_64-unknown-linux-gnu.tar.gz: 18.9 MiB: done
Verifying the SHA-256 digest: ok
Checking the new executable: hanafubuki-agent 0.3.0
Installing: done
Updated to 0.3.0. The next start of hanafubuki-agent runs it; running ones keep 0.2.0 until they restart.在终端中,下载进度在同一行原地刷新;否则只打印开始和结束两行。
具体做法取决于可执行文件的安装方式:
- 发布的二进制:把最新发布版本中本平台的归档(
hanafubuki-agent-VERSION-TARGET.tar.gz,Windows 上是.zip)下载到可执行文件旁边新建的隐藏目录(.hanafubuki-agent-update-…)中,并按 GitHub 给出的大小和 SHA-256 摘要校验;没有摘要的发布会被拒绝。只按确切路径(hanafubuki-agent-VERSION-TARGET/hanafubuki-agent)从中取出可执行文件,它必须在 10 秒内用新版本号回答--version,这同时能发现其他架构的构建,以及 Linux 上低于 2.35 的 glibc。然后用一次重命名把它放到位:从不写入已安装的可执行文件,这最后一步之前的任何步骤都不会碰它。通过符号链接运行时,替换的是链接指向的文件,链接保持不变。在 Windows 上,正在运行的可执行文件不能被替换,所以先把它重命名为旁边的hanafubuki-agent.exe.NUMBER.outdated(新文件放不到位时会改回来);没有进程再运行它之后,下一次更新或终端界面的下一次启动会删除这个文件。 cargo install:在 Linux 和 macOS 上运行cargo install --locked hanafubuki-agent-cli(可执行文件不在 cargo 的默认安装根目录时带上--root),在一个临时目录中运行,这样任何项目的 cargo 设置都不会生效,并显示 cargo 自己的输出;然后询问可执行文件的版本,从而发现 cargo 把它装到了别处(CARGO_INSTALL_ROOT、install.root)的情况。在 Windows 上只给出这条命令。- 从检出的源码构建(
target/debug、target/release、cargo install --path)、没有写权限的目录,或没有发布构建的平台:说明应该怎么做,并以退出码 1 退出。
失败时会说明保留了什么,通常是 “nothing was changed”:此时可执行文件保持原样。被中断或杀掉的更新最多留下它的隐藏目录,下一次更新会删除它。
同一时间只有一个更新:一个更新运行时,同一个可执行文件的另一个更新会被立即拒绝(锁是可执行文件旁边的 .hanafubuki-agent.update.lock 文件,更新后保留)。发现可执行文件已经是最新版本(另一个进程更新了它)的更新不会下载任何东西。
update 不启动 Agent,也不获取数据目录的锁,所以可以在 Agent 运行时使用。正在运行的 Agent 保持原来的版本直到重启,下次启动运行新版本;在此期间,它们的沙箱命令会启动该路径上的可执行文件,也就是新版本(内部实现)。
发送的内容:GET https://api.github.com/repos/licyk/hanafubuki-agent/releases/latest,带 Accept: application/vnd.github+json、User-Agent: hanafubuki-agent/VERSION,设置了 GITHUB_TOKEN 时还带上 Authorization: Bearer 和它的值(环境变量);然后从 GitHub 回答中给出的地址下载归档(GitHub 会把它重定向到下载主机),不带令牌。每个请求和每次重定向都是 HTTPS。两者都经过 network.proxy;配置无法读取时只给出警告,并使用系统代理。调试构建只会在 HANAFUBUKI_AGENT_TEST_RELEASE_URL 查询发布。
更新成功或没有可安装的版本时以 0 退出,无法更新时以 1 退出(退出码)。另见更新。
哪些命令会启动 Agent
config、providers list、roles 和不带 --online 的 doctor 只读写配置(roles 和 doctor 还会读取已安装插件,但不在那里写入任何东西),update 只读取其中的代理;它们都不启动 Agent,可以在另一个 Agent 进程运行时使用。其他命令会启动 Agent,包括 mcp list。它们可以与其他实例共享数据目录;打开或修改已由另一实例持有的会话会被拒绝(并发 Agent)。终端界面的更新提示出现在 Agent 启动之前:选择 Update now 会结束程序,不启动 Agent。
每个命令都会先读取配置,再安装崩溃处理和日志文件,然后才启动 Agent 或修改任何内容。会启动 Agent 的管理命令也会像每次启动一样在后台连接启用的 MCP 服务器。
除 exec 和终端界面外,按 Ctrl-C 会立即结束命令:操作系统释放数据目录锁,下次启动时清理 Agent 启动过的进程。