socialsyncs

Install as a skill

npx skills add lakshit77/socialsyncs-cli

SocialSyncs CLI

Social media automation CLI for AI agents - Schedule posts across 28+ platforms programmatically.

The SocialSyncs CLI provides a command-line interface to the SocialSyncs API, enabling developers and AI agents to automate social media posting, manage content, and handle media uploads across platforms like Twitter/X, LinkedIn, Reddit, YouTube, TikTok, Instagram, Facebook, and more.

---

Installation

From npm (Recommended)

npm install -g socialsyncs
# or
pnpm install -g socialsyncs

---

Authentication

Option 1: OAuth2 (Recommended)

Authenticate using the device flow — no client ID or secret needed:

socialsyncs auth:login

This will:

1. Display a one-time code in your terminal
2. Open your browser to authorize
3. Automatically save credentials to ~/.socialsyncs/credentials.json

# Check current auth status (verifies credentials are still valid)
socialsyncs auth:status

# Remove stored credentials
socialsyncs auth:logout

Self-Hosting the Auth Server

By default, socialsyncs auth:login uses the hosted auth server at auth.socialsyncs.co. If you want to self-host the OAuth2 device flow server, follow the guide in server/SERVER.md.

Option 2: API Key

export SOCIALSYNCS_API_KEY=your_api_key_here

Optional: Custom API endpoint

export SOCIALSYNCS_API_URL=https://your-custom-api.com

Note: OAuth2 credentials take priority over the API key when both are present.

---

Commands

Discovery & Settings

List all connected integrations

socialsyncs integrations:list
socialsyncs integrations:list --group "customer-id"

Returns integration IDs, provider names, and metadata. Use --group to return only the channels assigned to a specific group (customer).

List all groups (customers)

socialsyncs integrations:groups

Returns all groups (customers) for your organization as {id, name}. Use a group's id with integrations:list --group to filter channels.

Get integration settings schema

socialsyncs integrations:settings <integration-id>

Returns character limits, required settings, and available tools for fetching dynamic data.

Trigger integration tools

socialsyncs integrations:trigger <integration-id> <method-name>
socialsyncs integrations:trigger <integration-id> <method-name> -d '{"key":"value"}'

Fetch dynamic data like Reddit flairs, YouTube playlists, LinkedIn companies, etc.

Examples:

# Get Reddit flairs
socialsyncs integrations:trigger reddit-123 getFlairs -d '{"subreddit":"programming"}'

# Get YouTube playlists
socialsyncs integrations:trigger youtube-456 getPlaylists

# Get LinkedIn companies
socialsyncs integrations:trigger linkedin-789 getCompanies

---

Creating Posts

Simple scheduled post

socialsyncs posts:create -c "Content" -s "2024-12-31T12:00:00Z" -i "integration-id"

Draft post

socialsyncs posts:create -c "Content" -s "2024-12-31T12:00:00Z" -t draft -i "integration-id"

Post with media

socialsyncs posts:create -c "Content" -m "img1.jpg,img2.jpg" -s "2024-12-31T12:00:00Z" -i "integration-id"

Post with comments (each comment can have its own media)

socialsyncs posts:create \
  -c "Main post" -m "main.jpg" \
  -c "First comment" -m "comment1.jpg" \
  -c "Second comment" -m "comment2.jpg,comment3.jpg" \
  -s "2024-12-31T12:00:00Z" \
  -i "integration-id"

Multi-platform post

socialsyncs posts:create -c "Content" -s "2024-12-31T12:00:00Z" -i "twitter-id,linkedin-id,facebook-id"

Platform-specific settings

socialsyncs posts:create \
  -c "Content" \
  -s "2024-12-31T12:00:00Z" \
  --settings '{"subreddit":[{"value":{"subreddit":"programming","title":"Post Title","type":"text"}}]}' \
  -i "reddit-id"

Complex post from JSON file

socialsyncs posts:create --json post.json

Options:

• -c, --content - Post/comment content (use multiple times for posts with comments)
• -s, --date - Schedule date in ISO 8601 format (REQUIRED)
• -t, --type - Post type: "schedule" or "draft" (default: "schedule")
• -m, --media - Comma-separated media URLs for corresponding -c
• -i, --integrations - Comma-separated integration IDs (required)
• -d, --delay - Delay between comments in minutes (default: 0)
• --settings - Platform-specific settings as JSON string
• -j, --json - Path to JSON file with full post structure
• --shortLink - Use short links (default: true)

---

Managing Posts

List posts

socialsyncs posts:list
socialsyncs posts:list --startDate "2024-01-01T00:00:00Z" --endDate "2024-12-31T23:59:59Z"
socialsyncs posts:list --customer "customer-id"

Defaults to last 30 days to next 30 days if dates not specified.

Delete post

socialsyncs posts:delete <post-id>

Change post status (draft schedule)

socialsyncs posts:status <post-id> --status draft
socialsyncs posts:status <post-id> --status schedule

Move a scheduled post back to a draft, or promote a draft into the publishing queue. Switching to draft also terminates any workflow that's already running for the post, so it won't publish. Switching to schedule queues the post for publishing at its stored date.

---

Analytics

Get platform analytics

socialsyncs analytics:platform <integration-id>
socialsyncs analytics:platform <integration-id> -d 30

Returns metrics like followers, impressions, and engagement over time for a specific integration/channel. The -d flag specifies the number of days to look back (default: 7).

Get post analytics

socialsyncs analytics:post <post-id>
socialsyncs analytics:post <post-id> -d 30

Returns metrics like likes, comments, shares, and impressions for a specific published post.

If analytics:post returns {"missing": true}, the post was published but the platform didn't return a usable post ID. You must resolve this before analytics will work:

# 1. List available content from the provider
socialsyncs posts:missing <post-id>

# 2. Connect the correct content to the post
socialsyncs posts:connect <post-id> --release-id "7321456789012345678"

# 3. Analytics will now work
socialsyncs analytics:post <post-id>

---

Automations

Manage auto-reply / DM automation workflows (e.g. reply to Instagram comments that match a keyword). The automation engine is org-scoped — your API key resolves the org server-side.

Requires the automation service to be enabled on your instance. If it isn't, these commands return 404 Automation service is not enabled.

List automations

socialsyncs automations:list
socialsyncs automations:list --integration "instagram-123"

Get a single automation

socialsyncs automations:get <automation-id>

Create an automation (from a workflow JSON file — see examples/automation.json)

socialsyncs automations:create --json ./automation.json

Update an automation

socialsyncs automations:update <automation-id> --json ./automation.json

Activate / pause an automation

socialsyncs automations:toggle <automation-id> --active false   # pause
socialsyncs automations:toggle <automation-id> --active true    # resume

Delete an automation

socialsyncs automations:delete <automation-id>

View run history

socialsyncs automations:logs <automation-id>
socialsyncs automations:logs <automation-id> --limit 10

Test the trigger against a sample message (dry-run — nothing is sent)

socialsyncs automations:test <automation-id> --text "what is the price?"
socialsyncs automations:test <automation-id> --text "info" --username someuser

The workflow JSON shape (for create/update) is the same one the dashboard builder produces — a name, integration_id, is_active, and an events array of one trigger with nested actions. See examples/automation.json for a working comment-keyword → auto-reply example.

---

Connecting Missing Posts

Some platforms (e.g. TikTok) don't return a post ID immediately after publishing. The post's releaseId is set to "missing" and analytics won't work until resolved.

List available content from the provider

socialsyncs posts:missing <post-id>

Returns an array of {id, url} items representing recent content from the provider. Returns an empty array if the provider doesn't support this feature.

Connect a post to its published content

socialsyncs posts:connect <post-id> --release-id "<content-id>"

---

Media Upload

Upload file and get URL

socialsyncs upload <file-path>

IMPORTANT: Upload Files Before Posting

You must upload media files to SocialSyncs before using them in posts. Many platforms (especially TikTok, Instagram, and YouTube) require verified/trusted URLs and will reject external links.

Workflow:

1. Upload your file using socialsyncs upload
2. Extract the returned URL
3. Use that URL in your post's -m parameter

Supported formats:

• Images: PNG, JPG, JPEG, GIF
• Videos: MP4

Example:

# 1. Upload the file first
RESULT=$(socialsyncs upload video.mp4)
PATH=$(echo "$RESULT" | jq -r '.path')

# 2. Use the SocialSyncs URL in your post
socialsyncs posts:create -c "Check out my video!" -s "2024-12-31T12:00:00Z" -m "$PATH" -i "tiktok-id"

Why this is required:

• TikTok, Instagram, YouTube only accept URLs from trusted domains
• Security: Platforms verify media sources to prevent abuse
• Reliability: SocialSyncs ensures your media is always accessible

---

Platform-Specific Features

Reddit

# Get available flairs
socialsyncs integrations:trigger reddit-id getFlairs -d '{"subreddit":"programming"}'

# Post with subreddit and flair
socialsyncs posts:create \
  -c "Content" \
  -s "2024-12-31T12:00:00Z" \
  --settings '{"subreddit":[{"value":{"subreddit":"programming","title":"My Post","type":"text","is_flair_required":true,"flair":{"id":"flair-123","name":"Discussion"}}}]}' \
  -i "reddit-id"

YouTube

# Get playlists
socialsyncs integrations:trigger youtube-id getPlaylists

# Upload video FIRST (required!)
VIDEO=$(socialsyncs upload video.mp4)
VIDEO_URL=$(echo "$VIDEO" | jq -r '.path')

# Post with uploaded video URL
socialsyncs posts:create \
  -c "Video description" \
  -s "2024-12-31T12:00:00Z" \
  --settings '{"title":"Video Title","type":"public","tags":[{"value":"tech","label":"Tech"}],"playlistId":"playlist-id"}' \
  -m "$VIDEO_URL" \
  -i "youtube-id"

TikTok

# Upload video FIRST (TikTok only accepts verified URLs!)
VIDEO=$(socialsyncs upload video.mp4)
VIDEO_URL=$(echo "$VIDEO" | jq -r '.path')

# Post with uploaded video URL
socialsyncs posts:create \
  -c "Video caption #fyp" \
  -s "2024-12-31T12:00:00Z" \
  --settings '{"privacy":"PUBLIC_TO_EVERYONE","duet":true,"stitch":true}' \
  -m "$VIDEO_URL" \
  -i "tiktok-id"

LinkedIn

# Get companies you can post to
socialsyncs integrations:trigger linkedin-id getCompanies

# Post as company
socialsyncs posts:create \
  -c "Company announcement" \
  -s "2024-12-31T12:00:00Z" \
  --settings '{"companyId":"company-123"}' \
  -i "linkedin-id"

X (Twitter)

# Create thread
socialsyncs posts:create \
  -c "Thread 1/3 🧵" \
  -c "Thread 2/3" \
  -c "Thread 3/3" \
  -s "2024-12-31T12:00:00Z" \
  -d 2000 \
  -i "twitter-id"

# With reply settings
socialsyncs posts:create \
  -c "Tweet content" \
  -s "2024-12-31T12:00:00Z" \
  --settings '{"who_can_reply_post":"everyone"}' \
  -i "twitter-id"

Instagram

# Upload image FIRST (Instagram requires verified URLs!)
IMAGE=$(socialsyncs upload image.jpg)
IMAGE_URL=$(echo "$IMAGE" | jq -r '.path')

# Regular post
socialsyncs posts:create \
  -c "Caption #hashtag" \
  -s "2024-12-31T12:00:00Z" \
  --settings '{"post_type":"post"}' \
  -m "$IMAGE_URL" \
  -i "instagram-id"

# Story (upload first)
STORY=$(socialsyncs upload story.jpg)
STORY_URL=$(echo "$STORY" | jq -r '.path')

socialsyncs posts:create \
  -c "" \
  -s "2024-12-31T12:00:00Z" \
  --settings '{"post_type":"story"}' \
  -m "$STORY_URL" \
  -i "instagram-id"

See PROVIDER_SETTINGS.md for all 28+ platforms.

---

Features for AI Agents

Discovery Workflow

The CLI enables dynamic discovery of integration capabilities:

1. List integrations - Get available social media accounts
2. Get settings - Retrieve character limits, required fields, and available tools
3. Trigger tools - Fetch dynamic data (flairs, playlists, boards, etc.)
4. Create posts - Use discovered data in posts
5. Analyze - Get post analytics; if {"missing": true} is returned, resolve with posts:missing + posts:connect

This allows AI agents to adapt to different platforms without hardcoded knowledge.

JSON Mode

For complex posts with multiple platforms and settings:

socialsyncs posts:create --json complex-post.json

JSON structure:

{
  "integrations": ["twitter-123", "linkedin-456"],
  "posts": [
    {
      "provider": "twitter",
      "post": [
        {
          "content": "Tweet version",
          "image": ["twitter-image.jpg"]
        }
      ]
    },
    {
      "provider": "linkedin",
      "post": [
        {
          "content": "LinkedIn version with more context...",
          "image": ["linkedin-image.jpg"]
        }
      ],
      "settings": {
        "__type": "linkedin",
        "companyId": "company-123"
      }
    }
  ]
}

All Output is JSON

Every command outputs JSON for easy parsing:

INTEGRATIONS=$(socialsyncs integrations:list | jq -r '.')
REDDIT_ID=$(echo "$INTEGRATIONS" | jq -r '.[] | select(.identifier=="reddit") | .id')

Threading Support

Comments are automatically converted to threads/replies based on platform:

• Twitter/X: Thread of tweets
• Reddit: Comment replies
• LinkedIn: Comment on post
• Instagram: First comment

socialsyncs posts:create \
  -c "Main post" \
  -c "Comment 1" \
  -c "Comment 2" \
  -i "integration-id"

---

Common Workflows

Reddit Post with Flair

#!/bin/bash
REDDIT_ID=$(socialsyncs integrations:list | jq -r '.[] | select(.identifier=="reddit") | .id')
FLAIRS=$(socialsyncs integrations:trigger "$REDDIT_ID" getFlairs -d '{"subreddit":"programming"}')
FLAIR_ID=$(echo "$FLAIRS" | jq -r '.output[0].id')

socialsyncs posts:create \
  -c "My post content" \
  -s "2024-12-31T12:00:00Z" \
  --settings "{\"subreddit\":[{\"value\":{\"subreddit\":\"programming\",\"title\":\"Post Title\",\"type\":\"text\",\"is_flair_required\":true,\"flair\":{\"id\":\"$FLAIR_ID\",\"name\":\"Discussion\"}}}]}" \
  -i "$REDDIT_ID"

YouTube Video Upload

#!/bin/bash
VIDEO=$(socialsyncs upload video.mp4)
VIDEO_PATH=$(echo "$VIDEO" | jq -r '.path')

socialsyncs posts:create \
  -c "Video description..." \
  -s "2024-12-31T12:00:00Z" \
  --settings '{"title":"My Video","type":"public","tags":[{"value":"tech","label":"Tech"}]}' \
  -m "$VIDEO_PATH" \
  -i "youtube-id"

Multi-Platform Campaign

#!/bin/bash
socialsyncs posts:create \
  -c "Same content everywhere" \
  -s "2024-12-31T12:00:00Z" \
  -m "image.jpg" \
  -i "twitter-id,linkedin-id,facebook-id"

Batch Scheduling

#!/bin/bash
DATES=("2024-02-14T09:00:00Z" "2024-02-15T09:00:00Z" "2024-02-16T09:00:00Z")
CONTENT=("Monday motivation 💪" "Tuesday tips 💡" "Wednesday wisdom 🧠")

for i in "${!DATES[@]}"; do
  socialsyncs posts:create \
    -c "${CONTENT[$i]}" \
    -s "${DATES[$i]}" \
    -i "twitter-id"
done

---

Documentation

For AI Agents:

• SKILL.md - Complete skill reference with patterns and examples

Deep-Dive Guides:

• HOW_TO_RUN.md - Installation and setup methods
• COMMAND_LINE_GUIDE.md - Complete command syntax reference
• PROVIDER_SETTINGS.md - All platform settings schemas
• INTEGRATION_TOOLS_WORKFLOW.md - Tools workflow guide
• INTEGRATION_SETTINGS_DISCOVERY.md - Settings discovery
• SUPPORTED_FILE_TYPES.md - Media format reference
• PROJECT_STRUCTURE.md - Code architecture
• PUBLISHING.md - npm publishing guide

Examples:

• examples/EXAMPLES.md - Comprehensive examples
• examples/ - Ready-to-use scripts and JSON files

---

API Endpoints

The CLI interacts with these SocialSyncs API endpoints:

Endpoint	Method	Purpose
/public/v1/posts	POST	Create a post
/public/v1/posts	GET	List posts
/public/v1/posts/:id	DELETE	Delete a post
/public/v1/posts/:id/missing	GET	Get missing content from provider
/public/v1/posts/:id/release-id	PUT	Update release ID for a post
/public/v1/integrations	GET	List integrations (optional ?group= filter)
/public/v1/groups	GET	List groups (customers)
/public/v1/integration-settings/:id	GET	Get integration settings
/public/v1/integration-trigger/:id	POST	Trigger integration tool
/public/v1/analytics/:integration	GET	Get platform analytics
/public/v1/analytics/post/:postId	GET	Get post analytics
/public/v1/upload	POST	Upload media

---

Environment Variables

Variable	Required	Default	Description
SOCIALSYNCS_API_KEY	No*	-	Your SocialSyncs API key
SOCIALSYNCS_API_URL	No	https://app.socialsyncs.co	Custom API endpoint
SOCIALSYNCS_AUTH_SERVER	No	https://app.socialsyncs.co	Custom auth server URL

*Either OAuth2 (via socialsyncs auth:login) or SOCIALSYNCS_API_KEY is required.

---

Error Handling

The CLI provides clear error messages with exit codes:

• Exit code 0: Success
• Exit code 1: Error occurred

Common errors:

Error	Solution
Not authenticated	Run socialsyncs auth:login or set SOCIALSYNCS_API_KEY
Integration not found	Run integrations:list to get valid IDs
startDate/endDate required	Use ISO 8601 format: "2024-12-31T12:00:00Z"
Invalid settings	Check integrations:settings for required fields
Tool not found	Check available tools in integrations:settings output
Upload failed	Verify file exists and format is supported
analytics:post returns {"missing": true}	Run posts:missing <id> then posts:connect <id> --release-id "<rid>"

---

Development

Project Structure

src/
├── index.ts              # CLI entry point with yargs
├── api.ts                # SocialSyncsAPI client class
├── config.ts             # Configuration (OAuth2 + API key)
└── commands/
    ├── auth.ts           # OAuth2 authentication (login/logout/status)
    ├── posts.ts          # Post management commands
    ├── integrations.ts   # Integration commands
    ├── analytics.ts      # Analytics commands
    └── upload.ts         # Media upload command
examples/                 # Example scripts and JSON files
package.json
tsconfig.json
tsup.config.ts            # Build configuration
README.md                 # This file
SKILL.md                  # AI agent reference

Scripts

pnpm run dev       # Watch mode for development
pnpm run build     # Build the CLI
pnpm run start     # Run the built CLI

Building

The CLI uses tsup for bundling:

pnpm run build

Output in dist/:

• index.js - Bundled executable with shebang
• index.js.map - Source map

---

Quick Reference

# Authentication
socialsyncs auth:login                                              # OAuth2 device flow
socialsyncs auth:status                                             # Check auth
socialsyncs auth:logout                                             # Remove credentials
export SOCIALSYNCS_API_KEY=your_key                                 # Or use API key

# Discovery
socialsyncs integrations:list                           # List integrations
socialsyncs integrations:list --group "<group-id>"      # List integrations in a group
socialsyncs integrations:groups                         # List groups (customers)
socialsyncs integrations:settings <id>                  # Get settings
socialsyncs integrations:trigger <id> <method> -d '{}'  # Fetch data

# Posting (date is required)
socialsyncs posts:create -c "text" -s "2024-12-31T12:00:00Z" -i "id"                    # Simple
socialsyncs posts:create -c "text" -s "2024-12-31T12:00:00Z" -t draft -i "id"          # Draft
socialsyncs posts:create -c "text" -m "img.jpg" -s "2024-12-31T12:00:00Z" -i "id"      # With media
socialsyncs posts:create -c "main" -c "comment" -s "2024-12-31T12:00:00Z" -i "id"      # With comment
socialsyncs posts:create -c "text" -s "2024-12-31T12:00:00Z" --settings '{}' -i "id"   # Platform-specific
socialsyncs posts:create --json file.json                                               # Complex

# Management
socialsyncs posts:list                                  # List posts
socialsyncs posts:delete <id>                          # Delete post
socialsyncs posts:status <id> --status draft           # Move to draft (stops workflow)
socialsyncs posts:status <id> --status schedule        # Queue draft for publishing
socialsyncs upload <file>                              # Upload media

# Analytics
socialsyncs analytics:platform <id>                    # Platform analytics (7 days)
socialsyncs analytics:platform <id> -d 30             # Platform analytics (30 days)
socialsyncs analytics:post <id>                        # Post analytics (7 days)
socialsyncs analytics:post <id> -d 30                 # Post analytics (30 days)
# If analytics:post returns {"missing": true}, resolve it:
socialsyncs posts:missing <id>                         # List provider content
socialsyncs posts:connect <id> --release-id "<rid>"    # Connect content to post

# Help
socialsyncs --help                                     # Show help
socialsyncs posts:create --help                        # Command help

---

Contributing

This CLI is part of the SocialSyncs monorepo.

To contribute:

1. Fork the repository
2. Create a feature branch
3. Make your changes in apps/cli/
4. Run tests: pnpm run build
5. Submit a pull request

---

License

AGPL-3.0

---

Links

• Website: socialsyncs.co
• API Docs: [app.socialsyncs.co](https://app.socialsyncs.co
• GitHub: lakshit77/socialsyncs-cli
• Issues: Report bugs

---

Supported Platforms

28+ platforms including:

Platform	Integration Tools	Settings
Twitter/X	getLists, getCommunities	who_can_reply_post
LinkedIn	getCompanies	companyId, carousel
Reddit	getFlairs, searchSubreddits	subreddit, title, flair
YouTube	getPlaylists, getCategories	title, type, tags, playlistId
TikTok	-	privacy, duet, stitch
Instagram	-	post_type (post/story)
Facebook	getPages	-
Pinterest	getBoards, getBoardSections	-
Discord	getChannels	-
Slack	getChannels	-
And 18+ more...

See PROVIDER_SETTINGS.md for complete documentation.