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.
| Using | Use this |
|---|---|
| Claude Code | The plugin (see Install as a Claude Code plugin below) — ships the MCP server pre-wired |
| Claude Desktop, ChatGPT Desktop | The MCP server (one-click connect, no setup) |
| Cursor, Codex, Warp, Cline, OpenCode, other agents | The skill (see Install as a skill below) |
| Shell scripts, CI/CD, your own tooling | The CLI (see Install as a CLI below) |
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.
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.
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.mdMulti-agent install (Cursor, Codex, Warp, Cline, OpenCode, etc.):
npx skills add socialpostflow/socialpostflow-cliWhen 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.
Globally via npm:
npm install -g socialpostflow-cliOr run directly via npx without installing:
npx socialpostflow-cli --helpOr 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 --helpRequires Node.js 18 or later (for built-in fetch).
You need a Social Post Flow account with API access. Grab your personal access token from your profile page, then:
spf setup --key spf_xxxxxxxxxxxxxxxxThis 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# 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| Command | Description |
|---|---|
spf setup --key <token> |
Verify and store a personal access token. |
spf whoami |
Show the authenticated user's profile, subscription state, and stats. |
spf profiles [--post-type T] |
List connected social profiles. Optionally filter by post type. |
spf posts [--status S] [--profile-id N] |
List posts. Filter by status or profile. |
spf post -c "..." -i id1,id2 [options] |
Create a post (see options below). |
spf show <post-id> |
Show details of a single post. |
spf delete <post-id> |
Delete a post. Stops it publishing if scheduled. |
| Flag | Description |
|---|---|
-c, --content |
Post text. Required unless --type story. |
-i, --profile-ids |
Comma-separated profile IDs (required). |
-t, --type |
Post type: text (default), link, image, story, pin, tiktok, google. |
-m, --media |
Comma-separated public image/video URLs. |
-u, --url |
URL to attach (required for --type link). |
--first-comment |
First-comment text. Not supported on Mastodon, TikTok, Telegram, Google. |
--schedule-type |
immediate (default), queue_end, queue_start, scheduled. |
-s, --scheduled-at |
ISO 8601 timestamp (required when --schedule-type=scheduled, must be in future). |
See agent-skill/socialpostflow/SKILL.md for the full post-type rules (what each type requires and forbids).
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"| Variable | Default | Description |
|---|---|---|
SOCIALPOSTFLOW_API_TOKEN |
— | Your API token. Alternative to spf setup. |
SOCIALPOSTFLOW_API_URL |
https://app.socialpostflow.com/api |
Override the API base URL (useful for testing). |
See examples/ for shell scripts demonstrating common workflows:
post-everywhere.sh— post the same content to all connected text-capable profilesschedule-week.sh— schedule a week's worth of posts using the queuegithub-actions.yml— publish a blog post announcement from a GitHub Action
"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.
MIT — see LICENSE.
- 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