CLI / Agents

How to connect Social Post Flow to your AI agent (Claude Code, Cursor, Codex, Warp) or your own shell scripts and CI workflows.

Introduction

Social Post Flow’s CLI is a command-line interface that lets your AI agent or shell scripts manage your Social Post Flow account. It’s ideal for:

• AI agents that don’t natively support MCP (Cursor, Codex, Warp, Cline, OpenCode, and more).
• Shell scripts that schedule content from your own systems.
• CI/CD workflows that auto-publish (e.g. a GitHub Action that announces every blog post).
• Anyone who wants to script Social Post Flow without writing API code.

The CLI is open source under the MIT licence: github.com/socialpostflow/socialpostflow-cli

Prerequisites

• A registered account with Social Post Flow, either in trial or on a paid subscription.
• At least one social media profile connected to Social Post Flow.
• Node.js 18 or later installed on your machine (the CLI uses Node’s built-in fetch).

Setup

Install the CLI

Install globally with npm:

npm install -g socialpostflow-cli

This installs two interchangeable commands: spf (short form) and socialpostflow (long form). Both do the same thing.

Alternatively, run directly with npx (no install required):

npx socialpostflow-cli --help

Or clone the repo and run the script directly:

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

Authenticate the CLI

You can find your personal access token and the setup command on the Integrations > CLI / Agents screen of your account: app.socialpostflow.com/integrations/cli

Run the setup command (replace with your own token):

spf setup --key eyxxxxxxxxxxxxxxxxxxx

The CLI verifies the token against the API and saves it to ~/.socialpostflow/credentials.json. From then on, every spf command uses the stored token automatically.

Alternatively, set an environment variable instead of running setup:

export SOCIALPOSTFLOW_API_TOKEN=eyxxxxxxxxxxxxxxxxxxx

This is the preferred method for CI/CD secrets, GitHub Actions, and Docker containers.

Install the agent skill

The CLI works on its own — you can use spf commands directly from any shell. But agents work better when they have a “skill” that teaches them how to use Social Post Flow in natural language.

Claude Code

Run this one command in your terminal:

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

The skill is now available in every Claude Code session. Open Claude Code and run /skills to confirm socialpostflow is listed. Then ask things like:

“Schedule a post saying ‘Happy Monday’ to my X account for 9am tomorrow.”

“List my failed posts.”

“Post this thread to LinkedIn and Threads.”

Claude will use the CLI under the hood to do the work.

Other agents

For Cursor, Codex, Warp, Cline, OpenCode, and many others, use the multi-agent installer:

npx skills add socialpostflow/socialpostflow-cli

When prompted, select the agents you want to install for. The installer will copy the skill into each agent’s skill folder.

Command Reference

Command	Description	Options
spf setup	Verify and store a personal access token.	--key <token>
spf whoami	Show the authenticated user, subscription state, and stats.	None
spf profiles	List your connected social profiles.	--post-type <type> --per-page <n> --order-by --order
spf posts	List posts.	--status <s> --profile-id <id> --per-page --order-by --order
spf post	Create a post (one per profile ID).	-c text -i ids -t type -m media -u url --first-comment --schedule-type -s scheduled-at
spf show	Show a single post.	<post-id>
spf delete	Delete a post. Stops it publishing if scheduled.	<post-id>

For the full reference, run spf --help or spf <command> --help in your terminal.

All commands write JSON to standard output, so they’re easy to pipe into jq or parse from a script:

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"

Command Usage

Get User

spf whoami

Or ask your agent:

“List my account details in Social Post Flow.”

List Profiles

spf profiles

Filter by what kind of post the profile can accept:

spf profiles --post-type text      # Networks that support text/link posts
spf profiles --post-type story     # Instagram (Stories only)
spf profiles --post-type pin       # Pinterest only
spf profiles --post-type tiktok    # TikTok only
spf profiles --post-type google    # Google Business Profiles only

Or ask your agent:

“List my connected social media profiles in Social Post Flow.”

List Posts

spf posts
spf posts --status scheduled
spf posts --status posted --order-by posted_at --order desc
spf posts --status failed
spf posts --profile-id 42

Or ask your agent:

“List my posts in Social Post Flow.”

“List my failed posts in Social Post Flow.”

Get Post

spf show 98081

Or ask your agent:

“Display post 98081 from Social Post Flow.”

Create a Post

A simple text post, published immediately:

spf post -c "Hello, world" -i 42

To multiple profiles at once:

spf post -c "Big announcement" -i 42,87,103

A link post:

spf post -t link -c "Worth reading:" -u "https://example.com/article" -i 42

An image post:

spf post -t image -c "Behind the scenes" -m "https://example.com/photo.jpg" -i 42

Scheduled for a specific time:

spf post -c "Happy Monday!" -i 42 \
  --schedule-type scheduled \
  -s "2026-07-20T09:00:00Z"

Added to the end of the user’s queue (uses their configured queue interval):

spf post -c "Quick tip..." -i 42 --schedule-type queue_end

With a first comment (X thread starter, LinkedIn comment, etc.):

spf post -c "Main post text" -i 42 --first-comment "Reply with extra context…"

Or ask your agent:

“Create a text post for the Facebook profile ‘Social Post Flow’ saying ‘Hello, world’, and post it immediately.”

“Schedule a Monday motivation post for 9am next week on my X account.”

“Queue up these three blog promos across all my channels.”

Delete a Post

spf delete 104105

Or ask your agent:

“Delete post 104105 from Social Post Flow.”

Environment Variables

Variable	Default	Description
SOCIALPOSTFLOW_API_TOKEN	—	Your API token. Alternative to running spf setup.
SOCIALPOSTFLOW_API_URL	https://app.socialpostflow.com/api	Override the API base URL. Useful for testing.

Troubleshooting

Not authenticated — Run spf setup --key <token> or set SOCIALPOSTFLOW_API_TOKEN. Get your token from app.socialpostflow.com/integrations/cli.

HTTP 401 from API — Your token is invalid or expired. Generate a new one from your Integrations > CLI / Agents screen.

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, or missing required media_urls for image, story, pin or TikTok posts.

HTTP 429 from API — Daily post limit reached for that profile. Wait until the next day or upgrade your plan.

command not found: spf — The CLI isn’t on your PATH. If you installed with npm install -g, run npm ls -g | grep socialpostflow to confirm. If running locally, use node scripts/socialpostflow.js instead.

Agent doesn’t see the skill — Run /skills in Claude Code (or your agent’s equivalent). If socialpostflow isn’t listed, repeat the install command from the Install the agent skill section above.

---

For full API reference and request/response schemas, see the API documentation.

For agent skills installed alongside the CLI, see the SKILL.md in the open source repo.