hanafubuki-agent

命令行参考

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 启动过的进程。

本页目录