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

Using	Use this
Claude Code, 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.

Install as a skill

Adds the Social Post Flow skill to your agent so it can compose and schedule posts in natural language.

Single-command install (Claude Code):

mkdir -p ~/.claude/skills/socialpostflow && \
  curl -L https://raw.githubusercontent.com/socialpostflow/socialpostflow-cli/main/skills/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 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

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.

spf post options

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

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

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