命令行总览

yachiyo 命令驱动的是桌面应用用的那同一个本地实例。它大部分直接读写 ~/.yachiyo，所以应用开没开都能用 —— 例外是 send，它需要一个活着的应用。

yachiyo <namespace> <subcommand> [args...] [flags...]

除非命令另有说明，输出都是 JSON。yachiyo <namespace> --help 会打印任意命名空间的详细帮助。

命名空间

命名空间	用途
`soul`	管理演化中的人格特质
`provider`	管理 AI 供应商和模型
`agent`	子智能体运行模式与 ACP 档案
`config`	读写配置项
`thread`	搜索和查看对话历史
`schedule`	管理定时任务和运行历史
`channel`	列出频道用户和群组，设置状态与标签
`send`	发送通知和频道消息
`doctor`	诊断平台运行时、二进制和可用能力

yachiyo doctor 输出便于阅读的平台报告；yachiyo doctor --json 只输出结构化 JSON，可以安全附在 bug 报告里，不会包含供应商密钥、凭据 key、认证文件或完整环境变量。

全局参数

参数	默认	说明
`--settings <path>`	`~/.yachiyo/config.toml`	设置文件路径
`--soul <path>`	`~/.yachiyo/SOUL.md`	灵魂文档路径
`--db <path>`	`~/.yachiyo/yachiyo.sqlite`	数据库文件路径
`--payload <json>`	——	变更类命令的 JSON 请求体
`--limit <n>`	5	列表类命令的最大结果数
`--json`	关	输出原始 JSON 而不是可读文本
`--help`	——	某个命令或命名空间的帮助

有些命令会覆盖 limit 的默认值 —— thread list 用 10，schedule runs 用 20。

路径参数的存在是为了让你把命令行指向一个隔离的环境。设置 YACHIYO_HOME 可以一次性把三个都挪过去，通常更省事。

输出中的密钥

每条命令在打印之前都会把 apiKey 的值替换成 ***，yachiyo config get 也不例外。供应商 API key 存放在本机加密凭据库中，而不是 config.toml，也不会参与同步。

channels.toml 里的频道机器人 token 不在这个打码范围内。

写脚本

--json 让所有东西都变成机器可读的：

# 最近更新的线程，JSON 格式
yachiyo thread list --limit 20 --json | jq '.[] | .title'

# 长时间构建结束时通知自己
make release && yachiyo send notification "Release build done" --title "CI"

`command not found`

先问八千代：

终端里找不到 yachiyo 命令，修一下。

它的 help 技能里有完整的排查路径，也有 shell 权限去执行，包括改你的 shell 配置文件。应用不在你的 PATH 里，并不妨碍这个应用去修你的 PATH。

自己排查

桌面应用每次启动都会写入对应平台的包装脚本，然后尝试让它可被调用。这一步没成功时，看对应平台。

Windows

包装脚本是 %USERPROFILE%\.yachiyo\bin\yachiyo.cmd。应用会以当前用户身份把这个目录加入用户 PATH，不需要管理员权限。

Test-Path "$env:USERPROFILE\.yachiyo\bin\yachiyo.cmd"
($env:Path -split ';') | Where-Object { $_ -like '*\.yachiyo\bin' }

包装脚本存在但第二条命令找不到目录时，重启八千代，让它修复用户 PATH。然后关闭并重新打开 PowerShell、命令提示符或内置 Bash；已经打开的终端仍保留旧环境。最后验证：

yachiyo doctor --json

macOS

1. 包装脚本存在吗？

ls -la ~/.yachiyo/bin/yachiyo

不存在说明应用还没生成它 —— 重启八千代。

2. 软链在吗？

ls -la /usr/local/bin/yachiyo

如果没有，检查这个目录是否存在且可写：

ls -ld /usr/local/bin

你可以手动建这个链接：

sudo mkdir -p /usr/local/bin
sudo ln -sf ~/.yachiyo/bin/yachiyo /usr/local/bin/yachiyo

3. ~/.yachiyo/bin 在你的 PATH 里吗？

echo $PATH | tr ':' '\n' | grep yachiyo

不在的话，应用启动时会把它加进你的 shell 配置文件 —— 检查 ~/.zshrc、~/.bashrc / ~/.bash_profile，或者 ~/.config/fish/config.fish。自己加的话：

export PATH="$HOME/.yachiyo/bin:$PATH"     # zsh / bash

fish_add_path ~/.yachiyo/bin               # fish

无论哪种方式，都需要开一个新终端，或者 source 一下配置文件。