---
name: social-cli
slug: social-cli
version: 0.0.3
description: Social media automation CLI for AI agents — post, schedule, analyze, and manage across 15 platforms (Twitter/X, Instagram, Facebook, LinkedIn, TikTok, YouTube, Pinterest, Reddit, Telegram, Discord, Bluesky, Snapchat, WhatsApp, Google Business, Threads)
author: socialcli
homepage: https://socialcli.xyz
repository: https://github.com/social-cli/social-cli-skill
license: MIT
runtime: node
permissions:
  - network
  - env
metadata:
  openclaw:
    requirements:
      env:
        - SOCIAL_CLI_API_KEY
        - SOCIAL_CLI_API_URL
      binaries:
        - social-cli
---

# Social CLI — Social Media Automation for AI Agents

Automate social media posting across 15 platforms. Every command outputs structured JSON. MCP-native — plug into Claude, Cursor, ChatGPT, or any agent runtime.

## Setup

```bash
# Install
npm install -g social-cli

# Set credentials
export SOCIAL_CLI_API_KEY=sk_your_api_key_here
export SOCIAL_CLI_API_URL=https://backend.socialcli.xyz

# Verify
social-cli auth:check
```

## Available Commands

### Accounts
- `social-cli accounts list` — List all connected social media accounts
- `social-cli accounts health` — Check token validity of all accounts
- `social-cli accounts connect <platform>` — Get OAuth URL to connect a platform
- `social-cli accounts disconnect <accountId>` — Disconnect an account
- `social-cli accounts bluesky <handle> <appPassword>` — Connect Bluesky via credentials

### Posts
- `social-cli posts list [--status <status>] [--platform <platform>] [--limit <n>]` — List posts
- `social-cli posts create -c <content> -p <platform> -a <accountId> [options]` — Create/schedule a post
- `social-cli posts get <postId>` — Get post details
- `social-cli posts delete <postId>` — Delete a post
- `social-cli posts retry <postId>` — Retry a failed post
- `social-cli posts stats` — Get post counts by status
- `social-cli posts validate -c <content> -p <platform> -a <accountId>` — Validate before posting

### Media
- `social-cli upload <filePath>` — Upload a local file, returns publicUrl for use in posts
- `social-cli upload:url` — Get a raw presigned upload URL

### Queue
- `social-cli queue list` — Show posting queue schedule
- `social-cli queue set --slots <json> --timezone <tz>` — Set queue schedule
- `social-cli queue next` — Get next queue slot time
- `social-cli queue preview [--count <n>]` — Preview upcoming queue times

### Profile
- `social-cli profile get` — Get your workspace profile
- `social-cli profile update [--name <name>] [--description <desc>]` — Update profile

### Analytics
- `social-cli analytics [--platform <platform>]` — Get post analytics

### Usage
- `social-cli usage` — Get plan usage stats

## Post Creation Examples

```bash
# Publish immediately to Twitter
social-cli posts create \
  -c "Hello from Social CLI!" \
  -p twitter \
  -a <accountId> \
  --now

# Schedule for a specific time
social-cli posts create \
  -c "Scheduled post content" \
  -p twitter \
  -a <accountId> \
  --schedule "2025-06-01T09:00:00Z"

# Save as draft
social-cli posts create \
  -c "Draft content" \
  -p twitter \
  -a <accountId> \
  --draft

# Post with image (upload first)
social-cli upload ./photo.jpg
# → returns: { "publicUrl": "https://media.zernio.com/..." }
social-cli posts create \
  -c "Post with image!" \
  -p twitter \
  -a <accountId> \
  --media "https://media.zernio.com/..." \
  --media-type image \
  --now

# Post to multiple platforms
social-cli posts create \
  -c "Cross-platform post!" \
  -p twitter -a <twitterAccountId> \
  -p instagram -a <instagramAccountId> \
  --now

# Add to queue
social-cli posts create \
  -c "Queued post" \
  -p twitter \
  -a <accountId> \
  --queue
```

## AI Agent Workflow

```
1. social-cli accounts list          → discover accountIds
2. social-cli upload ./image.png     → get publicUrl for media
3. social-cli posts create ...       → create/schedule post
4. social-cli posts list             → verify post was created
```

## Output Format

All commands output JSON:
```json
{
  "status": "SUCCESS",
  "message": "...",
  "data": { ... }
}
```

Errors:
```json
{
  "status": "ERROR",
  "message": "...",
  "data": null
}
```