Skip to content

Latest commit

 

History

History
111 lines (87 loc) · 4.52 KB

AGENTS.md

File metadata and controls

111 lines (87 loc) · 4.52 KB

Buffer CLI — Agent Reference

Command Inventory

auth

Command Required Args Optional Flags Description
buffer auth login <token> token — Save access token
buffer auth status — -o Show auth status
buffer auth logout — — Remove credentials

profiles

Command Required Args Optional Flags Description
buffer profiles list — --access-token, -o, -q, -v List all profiles
buffer profiles get --profile-id --access-token, -o, -q, -v Get profile details

posts

Command Required Args Optional Flags Description
buffer posts list --profile-id --count, --page, --access-token, -o, -q, -v List pending posts
buffer posts sent --profile-id --count, --page, --access-token, -o, -q, -v List sent posts
buffer posts create --profile-id, --text --media-link, --media-description, --scheduled-at, --now, --dry-run, --access-token, -o, -q, -v Create a post
buffer posts update --post-id, --text --media-link, --media-description, --scheduled-at, --dry-run, --access-token, -o, -q, -v Update a post
buffer posts delete --post-id --dry-run, --access-token, -o, -q, -v Delete a post
buffer posts share --post-id --dry-run, --access-token, -o, -q, -v Share immediately

analytics

Command Required Args Optional Flags Description
buffer analytics get --profile-id --count, --page, --access-token, -o, -q, -v Get post analytics

Auth Setup Sequence

  1. Obtain an access token from https://buffer.com/developers/apps
  2. Run buffer auth login <token> to save it
  3. Or set BUFFER_ACCESS_TOKEN environment variable
  4. Verify with buffer auth status

Token priority: --access-token flag > BUFFER_ACCESS_TOKEN env var > config file

Common Workflows

Post to multiple profiles

# Get profile IDs
PROFILES=$(buffer profiles list -o json | jq -r '.[].id')

# Post to a specific profile
buffer posts create --profile-id prof_abc123 --text "Hello world!"

# Post to multiple profiles
buffer posts create --profile-id prof_abc123 prof_def456 --text "Cross-post!"

Schedule a batch of posts

buffer posts create --profile-id prof_abc123 --text "Morning post" --scheduled-at "2024-03-01T09:00:00Z"
buffer posts create --profile-id prof_abc123 --text "Afternoon post" --scheduled-at "2024-03-01T14:00:00Z"
buffer posts create --profile-id prof_abc123 --text "Evening post" --scheduled-at "2024-03-01T19:00:00Z"

Export analytics to CSV

buffer analytics get --profile-id prof_abc123 --count 100 -o csv > analytics.csv

Check queue and share next post immediately

# See what's in the queue
buffer posts list --profile-id prof_abc123 -o table

# Share the next post right now
buffer posts share --post-id upd_xyz789

Output Format Notes

JSON output (default)

  • Arrays returned for list commands
  • Single objects for get/create/update
  • Error format: {"error": {"code": "ERROR_CODE", "message": "..."}}

Table output

  • Human-readable aligned columns
  • Long text fields are truncated with ...
  • Timestamps shown in ISO 8601

CSV output

  • Headers in first row
  • Suitable for piping to spreadsheets or data tools

Error Codes

Code Meaning Action
AUTH_FAILED Invalid or expired token Run buffer auth login <new-token>
AUTH_MISSING No token provided Set token via flag, env var, or config
RATE_LIMITED 60 req/min limit exceeded Wait and retry (auto-retry built in)
API_ERROR General API error Check message for details
CREATE_FAILED Post creation failed Check profile ID and text content
UPDATE_FAILED Post update failed Check post ID is valid and pending
DELETE_FAILED Post deletion failed Check post ID exists
SHARE_FAILED Immediate share failed Check post ID is in pending queue

Rate Limits

  • Limit: 60 authenticated requests per user per minute
  • Response: HTTP 429 with Retry-After header
  • CLI behavior: Auto-retry with exponential backoff (up to 3 retries)
  • Best practice: Use --count to fetch more items per request to reduce request count