social-cli 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paras Raut
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,306 @@
+# social-cli
+
+The unified social media CLI for AI agents and developers. Post, schedule, and manage content across **14 platforms** from a single command — with structured JSON output for every operation.
+
+**Platforms:** Twitter/X · Instagram · Facebook · LinkedIn · TikTok · YouTube · Pinterest · Reddit · Telegram · Discord · Bluesky · Snapchat · Google Business · Threads
+
+---
+
+## Install
+
+```bash
+npm install -g social-cli
+```
+
+Or run without installing:
+
+```bash
+npx social-cli --help
+```
+
+---
+
+## Quick Setup
+
+**1. Get an API key**
+
+Sign up at [socialcli.dev](https://socialcli.dev) and go to **Dashboard → API Keys**.
+
+**2. Authenticate**
+
+```bash
+social-cli auth:set --key sk_your_api_key_here
+```
+
+**3. Verify**
+
+```bash
+social-cli auth:check
+# → { "status": "SUCCESS", "data": { "workspace": "my-brand", ... } }
+```
+
+---
+
+## Quick Start
+
+```bash
+# List your connected social accounts
+social-cli accounts list
+
+# Post immediately to Twitter
+social-cli posts create \
+  -c "Hello from Social CLI!" \
+  -p twitter \
+  -a <accountId> \
+  --now
+
+# Schedule a post
+social-cli posts create \
+  -c "Scheduled content" \
+  -p twitter \
+  -a <accountId> \
+  --schedule "2025-06-01T09:00:00Z"
+
+# Upload media then post with it
+social-cli upload ./photo.jpg
+# → { "publicUrl": "https://cdn.socialcli.dev/..." }
+
+social-cli posts create \
+  -c "Post with image!" \
+  -p twitter \
+  -a <accountId> \
+  --media "https://cdn.socialcli.dev/..." \
+  --now
+
+# Cross-post to multiple platforms at once
+social-cli posts create \
+  -c "Cross-platform launch!" \
+  -p twitter -a <twitterId> \
+  -p instagram -a <instagramId> \
+  -p linkedin -a <linkedinId> \
+  --now
+
+# Add to your posting queue
+social-cli posts create \
+  -c "Queued post" \
+  -p twitter \
+  -a <accountId> \
+  --queue
+```
+
+---
+
+## Commands
+
+### Auth
+
+```bash
+social-cli auth:set --key <apiKey>   # Save API key locally
+social-cli auth:check                # Verify key and show workspace info
+social-cli auth:whoami               # Show current saved key
+social-cli auth:logout               # Remove saved key
+```
+
+### Accounts
+
+```bash
+social-cli accounts list                           # List all connected accounts
+social-cli accounts health                         # Check OAuth token validity
+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> <appPass>     # Connect Bluesky (no OAuth needed)
+```
+
+Supported platforms: `twitter` `instagram` `facebook` `linkedin` `tiktok` `youtube` `pinterest` `reddit` `telegram` `discord` `snapchat` `googlebusiness` `threads`
+
+### Posts
+
+```bash
+social-cli posts list [--status <s>] [--platform <p>] [--limit <n>]
+social-cli posts create -c <text> -p <platform> -a <accountId> [options]
+social-cli posts get <postId>
+social-cli posts delete <postId>
+social-cli posts retry <postId>
+social-cli posts stats
+social-cli posts validate -c <text> -p <platform> -a <accountId>
+```
+
+**`posts create` flags:**
+
+| Flag | Description |
+|------|-------------|
+| `-c, --content <text>` | Post text content |
+| `-p, --platform <name>` | Target platform (repeatable) |
+| `-a, --account <id>` | Account ID (repeatable) |
+| `-m, --media <url>` | Media URL — use `social-cli upload` first (repeatable) |
+| `--media-type <type>` | `image`, `video`, or `gif` (default: `image`) |
+| `--now` | Publish immediately |
+| `--draft` | Save as draft |
+| `--schedule <datetime>` | ISO 8601 UTC datetime e.g. `"2025-06-01T09:00:00Z"` |
+| `--queue` | Add to next available queue slot |
+| `--timezone <tz>` | Timezone e.g. `"America/New_York"` |
+| `--json <file>` | Load post data from a JSON file |
+
+### Media
+
+```bash
+social-cli upload <filePath>                       # Upload local file → returns publicUrl
+social-cli upload:url --filename <n> --type <mime> # Get raw presigned S3 URL
+```
+
+Supported: `image/jpeg` `image/png` `image/gif` `image/webp` `video/mp4` `video/quicktime` `application/pdf`
+
+### Queue
+
+```bash
+social-cli queue list                              # Show your posting schedule
+social-cli queue set --slots <file.json> --timezone <tz>   # Set recurring slots
+social-cli queue next                              # Show next available slot
+social-cli queue preview [--count <n>]             # Preview upcoming N slots
+```
+
+**Slots JSON format:**
+```json
+[
+  { "day": "MON", "time": "09:00" },
+  { "day": "WED", "time": "14:00" },
+  { "day": "FRI", "time": "17:00" }
+]
+```
+
+### Profile
+
+```bash
+social-cli profile get
+social-cli profile update [--name <name>] [--description <desc>] [--color <hex>]
+```
+
+### Analytics & Usage
+
+```bash
+social-cli analytics [--platform <p>] [--from <date>] [--to <date>]
+social-cli usage
+```
+
+### Twitter/X Engagement
+
+```bash
+social-cli twitter retweet <accountId> <tweetId>
+social-cli twitter bookmark <accountId> <tweetId>
+social-cli twitter follow <accountId> <targetUserId>
+social-cli twitter unfollow <accountId> <targetUserId>
+```
+
+---
+
+## Output Format
+
+Every command returns JSON to stdout:
+
+```json
+{
+  "status": "SUCCESS",
+  "message": "Post created successfully",
+  "data": {
+    "postId": "post_abc123",
+    "status": "scheduled",
+    "scheduledFor": "2025-06-01T09:00:00Z"
+  }
+}
+```
+
+Errors:
+
+```json
+{
+  "status": "ERROR",
+  "message": "SOCIAL_CLI_API_KEY not set. Run: social-cli auth:set --key sk_...",
+  "data": null
+}
+```
+
+Exit code `0` on success, `1` on error — works cleanly in shell scripts and CI pipelines.
+
+---
+
+## Environment Variables
+
+```bash
+SOCIAL_CLI_API_KEY=sk_your_key       # Required — your API key
+SOCIAL_CLI_API_URL=https://...       # Optional — custom backend URL
+```
+
+---
+
+## AI Agent Integration
+
+### MCP (Claude Desktop, Cursor, OpenClaw)
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "social-cli": {
+      "url": "https://api.socialcli.dev/mcp",
+      "headers": {
+        "x-api-key": "sk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+Then just tell your agent:
+> "Post 'Launching our new feature!' to Twitter with ./assets/launch.png, schedule for tomorrow 9am UTC"
+
+### X402 Protocol (Pay-per-use for agents)
+
+Social CLI supports the [X402 payment protocol](https://x402.org) — agents can pay per API call without a subscription:
+
+```bash
+# Agents authenticate via X402 — no subscription required
+# Payments processed in USDC on Base or Solana
+```
+
+### SKILL.md (OpenClaw auto-discovery)
+
+The bundled `SKILL.md` is auto-discovered by OpenClaw and other skill-based agents. Install globally and it just works:
+
+```bash
+npm install -g social-cli
+export SOCIAL_CLI_API_KEY=sk_your_key
+social-cli accounts list
+```
+
+### Batch scheduling example
+
+```bash
+for day in 1 2 3 4 5; do
+  social-cli posts create \
+    -c "Day $day of our launch week!" \
+    --schedule "2025-06-0${day}T09:00:00Z" \
+    -p twitter -a <accountId>
+done
+```
+
+---
+
+## Pricing
+
+| Plan | Price | Posts/mo |
+|------|-------|----------|
+| Standard | $19/mo | 200 |
+| Team | $29/mo | 500 |
+| Pro | $49/mo | 1,000 |
+| Ultimate | $99/mo | Unlimited |
+
+All plans include CLI access, MCP server, API keys, and all 14 platforms.
+
+Get started at [socialcli.dev](https://socialcli.dev)
+
+---
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: social-cli
+description: Social media automation CLI — schedule, publish, and manage posts across 14 platforms (Twitter/X, Instagram, Facebook, LinkedIn, TikTok, YouTube, Pinterest, Reddit, Telegram, Discord, Bluesky, Snapchat, Google Business, Threads)
+metadata:
+  openclaw:
+    requirements:
+      env:
+        - SOCIAL_CLI_API_KEY
+        - SOCIAL_CLI_API_URL
+      binaries:
+        - social-cli
+---
+
+# Social CLI — Social Media Automation
+
+Automate social media posting across 14 platforms. Every command outputs structured JSON.
+
+## 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://api.socialcli.dev
+
+# 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
+}
+```