social-cli

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: social-cli
slug: social-cli
version: 0.0.3
description: Social media automation for AI agents — post, schedule, analyze, and manage across 15 platforms via CLI or MCP server.
author: socialcli
homepage: https://socialcli.xyz
repository: https://github.com/social-cli/social-cli-skill
license: MIT
runtime: node
permissions:
  - network
  - env
tags:
  - social-media
  - mcp
  - twitter
  - instagram
  - linkedin
  - tiktok
  - youtube
  - scheduling
  - analytics
  - ai-agent
  - automation
---

# 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 create -c <content> -p <platform> -a <accountId> [options]` — Create/schedule a post
- `social-cli posts list [--status <status>] [--platform <platform>] [--limit <n>]` — List posts
- `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>] [--limit <n>] [--page <n>]` — Get post analytics
- `social-cli facebook-insights --account <accountId>` — Get Facebook Page insights

### 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"

# Post with image (upload first)
social-cli upload ./photo.jpg
# → returns: { "publicUrl": "https://..." }
social-cli posts create \
  -c "Post with image!" \
  -p twitter \
  -a <accountId> \
  --media "https://..." \
  --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
```

## MCP Server

Social CLI also ships as an MCP server for direct agent integration:

```json
{
  "mcpServers": {
    "social-cli": {
      "url": "https://backend.socialcli.xyz/mcp/social-cli",
      "auth": "Bearer ${SOCIAL_CLI_API_KEY}"
    }
  }
}
```

35+ tools available via MCP: posting, scheduling, inbox, analytics, queue management, and more.

## AI Agent Workflow

```
1. social-cli accounts list