socialpostflow-cli

Social Post Flow CLI

Social media automation for AI agents — schedule posts across 12+ networks programmatically.

A zero-dependency Node.js CLI wrapper around the Social Post Flow API. Designed for use with AI agents (Claude Code, Cursor, Windsurf, Codex, OpenAI SDKs) and for shell scripting / CI workflows.

Supports: Facebook, X (Twitter), LinkedIn, Instagram (Feed + Stories), Threads, Pinterest, TikTok, Mastodon, Bluesky, Telegram, Google Business Profiles, and more.

Pick your install

You can use the skill and the CLI together. The skill teaches the agent how to use Social Post Flow; the CLI is what the agent actually runs.

Install as a Claude Code plugin

The plugin bundles the MCP server config and a Claude-native skill in one install:

/plugin marketplace add socialpostflow/claude-marketplace
/plugin install socialpostflow@socialpostflow

Or, once approved in the community marketplace:

/plugin marketplace add anthropics/claude-plugins-community
/plugin install socialpostflow@claude-community

On first use, Claude Code opens a browser for you to sign in with your Social Post Flow account and approve access — no personal access token needed.

Note: If you install the plugin, don't also add the MCP server manually in Claude Desktop settings — you'll register the same endpoint twice. Pick one.

Install as a skill

Adds the Social Post Flow skill to your agent so it can compose and schedule posts in natural language. This is the CLI-driven skill (agent shells out to spf). Claude Code users should install the plugin above instead — it uses the MCP server, no CLI needed.

Single-command install (any agent that reads ~/.claude/skills/):

mkdir -p ~/.claude/skills/socialpostflow && \
  curl -L https://raw.githubusercontent.com/socialpostflow/socialpostflow-cli/main/agent-skill/socialpostflow/SKILL.md \
    -o ~/.claude/skills/socialpostflow/SKILL.md

Multi-agent install (Cursor, Codex, Warp, Cline, OpenCode, etc.):

npx skills add socialpostflow/socialpostflow-cli

When prompted, pick the agents you want to install for.

Then ask your agent things like:

"Post this text to my X and LinkedIn accounts."

"Schedule a Monday motivation post for 9am next week."

"Queue up these three blog promos across all my channels."

The agent learns from agent-skill/socialpostflow/SKILL.md, which documents the post types, scheduling model, and common workflows.

Install as a CLI

Globally via npm:

npm install -g socialpostflow-cli

Or run directly via npx without installing:

npx socialpostflow-cli --help

Or clone the repo and run the script directly (zero dependencies):

git clone https://github.com/socialpostflow/socialpostflow-cli.git
cd socialpostflow-cli
node scripts/socialpostflow.js --help

Requires Node.js 18 or later (for built-in fetch).

Authentication

You need a Social Post Flow account with API access. Grab your personal access token from your profile page, then:

spf setup --key spf_xxxxxxxxxxxxxxxx

This verifies the token against the API and saves it to ~/.socialpostflow/credentials.json (chmod 600).

Alternatively, set the environment variable:

export SOCIALPOSTFLOW_API_TOKEN=spf_xxxxxxxxxxxxxxxx

Quick start

# List your connected social profiles
spf profiles

# Post to one profile, immediately
spf post -c "Hello world!" -i 42

# Post to multiple profiles
spf post -c "Big announcement coming soon" -i 42,87,103

# Schedule for a specific time
spf post -c "Happy Monday!" -i 42 --schedule-type scheduled -s "2026-07-20T09:00:00Z"

# Add to the user's queue (uses their configured queue interval)
spf post -c "Quick tip..." -i 42 --schedule-type queue_end

# List recent posts
spf posts --status posted --order-by posted_at --order desc

# Delete a scheduled post
spf delete 12345

Commands

spf post options

See agent-skill/socialpostflow/SKILL.md for the full post-type rules (what each type requires and forbids).

All output is JSON

Every command writes JSON to stdout. Errors write JSON to stderr with a non-zero exit code:

PROFILES=$(spf profiles)
TWITTER_ID=$(echo "$PROFILES" | jq -r '.data[] | select(.provider=="x") | .id')

spf post -c "Hello from a shell script" -i "$TWITTER_ID"

Environment variables

Examples

See examples/ for shell scripts demonstrating common workflows:

• post-everywhere.sh — post the same content to all connected text-capable profiles
• schedule-week.sh — schedule a week's worth of posts using the queue
• github-actions.yml — publish a blog post announcement from a GitHub Action

Troubleshooting

"Not authenticated" — Run spf setup --key <token> or set SOCIALPOSTFLOW_API_TOKEN.

"HTTP 401 from API" — Your token is invalid. Get a valid token from https://app.socialpostflow.com/profile.

"HTTP 422 from API" — Validation error. The details payload tells you which field failed. Common causes: invalid post_type/schedule_type combination, scheduled time in the past, missing required media_urls for image/story/pin/tiktok posts.

"HTTP 429 from API" — Daily post limit reached for that profile. The user needs to wait or upgrade their plan.

License

MIT — see LICENSE.

Links

• Social Post Flow: socialpostflow.com
• API documentation: socialpostflow.com/documentation/api
• MCP documentation: socialpostflow.com/documentation/mcp
• WordPress Plugin: wordpress.org/plugins/social-post-flow
• Issues / feedback: github.com/socialpostflow/socialpostflow-cli/issues