Manage, draft, schedule, and publish social media content across connected channels (such as LinkedIn, X/Twitter, Bluesky, and others) using the Buffer CLI (@bufferapp/cli). Covers account and channel inspection, queue scheduling with dry-run safety validation, draft ideas management, and GraphQL schema introspection. Activate when scheduling social media posts, inspecting Buffer channels, automating social publishing, or managing social queues.
Manage, draft, schedule, and publish social media content across connected channels (such as LinkedIn, X/Twitter, Bluesky, and others) using the Buffer CLI (@bufferapp/cli). Covers account and channel inspection, queue scheduling with dry-run safety validation, draft ideas management, and GraphQL schema introspection. Activate when scheduling social media posts, inspecting Buffer channels, automating social publishing, or managing social queues.
Procedures, command workflows, and safety gates for scheduling social media posts, managing channels, and automating publication workflows via the Buffer CLI (@bufferapp/cli).
Architecture & Progressive Disclosure
To minimize context consumption, SKILL.md contains core operational commands and safety rules. Load specialized references on demand:
Pitfalls & Service Schemas: Read references/pitfalls.md before composing payloads for complex networks (Instagram, Pinterest, YouTube, Twitter Threads).
Automation Workflows: Read references/workflows.md for shell scripting patterns, timezone math, and Relay cursor pagination.
Rate Limits & Idempotency: Read references/rate_limits.md for 429 backoff algorithms, retry matrices, and duplicate-post prevention.
1. Bootstrapping & Installation
The Buffer CLI is generated from Buffer's public GraphQL schema, returning structured JSON with predictable error handling.
Agent Bootstrap Sequence
When running in a new environment or container, follow this self-bootstrapping sequence:
# 1. Check if the Buffer CLI is already installedif ! command -v buffer &> /dev/null; thenecho"Buffer CLI not found. Installing globally via npm (requires Node.js 18+)..."
npm install -g @bufferapp/cli
fi# 2. Verify installation version
buffer --version
# 3. Diagnose environment, config, API token, and network reachability
buffer doctor
[!TIP]
In ephemeral sandbox environments where global npm installation is restricted, you can invoke the CLI on the fly using npx:
npx -y @bufferapp/cli doctor
Authentication Modes
Environment Variable (Recommended for CI / Ephemeral Agents):
export BUFFER_API_KEY="your-api-key"
Global Configuration (buffer init):
buffer init
Writes API token, default organization, and timezone to $XDG_CONFIG_HOME/buffer/config.json (or ~/.config/buffer/config.json).
2. Core Operational Workflows
[!IMPORTANT]
Always use --output json when invoking commands within automated scripts or agent subshells to ensure clean machine parsing.
Always inspect available channels before dispatching posts to resolve target channelIds:
# Inspect account details and default organization
buffer account --output json
# List all connected social channels (LinkedIn, X, Bluesky, Threads, Instagram, etc.)
buffer channels list --output json
# Get detailed metadata for a specific channel
buffer channels get --id"<channel-id>" --output json
Workflow B: Safe Post Creation & Scheduling
Always execute with --dry-run first to validate the payload structure before sending live mutations:
# List recent posts on a channel
buffer posts list --channel-id "<channel-id>" --output json
# Fetch specific post status
buffer posts get --id"<post-id>" --output json
3. Field Selection (--fields)
To minimize payload sizes and optimize context tokens, filter responses using comma-separated dot-notation paths or brace expansion:
# Select top-level and nested properties
buffer posts get --id"<post-id>" --fields id,text,channel.name --output json
# Brace expansion for list connections
buffer posts list --channel-id "<channel-id>" --fields 'items.{id,text,status},pageInfo.endCursor' --output json
# Retrieve complete GraphQL payload
buffer posts get --id"<post-id>" --fields all --output json
4. Dynamic Schema Introspection
When crafting payloads with unknown parameters or enums, query the live schema directly:
# List all available command groups
buffer schema list
# Inspect exact input types, enum values, and output shapes for a command
buffer schema describe posts create
5. Global Flags & Exit Codes
Global Flags
Flag
Description
Best Practice
--output <json|pretty|auto>
Output renderer format
Always specify --output json in agent tooling
--dry-run
Validates input locally without network calls
Always run before stateful mutations
--quiet
Suppress spinners and stderr notices
Recommended for headless execution
--verbose
Print rate-limit summary after requests
Useful for debugging throughput limits
--timeout <ms>
Command timeout in milliseconds (default: 30000)
Set appropriately for large batch requests
Exit Code Reference
Exit Code
Classification
Cause & Agent Remediation
0
Success
Command completed successfully.
1
General Error
Runtime failure. Check error message on stderr.
2
Usage / Validation Error
Missing required flags, invalid JSON, or schema mismatch. Run buffer schema describe <group> <cmd>.
3
API Error
GraphQL upstream error or rate limit exhaustion. Inspect returned error details.
4
Authentication Error
Missing or invalid token. Run buffer doctor or export BUFFER_API_KEY.
