PostSyncer CLI

Social media automation CLI for developers and AI agents — schedule posts programmatically, manage drafts and publishes, organize media uploads, moderate comments, and pull analytics from the terminal or from scripts.

Built for PostSyncer, it uses the same connected networks you already manage in the product — including X (Twitter), LinkedIn, Instagram, Facebook, TikTok, YouTube, Pinterest, Threads, Telegram, Mastodon, Bluesky, and other supported channels — so you can run social media scheduling and publishing from code without building your own integration.

Use it for CI/CD, internal tools, or agent and LLM workflows (tokens, JSON, and --help on every command). The installable command is postsyncer (npm package postsyncer-cli).

Get help: postsyncer --help or postsyncer <topic> --help (for example postsyncer posts --help).

Contents

• Why teams use this for scheduling and automation
• Overview
• Install
• Requirements
• Getting started
• Video cover images
• Signing in with a token
• Using JSON files and stdin
• Options available on every run
• Command list
• Security and automation
• Need help?
• AI assistants
• Build from source
• License

Why teams use this for scheduling and automation

• Programmatic scheduling — Create and update drafts, set publish or scheduled times, and attach media using JSON files or stdin, ideal for repeatable pipelines.
• Social media automation — Drive the same actions you use in the PostSyncer app from Bash, npm scripts, servers, or job runners.
• AI-ready — Bearer-token auth and structured JSON responses fit assistants and autonomous agents that need predictable tools (see also AI assistants below for MCP).

Exact field names for posts and uploads live in PostSyncer docs; this README focuses on how to install and run the CLI.

Overview

Typical uses:

| You want to… | Start here | |--------------|------------| | Confirm your setup | postsyncer ping | | See workspaces and IDs | postsyncer workspaces list | | See connected profiles | postsyncer accounts list | | Create or edit posts | postsyncer posts … | | Upload or organize media | postsyncer media … · postsyncer folders … | | Work with comments | postsyncer comments … | | View engagement summaries | postsyncer analytics … |

Results are printed as JSON (easy to read by default). For logs or scripting tools, use --raw-json for a single line per reply.

Install

Install globally with npm:

npm install -g postsyncer-cli

With pnpm:

pnpm add -g postsyncer-cli

Try once without installing:

npx postsyncer-cli --help

The command you run is always postsyncer.

Requirements

You need Node.js version 20 or newer.

Getting started

1. Open PostSyncer in the browser. Go to Settings → API integrations and create an access token. Choose the permissions your workflow needs. Read more in the authentication guide.
2. In your terminal, set the token and check that it works:

export POSTSYNCER_TOKEN="paste_your_token_here"
postsyncer ping

3. Note your workspace and account numbers for later commands:

postsyncer workspaces list
postsyncer accounts list

4. Create a draft post.

From a JSON file:

postsyncer posts create --file draft.json

Inline with --data (wrap the JSON in single quotes on macOS/Linux so your shell does not strip the quotes):

postsyncer posts create --data '{"workspace_id":12,"schedule_type":"draft","content":[{"text":"Hello from PostSyncer CLI","media":["https://postsyncer.com/images/og/banner.png"]}],"accounts":[]}'

On Windows, quoting differs by shell (cmd vs PowerShell); using --file with draft.json is usually simplest there.

Same payload as draft.json — replace workspace_id with your workspace number. Before publishing live, add the right accounts (from accounts list) and scheduling fields. Full field list and examples: Create post.

{
  "workspace_id": 12,
  "schedule_type": "draft",
  "content": [
    {
      "text": "Hello from PostSyncer CLI",
      "media": ["https://postsyncer.com/images/og/banner.png"]
    }
  ],
  "accounts": []
}

Scheduling: set schedule_type to draft, schedule, or publish_now. For timed posts you normally add a schedule block and accounts as described in the guide linked above.

Video cover images

For video posts, set cover_image on the first item in content[] (only content[0].cover_image is used when publishing). Which field you use depends on the target platform — see Create post — cover image.

| Platform | Cover method | API field | |----------|--------------|-----------| | TikTok | Frame from the attached video | video_cover_timestamp_ms | | YouTube | Custom thumbnail upload | thumbnail | | Instagram (Reels) | Custom thumbnail upload | thumbnail | | Facebook (Reels / video) | Custom thumbnail upload | thumbnail |

• thumbnail — media library id (from media upload-file / media upload-url) or a public HTTPS URL to an image. Required for YouTube, Instagram, and Facebook. Not used on TikTok.
• video_cover_timestamp_ms — timestamp in milliseconds (e.g. 2500 = 2.5 seconds). TikTok only.

Typical workflow for custom thumbnails: upload the video → upload the cover image → create the post with both ids in content[0].

TikTok — pick a frame at 2.5 seconds:

{
  "workspace_id": 12,
  "schedule_type": "draft",
  "content": [
    {
      "text": "New TikTok!",
      "media": [1842],
      "cover_image": { "video_cover_timestamp_ms": 2500 }
    }
  ],
  "accounts": [{ "id": 136 }]
}

Instagram / Facebook / YouTube — custom cover image:

{
  "workspace_id": 12,
  "schedule_type": "draft",
  "content": [
    {
      "text": "Check out our new reel!",
      "media": [1842],
      "cover_image": { "thumbnail": 1843 }
    }
  ],
  "accounts": [{ "id": 136 }]
}

Use postsyncer posts update <id> with the same cover_image shape to change cover settings on drafts.

Signing in with a token

| Method | Description | |--------|--------------| | Environment variable POSTSYNCER_TOKEN | Recommended for everyday use and servers. | | Flag -t or --token | Pass the token on that command line only. |

Your token only works for what you allowed when you created it. If PostSyncer returns a permission error, open API integrations and grant the matching access, or use a command your token supports.

Using JSON files and stdin

Several commands expect JSON (for example creating a post, creating a label, or importing media from URLs). Provide the data in exactly one of these ways:

| Method | Description | |--------|--------------| | --file / -f | Path to a JSON file. | | --data / -d | JSON as text on the command line. | | --stdin | Pipe JSON into the command. |

Examples:

postsyncer posts create --file ./my-post.json
postsyncer labels create --data '{"workspace_id":12,"name":"Product launch","color":"#4F46E5"}'
echo '{"workspace_id":1,"urls":["https://example.com/photo.jpg"]}' | postsyncer media upload-url --stdin

Options available on every run

These can be placed before the subject (for example postsyncer --raw-json workspaces list).

| Option | Description | |--------|--------------| | -t / --token | Token if POSTSYNCER_TOKEN is not set. | | --raw-json | Compact JSON output. | | --base-url | Only if PostSyncer support gives you a custom service URL. | | --upload-base-url | Only if support tells you uploads must use another host. |

Command list

Every command supports --help. Examples: postsyncer posts --help, postsyncer media upload-file --help.

All commands start with postsyncer.

Connectivity

• postsyncer ping — check your token and workspaces

Workspaces

• postsyncer workspaces list

Accounts

• postsyncer accounts list
• postsyncer accounts delete <id>

Labels

• postsyncer labels list
• postsyncer labels get <id>
• postsyncer labels create
• postsyncer labels update <id>
• postsyncer labels delete <id>

Posts

• postsyncer posts list
• postsyncer posts get <id>
• postsyncer posts get-by-url <url>
• postsyncer posts get-by-platform-id <id>
• postsyncer posts create
• postsyncer posts update <id>
• postsyncer posts delete <id>
• postsyncer posts analyze-twitter --url <url> --question <text>
• postsyncer posts auto-plug <postId>
• postsyncer posts comment-moderation <postId>
• postsyncer posts contact-collection <postId>

Media

• postsyncer media list
• postsyncer media get <id>
• postsyncer media delete <id>
• postsyncer media upload-file — needs --workspace, --file; optional --folder (postsyncer media upload-file --help)
• postsyncer media upload-url

Folders

• postsyncer folders list
• postsyncer folders get <id>
• postsyncer folders create
• postsyncer folders update <id>
• postsyncer folders delete <id>

Comments

• postsyncer comments list --post <postId>
• postsyncer comments get <id>
• postsyncer comments create
• postsyncer comments update <id>
• postsyncer comments delete <id>
• postsyncer comments hide <id>
• postsyncer comments sync

Analytics

• postsyncer analytics all
• postsyncer analytics workspace <id>
• postsyncer analytics post <id>
• postsyncer analytics account <id>
• postsyncer analytics sync-post <id>

Security and automation

• Treat tokens like passwords: do not store them in public repositories or chat logs.
• On GitHub Actions, GitLab CI, or other platforms, inject the token from masked secrets.
• Revoke compromised tokens immediately in PostSyncer and create new ones.
• Automated jobs should respect PostSyncer’s fair usage and avoid hammering the service; use retries with delays when bulk operations fail.

Need help?

• Product and field documentation: docs.postsyncer.com
• If a command fails, the CLI prints PostSyncer’s message so you can correct the token, permissions, or your JSON payload.

AI assistants

For AI agents and copilots that integrate with PostSyncer, the Model Context Protocol (MCP) exposes similar capabilities to apps like Cursor and Claude Desktop. Start with the MCP overview and client setup. Many workflows use the same Bearer token as postsyncer; others combine MCP tools with this CLI in scripts.

Build from source

For maintainers contributing to this package:

npm install
npm run build
node dist/cli.js --help

License

MIT