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, critical pitfalls, and safety rules directly in the body. Load specialized references on demand:

• 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

npx -y @bufferapp/cli doctor

Authentication Modes #

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

   export BUFFER_API_KEY="your-api-key"

2. Global Configuration (buffer init):
   bash 📋 Copy

   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 #

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

Media Hosting Requirement (No File Upload Attachments) #

Pass hosted media URLs via the assets array in a JSON payload:

{
  "channelId": "channel_123",
  "schedulingType": "automatic",
  "mode": "addToQueue",
  "text": "Announcing our new open-source release! 🚀",
  "assets": [
    {
      "image": {
        "url": "https://cdn.example.com/images/architecture-diagram.png",
        "metadata": {
          "altText": "Architecture diagram illustrating worker pool"
        }
      }
    }
  ]
}

For videos, provide the public video URL:

{
  "channelId": "channel_123",
  "schedulingType": "automatic",
  "mode": "addToQueue",
  "text": "Watch the terminal recording in action:",
  "assets": [
    {
      "video": {
        "url": "https://cdn.example.com/videos/demo.mp4"
      }
    }
  ]
}

Passing Payloads via JSON or File #

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

# Inline JSON payload with hosted media
buffer posts create --json '{
  "channelId": "channel_123",
  "schedulingType": "automatic",
  "mode": "addToQueue",
  "text": "Line 1\n\nLine 2 with links",
  "assets": [
    {
      "image": {
        "url": "https://cdn.example.com/diagram.png",
        "metadata": { "altText": "Architecture diagram" }
      }
    }
  ]
}' --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 #

Exit Code Reference #

6. Critical Pitfalls & Payload Rules #

Review these high-risk failure modes before composing commands and JSON payloads:

1. Media Hosting & File Attachments #

• Buffer Does Not Support Local Attachments: You cannot upload local file paths. All media (assets[].image.url or assets[].video.url) must be hosted publicly via HTTP/HTTPS (e.g. S3, GCS, CDN, or raw GitHub link).
• Empty text without assets is rejected: Most channels require text or at least one image/video asset.

2. Scheduling Modes & Notification Traps #

• mode: addToQueue is queued, not immediate: Use mode: shareNow to publish immediately. mode: shareNext jumps to the front of the queue. mode: customScheduled requires dueAt.
• schedulingType: notification does not auto-publish: It only sends a push notification to the user’s mobile app. Always use schedulingType: automatic for hands-off publishing.
• addToQueue on a channel with no schedule: Silently lands in an empty queue slot without scheduling. Check the schedule with buffer channels get --id <id> first.
• All times must be ISO-8601 with offset: dueAt requires a timezone offset (e.g. 2026-05-06T17:00:00-05:00). Obtain the offset from buffer config get timezone or buffer account --fields timezone. Never assume UTC.

3. Identifier Integrity #

• Never guess channel IDs: Always fetch with buffer channels list --output json. Invalid IDs will be accepted initially and fail on execution with vague upstream errors.
• IDs are not portable across organizations: A channelId from Organization A cannot be used while authenticated against Organization B.

4. Input & Formatting Constraints #

• --json overrides flags entirely: When both --json and individual flags are supplied, individual flags are ignored. Use either flags or --json, never mix.
• Nested objects need --json: Per-service metadata.* and assets.* cannot be set via flat CLI flags. Always use --json or --input <file>.
• Strip control characters: ASCII control characters (U+0000–U+001F except whitespace) cause payload rejections.

5. Per-Service Minimum Requirements & Threading #

• Twitter / X, Threads, Bluesky, Mastodon: Require text only.
• LinkedIn: text or assets; documents require metadata.linkedin.linkAttachment.
• Instagram: Image or video asset required; must specify metadata.instagram.type and metadata.instagram.shouldShareToFeed.
• Twitter / X Threads: When chaining posts via metadata.twitter.thread, the top-level text MUST match the first thread item’s text:
  json 📋 Copy

  {
    "channelId": "ch_123",
    "text": "First tweet in thread",
    "metadata": {
      "twitter": {
        "thread": [
          { "text": "First tweet in thread" },
          { "text": "Second tweet in thread" }
        ]
      }
    }
  }