# @bufferapp/cli 中文文档 规范地址：https://npmcn.com/package/%40bufferapp/cli/ 版本：2\.2\.0 npm 元数据更新时间：2026-11-02T19:56:26.729Z 中文译文更新时间：2026-11-08T19:25:09.783Z 软件包许可：ISC 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40bufferapp/cli 原文对照：https://npmcn.com/package/%40bufferapp/cli/?lang=original 项目主页：https://developers.buffer.com/guides/cli ## 关键信息（来自 npm 元数据） - 包体积（解压后）：2.3 MB，201 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - 运行依赖：2 个 - 首次发布：2026-04-21T08:25:09.132Z - 最新版本发布：2026-11-02T19:56:26.495Z - 近 30 天下载量：3422（2026-10-09 至 2026-11-07，npm 官方下载统计） - 已发布版本数：16（近 12 个月 16 个） ## 中文简介 用于缓冲器的CLI,为AI代理和人类设计 ## 安装 ```sh npm install @bufferapp/cli ``` 也可以使用：`pnpm add @bufferapp/cli`、`yarn add @bufferapp/cli`、`bun add @bufferapp/cli` ## README # 缓冲 CLI Buffer API的指令行界面,为人和AI代理设计. 所有输出都是JSON,所有错误都是结构化的,每个命令都是由公共GraphQL schema产生的. ## 安装 ```bash npm install -g @bufferapp/cli buffer --version ``` pnpm, Yarn, Bun, 和 Vite+ 工作: ```bash pnpm add -g @bufferapp/cli yarn global add @bufferapp/cli bun add -g @bufferapp/cli vp install -g @bufferapp/cli ``` `buffer update` 检测用于安装 CLI 的软件包管理器并运行匹配的全局更新命令,因此无论您是如何安装的,升级流程保持不变. 过 `--verbose` 在摘要中包含检测到的软件包管理器. 需要节点.js 18或以后. ## 快开始 ```bash # 1. Install npm install -g @bufferapp/cli # 2. Authenticate (recommended). Interactive setup writes your API key, # default organization, and timezone to global config, then offers # to install the agent skill into Claude Code or Codex. buffer init # 3. Verify setup buffer doctor # 4. Run a command buffer account buffer channels list ``` 不愿坚持磁盘的API密钥(CI,容器,麻黄膜)? 跳过 `buffer init` 设置 `BUFFER_API_KEY` 相反——见 [认证](https://npmcn.com/package/%40bufferapp/cli/#readme-authentication)时生成 API 密钥 [https://publish.buffer.com/ settings/api 页面存档备份,存于互联网档案馆](https://publish.buffer.com/settings/api)。 。 。 . ## 认证 `buffer init` 是建议设置。 它会将您的 API 密钥写入全局配置, 并附带默认的组织和时区, 然后提供安装代理技能 。 生成 API 密钥 [https://publish.buffer.com/ settings/api 页面存档备份,存于互联网档案馆](https://publish.buffer.com/settings/api)。 。 。 . ```bash buffer init ``` CLI 还接受来自 `BUFFER_API_KEY` 环境变量。 支持 CI, 容器, 以及任意使用磁盘的 API 密钥是不可取的—— 当两者都存在时, 它优先于配置文件 . ```bash export BUFFER_API_KEY=your-api-key-here ``` 分辨率命令 : `BUFFER_API_KEY` → `apiKey` 在全局配置文件中。 首个非null API 键取胜. 缺少或无效的 API 密钥生成退出代码 `4` 在 Stderr 有结构错误。 正则命令从不交互提示证书——只限 `buffer init` 是交互式的,并且是选入的. 为了安全起见, `apiKey` 仅在 **全球** 配置文件 。 试图将其写入可重复扫描的配置的尝试被拒绝. ## 使用量 ```bash buffer --help buffer --version buffer [flags] ``` 见 [Schema 反思](https://npmcn.com/package/%40bufferapp/cli/#readme-schema-introspection) 下面为程序化发现命令. ### 示例命令 ```bash # Account info buffer account # Channels buffer channels list buffer channels get --id # Posts (queries) buffer posts list --channel-id buffer posts get --id # Posts (mutations, flags) buffer posts create --channel-id --scheduling-type automatic --mode addToQueue --text "Hello" # Posts (mutations, JSON) buffer posts create --json '{"channelId": "...", "schedulingType": "automatic", "mode": "addToQueue", "text": "Hello"}' # Ideas (mutations, flags) buffer ideas create --organization-id --text "Idea body" # Ideas (mutations, JSON) buffer ideas create --json '{"organizationId": "...", "content": {"text": "Idea body"}}' # Idea Groups buffer ideaGroups list --organization-id ``` 输入也可以来自文件或 stdin: ```bash buffer posts create --input post.json cat post.json | buffer posts create --input - ``` ### 干线运行 所有突变支持 `--dry-run`,以验证本地输入并打印有效载荷 _将_ 在不发出API呼叫的情况下发送 : ```bash buffer posts create --json '{"channelId": "abc"}' --dry-run ``` ### 请求超时 使用 `--timeout ` 绑定任何命令会等待API多久。 默认为30000ms(30s). 过 `0` 以禁用长期运行的超时 : ```bash # Custom timeout (5s) buffer posts list --timeout 5000 # Disable the timeout buffer posts create --json '{...}' --timeout 0 ``` 当超时点火时,请求被中止,CLI以代码3退出,并在stderr上发出类似消息 `Request timed out after 5000ms`设置默认值 `buffer config set timeout 60000`。 。 。 . ## 检查张贴限制 使用 `buffer dailyPostingLimits list --channel-ids "$channelId" --date "2026-05-05T15:00:00Z"` 在排出时间之前 以时区通过预定的张贴时间戳; 省略 `--date` 现在检查。 就X而言,结果计入了受拟议员额影响的最繁忙的24小时滚动窗口中的现有员额,包括后来排定的员额。 其他网络使用频道的本地日历日. `isAtLimit` 说明是否将再增加一个员额. ## 产出 - 全部命令输出为 JSON 为 stdout; 错误转到 stderr - 中继连接被平整——回复返回 `{ items, pageInfo }` 而不是说 `edges`编号 :`node` 包装 - 每艘指挥舰都配有舰长 **默认字段集** 因此,反应保持小,没有 `--fields`。通过 `--fields` 用逗号分隔的点注释路径列表来覆盖默认值。 CLI 从这些路径构建一个最小的 GraphQL 请求, 因此 API 只返回您想要的 . ```bash # Default subset (small, still useful) buffer posts get --id post_123 # Cherry-pick fields, including nested paths buffer posts get --id post_123 --fields id,text,channel.name # Connections expose items.* and pageInfo.* buffer posts list --fields items.id,items.text,pageInfo.endCursor # Brace expansion for sibling fields under a common prefix. # Quote the value so the shell does not expand the braces itself. buffer posts list --fields 'items.{id,text,status},pageInfo.endCursor' # Nested groups work too — keep them quoted. Brace must be the last # token of a path; cross-products like `{a,b}.{x,y}` are rejected. buffer posts list --fields 'items.{id,channel.{id,name}}' # Opt back into the full response buffer posts get --id post_123 --fields all ``` > **引用 `--fields` 当你使用牙套.** Bash和zsh自己做支架扩张:未引用 `items.{id,text}` 成为两个论据(`items.id items.text`在CLI见过之前 将值以单引号包入( E)`--fields 'items.{id,text}'`),所以字形字符串会达到CLI的剖面. 运行 `buffer schema describe ` 来看看 `defaultFields` (返回时无 `--fields`和 `selectableFields` 任何命令. > **偏爱 `--fields` 在管道到 `jq`。 。 。 .** 过滤方式 `jq` 仍然支付通过网络和响应解析器获取每个字段的费用. `--fields` 缩写 GraphQL 请求本身,所以 API 跳过工作, 反应仍然很小 。 使用 `jq` 为了改造已经发射的JSON 而不是你不需要的修剪地盘. ### 输出格式和记录旗 每个命令上都有四个全局旗帜控制渲染和斯德尔噪声: - `--output ` 覆盖 `outputFormat` 一个引用的配置. `auto` (默认) 漂亮的指纹到 TTY , 并释放 JSON 其他; `--output json` 是脚本和特工的安全选择. - `--quiet` 压制非必需的标尺——飞行自旋器,后一秒完成线,可更新通知,和限速警告. Stdout没有受到影响。 当 Stderr 不是一个 TTY 或 `NO_COLOR` 设置在环境中. - `--verbose` 在每个请求后打印出一行速率限制摘要。 没有它,只报告低于低残留阈值的政策. - `--no-color` 在漂亮输出中禁用 ANSI 颜色 。 这个 `NO_COLOR` var (任何值) 和 `CLICOLOR=0` 做相同的; 非 TTY stdout 自动禁用颜色, 如 `TERM=dumb`设置 `FORCE_COLOR=1` (或 `CLICOLOR_FORCE=1`)在接通处理它们的寻呼器时保持颜色. ### 退出代码 | 代码 | 含义 | | --- | --- | | 0 个 | 成绩 | | 1个 | 一般错误 | | 2个 | 用法出错( 不良旗帜、 缺失字段、 验证失败) | | 3个 | API 错误 | | 页:1 | 认证错误( 丢失或无效的 API 密钥) | | 130个 | 被SIGINT中断(Ctrl-C) | | 143国 | 由SIGTERM终止 | 当CLI的stdout管被消费者关闭(例如. `buffer ... | head`), CLI 默默地退出 0 而不是打印出一个 EPIPE 堆栈跟踪. ### Schema 反思 ```bash buffer schema list buffer schema describe posts create ``` `buffer schema describe` 返回全方法签名为 JSON — 输入类型、输出形状、需要的字段、enum 值。 在执行前用它来发现命令并验证有效载荷. ### 壳完成 CLI 打印完成脚本 `bash`, (中文(简体) ), `zsh`,或 `fish`。通过 `--install` 自动把它接上; 没有它,脚本就转到 stdout 以便你能够 `eval` 或自吹自擂,或自吹自擂. ```bash # Install for the current shell (idempotent) buffer completion bash --install buffer completion zsh --install buffer completion fish --install # Or install manually by capturing the script buffer completion bash > /etc/bash_completion.d/buffer buffer completion zsh > "${fpath[1]}/_buffer" buffer completion fish > ~/.config/fish/completions/buffer.fish # Or source it on the fly (bash/zsh) eval "$(buffer completion zsh)" ``` `--install` 附加一个来源块到 `~/.bashrc` 或者说 `~/.zshrc`,标记为 `# buffer cli completion` 所以,重跑是一个不op。 对于鱼 它直接写剧本给 `~/.config/fish/completions/buffer.fish`重新打开你的外壳(或 `source` rc文件)来取取. ### 代理上下文 CLI舰艇的减分技能文件(工作流程、陷阱、速率限制、一能、启动) 编码了超出什么的变数 `--help` 财务报告和审定财务报表 `buffer schema describe` 可以表达 它们被设计成被装入AI代理的上下文窗口. ```bash buffer context # all topics, concatenated markdown buffer context workflows # one topic buffer context --list # topic name + one-line summary buffer context --output json # structured envelope for programmatic use ``` 这些命令不需要 API 调用, 也不需要 认证 . ### 管理代理技能 在您的代理机中安装缓冲技巧, 这样它就可以调用 CLI , 而无需自定义系统提示 : ```bash buffer agent install claude # writes ~/.claude/skills/buffer/SKILL.md buffer agent install codex # appends a managed block to ~/.codex/AGENTS.md buffer agent list # show supported agents and install status ``` 技能体装入当前引导 `!buffer context`。它还告诉不扩展指令运行的客户端 `buffer context` 在使用 CLI 命令之前。 已安装的文件中没有引用的快照 。 两个目标都是一流的——重新运行保持文件的时事和报告 `alreadyInstalled` 当一切都变了 没有API的呼叫, 没有需要认证 . 反转为 `buffer agent uninstall `用于 `claude` 删除独立技能文件 `codex` 管理区块被剥去 保存周围的纸条 同上,报告 `removed: false` 当什么都没有发现的时候. > **折旧:** 旧顶级 `buffer install ` 财务报告和审定财务报表 `buffer uninstall ` 命令仍然工作,但打印出折旧警告。 它们保存一次,然后取出——使用 `buffer agent install` 编号 : `buffer agent uninstall` 换句话说. ## 配置 CLI从两个文件中读取了配置. Repo 配置覆盖每个密钥的全球配置 。 丢失的文件被视为空 . | 范围 | 路径 | 页:1 | | --- | --- | --- | | 全球 | `$XDG_CONFIG_HOME/buffer/config.json` (或 `~/.config/buffer/config.json`(中文(简体) ) | 用户级默认值. 唯一一个地方 `apiKey` 可以存储. | | 还原 | `.buffer/config.json` (从当前目录走起) | 工程级别超载. `apiKey` 为了安全起见,被卸下. | 检查和管理配置 : ```bash # Interactive setup — writes apiKey + organizationId + timezone to global # config, then offers to install the Buffer skill into your agent (Claude # Code or Codex). Anything else (output format, pagination, timeout, update # check) is set with `buffer config set`. buffer init # Read buffer config get buffer config get --all # Write (defaults to global; use --repo for repo-scoped) buffer config set buffer config set outputFormat pretty --repo # Remove (defaults to global; use --repo for repo-scoped). Idempotent — # missing keys report `removed: false` and exit 0. buffer config unset buffer config unset outputFormat --repo # Show resolved config file paths buffer config path ``` ### 配置密钥 | 密钥 | 类型 | 说明 | | --- | --- | --- | | `apiKey` | 字符串 | API密钥. 仅限全球范围. | | `organizationId` | 字符串 | 接受命令的默认组织 `--organization-id`。 。 。 . | | `outputFormat` | `json` | `pretty` | `auto` | Stdout 渲染. `auto` (默认) 漂亮的指纹TTYs, JSON 否则. | | `paginationLimit` | 编号 | 默认值 `--limit` 列表中的命令. | | `timeout` | 编号 | 默认请求超时以毫秒计 . `0` 禁用超时. | | `timezone` | 字符串 | IANA时区(例如. `America/Panama`) (中文(简体) ). 坠入 `buffer init` 从你的账户里开始 使代理可以建立 `dueAt` 不包含每个命令的抵消 `buffer account` 电话. | 任意值的分辨率命令:命令旗 ~ 环境 ()`BUFFER_API_KEY` 页:1 `apiKey`, (中文(简体) ), `BUFFER_DISABLE_UPDATE_CHECK=1` 页:1 `disableUpdateCheck`) — repo配置 — 全球配置 — 内置默认 . `buffer config get` 反映分辨率顺序:每个返回的条目包括 `source` (单位:千美元)`env` | `repo` | `global` | `default`, (中文(简体) ), `path` 用于基于文件的源,以及 `envVar` (可变名称)何时 `source` 实值 `env`。这让特工和 `buffer doctor` 分辨出CLI实际选取的分层,所以一个env-var的覆接不能无声地比上盘配置高. ## 解决问题 运行 `buffer doctor` 用来诊断设置问题。 它检查: - 节点.js版本(需要18+) - 配置文件存在且有效 JSON - API 密钥存在( env var 或全局配置) - 默认组织设置 - API 端点可以达到 - API 密钥被 API 接受 - 费率限制 - CLI 版本为当前 ```bash buffer doctor ``` 默认情况下,报告只列出未完成的检查,因此可采取行动的项目易于发现。 过 `--verbose` 包括通过检查: ```bash buffer doctor --verbose ``` 每次检查都会返回状态,失败时会得到建议补救。 典型问题: - **`API key rejected`** - 在 [https://publish.buffer.com/ settings/api 页面存档备份,存于互联网档案馆](https://publish.buffer.com/settings/api) 重新运行 `buffer init`。 。 。 . - **`Rate limit reached for the window`** 等待窗口重置。 当购买一个计划提高这个限制时,固定包括链接. - **`No default organization set`** - 运行 `buffer init` 或者说 `buffer config set organizationId `。 。 。 . - **`Could not reach `** ——检查网络和VPN. - **`Config at is not valid JSON`** —— 修复或删除文件并重新运行 `buffer init`。 。 。 . - **`CLI is behind the latest `** - 运行 `buffer update` (自动检测您的软件包管理器)或等效 `npm install -g @bufferapp/cli@latest` 编号 : `pnpm add -g @bufferapp/cli@latest` 编号 : `bun add -g @bufferapp/cli@latest` 编号 : `vp install -g @bufferapp/cli@latest`。 。 。 . ## 更改日志 随包的放行便笺船 `CHANGELOG.md`。在 [Npm 代码标签](https://www.npmjs.com/package/@bufferapp/cli?activeTab=code)。 。 。 . ## 常见问题 ### @bufferapp/cli 是什么？ 用于缓冲器的CLI,为AI代理和人类设计 ### 如何安装 @bufferapp/cli？ 在项目目录运行 npm install @bufferapp/cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 buffer，可以用 npx buffer 直接运行。 ### @bufferapp/cli 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/bufferapp\_\_cli 是否存在。 ### @bufferapp/cli 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @bufferapp/cli 可以商用吗？ @bufferapp/cli 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @bufferapp/cli 的下载量有多少？ 根据 npm 官方下载统计，@bufferapp/cli 在 2026/10/09 – 2026/11/07 这 30 天内被下载 3,422 次，日均约 114 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @bufferapp/cli 还在维护吗？ 最新版本 2\.2\.0 发布于 2026/11/03（6 天前）；至今共发布 16 个版本，其中过去 12 个月发布了 16 个；首次发布于 2026/04/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。