缓冲 CLI

Buffer API的指令行界面,为人和AI代理设计. 所有输出都是JSON,所有错误都是结构化的,每个命令都是由公共GraphQL schema产生的.

安装

npm install -g @bufferapp/cli
buffer --version

pnpm, Yarn, Bun, 和 Vite+ 工作:

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或以后.

快开始

# 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 相反——见 认证时生成 API 密钥 https://publish.buffer.com/ settings/api 页面存档备份,存于互联网档案馆。 。 。 .

认证

buffer init 是建议设置。 它会将您的 API 密钥写入全局配置, 并附带默认的组织和时区, 然后提供安装代理技能 。 生成 API 密钥 https://publish.buffer.com/ settings/api 页面存档备份,存于互联网档案馆。 。 。 .

buffer init

CLI 还接受来自 BUFFER_API_KEY 环境变量。 支持 CI, 容器, 以及任意使用磁盘的 API 密钥是不可取的—— 当两者都存在时, 它优先于配置文件 .

export BUFFER_API_KEY=your-api-key-here

分辨率命令 : BUFFER_API_KEY → apiKey 在全局配置文件中。 首个非null API 键取胜. 缺少或无效的 API 密钥生成退出代码 4 在 Stderr 有结构错误。 正则命令从不交互提示证书——只限 buffer init 是交互式的,并且是选入的.

为了安全起见, apiKey 仅在 全球 配置文件 。 试图将其写入可重复扫描的配置的尝试被拒绝.

使用量

buffer --help
buffer --version
buffer <group> <command> [flags]

见 Schema 反思 下面为程序化发现命令.

示例命令

# Account info
buffer account

# Channels
buffer channels list
buffer channels get --id <channel-id>

# Posts (queries)
buffer posts list --channel-id <channel-id>
buffer posts get --id <post-id>

# Posts (mutations, flags)
buffer posts create --channel-id <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 <org-id> --text "Idea body"

# Ideas (mutations, JSON)
buffer ideas create --json '{"organizationId": "...", "content": {"text": "Idea body"}}'

# Idea Groups
buffer ideaGroups list --organization-id <org-id>

输入也可以来自文件或 stdin:

buffer posts create --input post.json
cat post.json | buffer posts create --input -

干线运行

所有突变支持 --dry-run,以验证本地输入并打印有效载荷 将 在不发出API呼叫的情况下发送 :

buffer posts create --json '{"channelId": "abc"}' --dry-run

请求超时

使用 --timeout <ms> 绑定任何命令会等待API多久。 默认为30000ms(30s). 过 0 以禁用长期运行的超时 :

# 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 只返回您想要的 .

# 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 <command> 来看看 defaultFields (返回时无 --fields和 selectableFields 任何命令.

偏爱 --fields 在管道到 jq。 。 。 . 过滤方式 jq 仍然支付通过网络和响应解析器获取每个字段的费用. --fields 缩写 GraphQL 请求本身,所以 API 跳过工作, 反应仍然很小 。 使用 jq 为了改造已经发射的JSON 而不是你不需要的修剪地盘.

输出格式和记录旗

每个命令上都有四个全局旗帜控制渲染和斯德尔噪声:

• --output <json|pretty|auto> 覆盖 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)在接通处理它们的寻呼器时保持颜色.

退出代码

当CLI的stdout管被消费者关闭(例如. buffer ... | head), CLI 默默地退出 0 而不是打印出一个 EPIPE 堆栈跟踪.

Schema 反思

buffer schema list
buffer schema describe posts create

buffer schema describe 返回全方法签名为 JSON — 输入类型、输出形状、需要的字段、enum 值。 在执行前用它来发现命令并验证有效载荷.

壳完成

CLI 打印完成脚本 bash, (中文(简体) ), zsh,或 fish。通过 --install 自动把它接上; 没有它,脚本就转到 stdout 以便你能够 eval 或自吹自擂,或自吹自擂.

# 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代理的上下文窗口.

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 , 而无需自定义系统提示 :

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 <agent>用于 claude 删除独立技能文件 codex 管理区块被剥去 保存周围的纸条 同上,报告 removed: false 当什么都没有发现的时候.

折旧: 旧顶级 buffer install <agent> 财务报告和审定财务报表 buffer uninstall <agent> 命令仍然工作,但打印出折旧警告。 它们保存一次,然后取出——使用 buffer agent install 编号 : buffer agent uninstall 换句话说.

配置

CLI从两个文件中读取了配置. Repo 配置覆盖每个密钥的全球配置 。 丢失的文件被视为空 .

检查和管理配置 :

# 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 <key>
buffer config get --all

# Write (defaults to global; use --repo for repo-scoped)
buffer config set <key> <value>
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 <key>
buffer config unset outputFormat --repo

# Show resolved config file paths
buffer config path

配置密钥

任意值的分辨率命令:命令旗 ~ 环境 ()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 版本为当前

buffer doctor

默认情况下,报告只列出未完成的检查,因此可采取行动的项目易于发现。 过 --verbose 包括通过检查:

buffer doctor --verbose

每次检查都会返回状态,失败时会得到建议补救。 典型问题:

• API key rejected - 在 https://publish.buffer.com/ settings/api 页面存档备份,存于互联网档案馆 重新运行 buffer init。 。 。 .
• Rate limit reached for the <window> window 等待窗口重置。 当购买一个计划提高这个限制时,固定包括链接.
• No default organization set - 运行 buffer init 或者说 buffer config set organizationId <id>。 。 。 .
• Could not reach <url> ——检查网络和VPN.
• Config at <path> is not valid JSON —— 修复或删除文件并重新运行 buffer init。 。 。 .
• CLI <x> is behind the latest <y> - 运行 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 代码标签。 。 。 .