SimplePost CLI

Post to X, Telegram, YouTube, Instagram, Facebook, TikTok, Bluesky, Threads, LinkedIn, Pinterest, and DEV/Forem from your terminal.

npm install -g @simple-post/cli

simplepost connect   # link the CLI to your SimplePost account
simplepost post      # pick accounts and write your post interactively

Hosted CLI access requires Advanced, Pro, or an active trial. Direct local publishing uses your own credentials and has no hosted plan requirement.

Two ways to connect accounts

The CLI supports exactly two modes — pick whichever fits you:

1. Use your SimplePost account (recommended)

If you use the hosted SimplePost Scheduler, your social accounts are already connected there. Link the CLI to it once and post through those accounts — no developer apps, no API keys:

simplepost connect          # opens the browser to authorize the CLI
simplepost account          # lists the accounts connected to SimplePost
simplepost post             # interactive posting flow

For CI or other non-interactive environments, provide an existing CLI token through the environment. Set SIMPLE_POST_CONFIG_PASSWORD so the token can be stored without an interactive setup step (encrypted file storage is configured automatically). Environment variables avoid exposing the token in the process list or shell history:

export SIMPLE_POST_CONFIG_PASSWORD="..."
export SIMPLE_POST_CLI_TOKEN="sp_cli_..."
simplepost connect

Scripted posting works too: simplepost account prints a target ID for every app account, which you pass to post:

simplepost post --app-account-id "<id>" --text "Hello from CI"

2. Bring your own developer apps

If you prefer to run without SimplePost, register your own developer app with each platform and put its credentials in environment variables. The CLI then runs the OAuth flow locally and stores the resulting tokens on your machine:

export SIMPLE_POST_X_CLIENT_ID="..."

simplepost account add x --alias main
simplepost post --account x:main --text "Hello from my own X app"

OAuth providers use these variable names:

| Variable | Meaning | | -------------------------------------- | ------------------------------------------------ | | SIMPLE_POST_<PLATFORM>_CLIENT_ID | OAuth client ID of your developer app | | SIMPLE_POST_<PLATFORM>_CLIENT_SECRET | OAuth client secret, when the platform needs one | | SIMPLE_POST_<PLATFORM>_REDIRECT_URI | Optional loopback redirect override |

<PLATFORM> is one of X, YOUTUBE, FACEBOOK, INSTAGRAM, TIKTOK, BLUESKY, THREADS, LINKEDIN, PINTEREST.

OAuth callbacks use port 5000 by default. If that port is occupied, pass --callback-port 6123 to connect or account add, or set SIMPLE_POST_CALLBACK_PORT=6123. For your own platform app, register the resulting loopback redirect URI exactly; a platform-specific SIMPLE_POST_<PLATFORM>_REDIRECT_URI still takes precedence.

Platform notes:

• X — a client secret is only needed if your app is a confidential client; public (native) apps work with PKCE alone.
• Facebook, Instagram — use a public (native/desktop) Meta app; the flow is OIDC + PKCE and no client secret is used.
• YouTube, TikTok, Threads, LinkedIn, Pinterest — always require the client secret.
• Bluesky — the client ID is the URL of your hosted atproto client metadata.
• Telegram — no OAuth app at all; connect with a bot token: simplepost account add telegram --bot-token "$TOKEN" --chat-id @channel.
• DEV/Forem — no OAuth app; connect with an API key from your Forem account settings.

Commands

simplepost connect          Connect the CLI to your SimplePost account
simplepost disconnect       Remove the SimplePost connection
simplepost status           Show connection and configuration status
simplepost account          List connected accounts
simplepost account add      Connect an account with your own developer app
simplepost account remove   Remove a locally connected account
simplepost post             Publish a post (interactive when run without flags)
simplepost repost           Repost previously published content
simplepost setup            Choose how local secrets are stored

Run simplepost <command> --help for all flags.

Posting

Posting submits immediately. The CLI does not create SimplePost drafts or calendar schedules; use the web app, MCP, or API for those. Provider-specific scheduling and TikTok inbox uploads remain provider actions.

Both local and Scheduler-connected accounts accept local image/video files and public URLs. The CLI uploads local files to Scheduler for app accounts (500 MiB per file); the web app has a separate 50 MiB limit. Upload limits.

Interactive (default when no flags are given):

simplepost post

Non-interactive, mixing local accounts (--account <platform>:<alias>) and SimplePost app accounts (--app-account-id <id>):

simplepost post \
  --account x:main \
  --account telegram:announcements \
  --app-account-id "<id>" \
  --text "Release day 🚀" \
  --image ./banner.png

Both selectors are listed by simplepost account in the Target column.

Full control with a JSON payload (the same shape as the @simple-post/sdk Post type):

simplepost post --post-json ./post.json --account x:main

The CLI prints a per-target summary and exits non-zero if any target fails, so it is safe to use in scripts and CI.

Boolean posting options use oclif's explicit positive/negative flags. For example, use --strict-mode or --no-strict-mode, and --youtube-made-for-kids or --no-youtube-made-for-kids; do not pass string values such as --strict-mode true.

Scheduler connections use a one-time browser authorization code. The bearer token is exchanged directly by the CLI, stored only in the selected secret backend, expires after 90 days, and is revoked remotely by simplepost disconnect.

Secret storage

Tokens are stored with the backend chosen during simplepost setup (it runs automatically on first use):

| Backend | Best for | | ---------------- | ----------------------------------------------------------- | | keychain | Personal machines with an OS keychain | | file-encrypted | Servers and CI, unlocked with SIMPLE_POST_CONFIG_PASSWORD | | file-plain | Local testing only |

Documentation

Read the CLI guide, local quickstart, and published versus hosted behavior. Maintainers: development and npm release instructions.

License

MIT

TikTok photo posts and music

Attach 1–35 JPEG/WebP photos with repeated --image flags. Use --tiktok-auto-add-music for TikTok-recommended music on Direct Post, or --tiktok-publish-mode draft to upload to TikTok's inbox and add music/edit/publish manually. --no-tiktok-auto-add-music disables automatic music. These work for both --account tiktok:alias and --app-account-id ID, including local files.

simplepost post --app-account-id TIKTOK_ACCOUNT_ID \
  --image ./1.jpg --image ./2.jpg --image ./3.jpg --image ./4.jpg \
  --text "My photo story" --tiktok-title "This week" \
  --tiktok-privacy-level SELF_ONLY --tiktok-auto-add-music

simplepost post --app-account-id TIKTOK_ACCOUNT_ID \
  --image ./1.jpg --image ./2.jpg --tiktok-publish-mode draft

Additional fields: --tiktok-description (photo description override) and --tiktok-photo-cover-index (zero-based, default 0). The interactive flow and JSON inputs expose the same behavior. Local-account SDK uploads need S3-compatible storage whose public domain/prefix is verified with TikTok. Public image URLs must also be verified, HTTPS and without redirects.

For local video publishing, install FFmpeg (ffprobe on PATH), or set an absolute FFPROBE_PATH. Video inspection failures block publishing before upload. See the validation coverage and runtime requirements.