在本机运行 CLI

Syndroo 是一个 Node.js 程序。它读取一个配置文件，在同一状态根目录下保存状态，并通过根据各提供商清单生成的外发策略直接访问平台 API。没有守护进程、计划任务或后台运行。

安装

使用 Node.js 24.19.0 or newer 和 npm。受支持的本地写入需要 macOS 或 Linux。用一条命令安装 0.7.0 版本的 CLI、提供商 SDK 和全部五个官方提供商：

npm install --global @syndroo/[email protected] @syndroo/[email protected] @syndroo/[email protected] @syndroo/[email protected] @syndroo/[email protected] @syndroo/[email protected] @syndroo/[email protected]

运行 syndroo --version。--version 会输出已安装版本和运行它的 Node.js 版本。--help 会输出命令列表，每个命令也会响应自己的 --help。两者在配置文件存在之前即可使用，而且不会创建任何内容。

需要源码构建的贡献者可以按照产品仓库 README 操作；普通读者不需要 checkout 或构建步骤。

配置

只有一个配置来源。未提供 --config 时，CLI 读取 $XDG_CONFIG_HOME/syndroo/config.json，找不到时退回 $HOME/.config/syndroo/config.json。不解析任何提供商的命令允许默认文件不存在；由 --config 指定的文件不存在则视为错误。--config 的路径必须是绝对路径。

{
  "version": 1,
  "stateRoot": "state",
  "providers": {
    "ghost": { "path": "vendor/ghost-provider" }
  }
}

version 必须为 1。stateRoot 和每个 providers.<id>.path 都相对于配置文件所在目录解析，因此切换工作目录不会改变一次运行所使用的状态或插件。未知键会被拒绝；名称类似令牌、密钥、密码或 API 密钥的键会按名称拒绝，不会被忽略。完整契约见配置。

本地状态

状态根目录默认为 $XDG_STATE_HOME/syndroo/runtime-v1，找不到时退回 $HOME/.local/state/syndroo/runtime-v1。它包含一个格式标记；如果根目录缺少标记或标记指向其他格式，运行时会拒绝使用。早期 Syndroo 版本使用不同的根目录；当前运行时不探测、不迁移，也不会删除旧目录。

读取操作从不创建根目录，也不修复它。在从未连接过任何账号的机器上运行只读命令时，状态会报告为未初始化，而不会写出一个目录。

连接一个提供商

每次运行只能使用一个凭证来源：--from-env 读取环境变量 SYNDROO_CREDENTIALS，--credential-file 读取私有 JSON 文件。两者都按严格 JSON 解析，并在保存前按照提供商自己的凭证模式验证。

export SYNDROO_CREDENTIALS='{"identifier":"you.bsky.social","password":"APP_PASSWORD_PLACEHOLDER"}'
syndroo connect bluesky --from-env --label work --default

--label 为连接命名；--default 使它成为目标未指定连接时使用的默认目标。一个提供商可以保存多个连接：再次使用 --connection 连接可刷新现有连接，使用 --update 可修改标签或默认标记，使用 --disconnect 可删除本地连接。断开连接绝不会撤销平台令牌。

机器调用方可以用完整请求文档代替参数来驱动同一命令：--input 读取文件，- 读取标准输入。每个连接步骤都会记录，因此重放相同请求会返回已存储的答案，而不会连接两次。

先准备，再执行

发布内容在发送前会被冻结。准备阶段验证内容和目标，返回预览及一次性审批令牌；执行阶段消耗该令牌。

{
  "type": "prepare",
  "content": { "text": "One document, chosen targets." },
  "targets": [
    { "provider": "bluesky" },
    { "provider": "devto", "options": { "title": "Hello", "body_markdown": "One document." } }
  ]
}

syndroo publish --input post.json --json
syndroo publish --input - < execute.json --json

在终端中，准备阶段会显示冻结的预览并询问 Publish to N accounts? [y/N/v]。接受的回答是 y 或 yes、n 或 no，以及 v 或 view。只有明确的 y 会使用同一令牌执行；v 会展开完整的冻结预览后再次询问，不会重新准备，也不会延长时间窗口；n、空行或输入结束会取消并以退出码 5 结束，不发送内容。其他回答不构成授权，系统会再次询问。--yes 会自动确认当前进程刚刚准备的冻结意图，不再提示。使用 --json 时命令从不提示，只返回准备结果，由调用方决定；使用 --yes --json 时，一次调用完成准备、确认和执行，只输出一个最终信封，不再输出第二个准备结果。显式执行请求只能从标准输入读取；同一进程内的确认或 --yes 不需要在标准输入上另附执行请求；令牌由同一进程族签发和消耗，准备后修改文件不会改变将发送的内容，过期审批或连接绑定发生变化时，旧令牌会被拒绝。

--data 可以内联传入相同请求文档，适合一次性调用，但内容会留在进程参数中。--dry-run 只解析并预览，不写入状态、不解析凭证，也不发起网络请求。--request-id 为调用提供稳定身份，使同一逻辑意图的重试能够被识别。

读取状态

读取操作从不修改或修复状态，也从不联系平台。未提供选择器时，概览会列出提供商可用性、连接数量和最近的操作。

syndroo status --json
syndroo status --connections --json
syndroo status --operation <operationId> --json
syndroo status --operations --limit 20 --json

--provider 查询一个提供商，也可以筛选连接列表。--limit 和 --cursor 仅用于 --operations；获取下一页时，应将不透明游标原样传回。

重试

重试是同一 publish 命令的一种模式，而不是第四个命令：--retry 指定较早的操作，--to 指定要重试的连接，每个目标可重复一次。只有已被确认未应用的失败目标才符合条件。结果为 unknown 的投递绝不能重试：平台可能已经保存了帖子，而 CLI 不会通过再次发送来查明。

syndroo publish --retry <operationId> --to <connectionId> --json

退出码

退出码说明本地调用确认了什么，而不是平台是否接受了帖子。退出码表列出全部七个值，其中最重要的两个是：4 表示写入可能已到达提供商，但结果未知；6 表示执行已经结束，并确认没有完全成功。