buffer

name	buffer
description	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.
license	Apache-2.0
metadata	{"category":"writing","tags":"social-media, publishing, automation, management","author":"Daniela Petruzalek ([e-mail])","version":"0.1.1","catalog":"https://skills.danicat.dev"}

Buffer CLI Playbook

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 installed
if ! command -v buffer &> /dev/null; then
  echo "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

1. Environment Variable (Recommended for CI / Ephemeral Agents):

   export BUFFER_API_KEY="your-api-key"
   

2. 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.

Workflow A: Channel Discovery & Account Inspection

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:

# Step 1: Dry run validation
buffer posts create \
  --channel-id "<channel-id>" \
  --scheduling-type automatic \
  --mode addToQueue \
  --text "Your post content here" \
  --dry-run

# Step 2: Live creation (Add to channel queue)
buffer posts create \
  --channel-id "<channel-id>" \
  --scheduling-type automatic \
  --mode addToQueue \
  --text "Your post content here" \
  --output json

Passing Payloads via JSON or File

For complex multi-line text, media attachments, or structured objects:

# Inline JSON payload
buffer posts create --json '{
  "channelId": "channel_123",
  "schedulingType": "automatic",
  "mode": "addToQueue",
  "text": "Line 1\n\nLine 2 with links"
}' --output json

# Read payload from file
buffer posts create --input post_payload.json --output json

# Pipe payload from stdin
cat post_payload.json | buffer posts create --input - --output json

---

Workflow C: Drafting Ideas

Create draft thoughts and ideas in Buffer without assigning them immediately to a channel queue:

# Create an idea in an organization
buffer ideas create \
  --organization-id "<org-id>" \
  --text "Draft angle for next week's release" \
  --output json

# Create an idea with structured JSON
buffer ideas create --json '{
  "organizationId": "org_123",
  "content": { "text": "Architectural breakdown draft" }
}' --output json

---

Workflow D: Inspecting & Monitoring Scheduled Posts

# 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.