{"_id":"@butterflysocial/agent-skill","_rev":"4-1ebff79a5a1cff1cdf692e0717d3049e","name":"@butterflysocial/agent-skill","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.0":{"name":"@butterflysocial/agent-skill","version":"1.0.0","keywords":["butterfly-social","cli","social-media","scheduling","automation","ai-agent","command-line","twitter","linkedin","facebook","instagram","tiktok","youtube","reddit"],"author":{"name":"Butterfly Social"},"license":"AGPL-3.0","_id":"@butterflysocial/agent-skill@1.0.0","maintainers":[{"name":"maestrotechnologysolutions","email":"maestrotechnologysolutions@gmail.com"}],"homepage":"https://github.com/butterflysocial/agent-skill#readme","bugs":{"url":"https://github.com/butterflysocial/agent-skill/issues"},"bin":{"bsocial":"dist/index.js"},"dist":{"shasum":"8a24bae7d2e535f284b43b42089bf0b8df05e3b4","tarball":"https://registry.npmjs.org/@butterflysocial/agent-skill/-/agent-skill-1.0.0.tgz","fileCount":8,"integrity":"sha512-yFFaVbAKapgKxe9dq00+FZwYwfbHhElCAqQwFoqSUWjyfO5D5tbI1kzwwnQu9UpDlswYxJf25jDLwbYJ2lPOdA==","signatures":[{"sig":"MEQCIBZVLqTmwY6aQWq2SxiQgnNWNQDyayCc4w5GmWAUnvWZAiAtJVphHEGKLGfPH7Z4URm1N+0thNZU0sN3B0t6dK1rmg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":159160},"main":"dist/index.js","engines":{"node":">=18.0.0"},"gitHead":"a6e07c8b50fd8a423ce3eb9991ae16bd0e997bcc","scripts":{"dev":"tsup --watch","build":"tsup","start":"node ./dist/index.js","publish":"tsup && pnpm publish --access public --no-git-checks","prepublishOnly":"pnpm run build"},"_npmUser":{"name":"maestrotechnologysolutions","email":"maestrotechnologysolutions@gmail.com"},"repository":{"url":"git+https://github.com/butterflysocial/agent-skill.git","type":"git"},"_npmVersion":"11.13.0","description":"Butterfly Social CLI - Command line interface + AI agent skill for the Butterfly Social API. Fork of the Postiz Agents CLI (gitroomhq/postiz-agent), retargeted at Butterfly Social's backend.","directories":{},"_nodeVersion":"24.16.0","dependencies":{"yargs":"^17.7.2","@types/pg":"^8.20.0","node-fetch":"^3.3.2"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","typescript":"^5.3.3","@types/node":"^20.11.19","@types/yargs":"^17.0.32"},"_npmOperationalInternal":{"tmp":"tmp/agent-skill_1.0.0_1788316785834_0.5012590459930308","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@butterflysocial/agent-skill","version":"1.0.1","keywords":["butterfly-social","cli","social-media","scheduling","automation","ai-agent","command-line","twitter","linkedin","facebook","instagram","tiktok","youtube","reddit"],"author":{"name":"Butterfly Social"},"license":"AGPL-3.0","_id":"@butterflysocial/agent-skill@1.0.1","maintainers":[{"name":"maestrotechnologysolutions","email":"maestrotechnologysolutions@gmail.com"}],"homepage":"https://github.com/maestrotechnologysolutions-cmd/butterfly-social#readme","bugs":{"url":"https://github.com/maestrotechnologysolutions-cmd/butterfly-social/issues"},"bin":{"bsocial":"dist/index.js"},"dist":{"shasum":"375e0c41e6c5f65fdc246a88bbcb1e508cdf21d5","tarball":"https://registry.npmjs.org/@butterflysocial/agent-skill/-/agent-skill-1.0.1.tgz","fileCount":8,"integrity":"sha512-7HYhtfKlhpNmOuMfvGO/KkTZHVXn+UWyOFiRAFAshLO7YJvr16a0lCZoBRkviUlzw50klmhXA3TLUEVLaVWNeg==","signatures":[{"sig":"MEQCIENMv4XZpNS0sgSMBZ7JYlu+ncT6yBYNh2svRGj9yT4RAiAxd15fsew5JyvVn5J1fiIOswV8pqz41VWkfP2lrmTgVQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":159367},"main":"dist/index.js","engines":{"node":">=18.0.0"},"gitHead":"a6e07c8b50fd8a423ce3eb9991ae16bd0e997bcc","scripts":{"dev":"tsup --watch","build":"tsup","start":"node ./dist/index.js","publish":"tsup && pnpm publish --access public --no-git-checks","prepublishOnly":"pnpm run build"},"_npmUser":{"name":"maestrotechnologysolutions","email":"maestrotechnologysolutions@gmail.com"},"repository":{"url":"git+https://github.com/maestrotechnologysolutions-cmd/butterfly-social.git","type":"git"},"_npmVersion":"11.13.0","description":"Butterfly Social CLI - Command line interface + AI agent skill for the Butterfly Social API. Fork of the Postiz Agents CLI (gitroomhq/postiz-agent), retargeted at Butterfly Social's backend.","directories":{},"_nodeVersion":"24.16.0","dependencies":{"yargs":"^17.7.2","@types/pg":"^8.20.0","node-fetch":"^3.3.2"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","typescript":"^5.3.3","@types/node":"^20.11.19","@types/yargs":"^17.0.32"},"_npmOperationalInternal":{"tmp":"tmp/agent-skill_1.0.1_1788316873125_0.2662730291337372","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@butterflysocial/agent-skill","version":"1.0.2","keywords":["butterfly-social","cli","social-media","scheduling","automation","ai-agent","command-line","twitter","linkedin","facebook","instagram","tiktok","youtube","reddit"],"author":{"name":"Butterfly Social"},"license":"AGPL-3.0","_id":"@butterflysocial/agent-skill@1.0.2","maintainers":[{"name":"maestrotechnologysolutions","email":"maestrotechnologysolutions@gmail.com"}],"homepage":"https://github.com/maestrotechnologysolutions-cmd/butterfly-social#readme","bugs":{"url":"https://github.com/maestrotechnologysolutions-cmd/butterfly-social/issues"},"bin":{"bsocial":"dist/index.js"},"dist":{"shasum":"440afb7301c35e332ad175c8df5b2b3fb32e23e6","tarball":"https://registry.npmjs.org/@butterflysocial/agent-skill/-/agent-skill-1.0.2.tgz","fileCount":8,"integrity":"sha512-U69nzynUzl4xCz/vJ8esFuuNqo/tt1FR6YHhCYNB1nBZlE9H/3RfK4SLo5uiXsx4H2jkZhalfpkylNRk9i+jhA==","signatures":[{"sig":"MEUCICTJZxJDvbhvjzv58Tfub01tInbNF7WChqugpLHUqNHQAiEA/sKTFprp2R2gwCgnkl9VzS+7/CzYC+U6V5ws4bM+b9U=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":159367},"main":"dist/index.js","engines":{"node":">=18.0.0"},"gitHead":"a6e07c8b50fd8a423ce3eb9991ae16bd0e997bcc","scripts":{"dev":"tsup --watch","build":"tsup","start":"node ./dist/index.js","publish":"tsup && pnpm publish --access public --no-git-checks","prepublishOnly":"pnpm run build"},"_npmUser":{"name":"maestrotechnologysolutions","email":"maestrotechnologysolutions@gmail.com"},"repository":{"url":"git+https://github.com/maestrotechnologysolutions-cmd/butterfly-social.git","type":"git"},"_npmVersion":"11.13.0","description":"Butterfly Social CLI - Command line interface + AI agent skill for the Butterfly Social API. Fork of the Postiz Agents CLI (gitroomhq/postiz-agent), retargeted at Butterfly Social's backend.","directories":{},"_nodeVersion":"24.16.0","dependencies":{"yargs":"^17.7.2","@types/pg":"^8.20.0","node-fetch":"^3.3.2"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","typescript":"^5.3.3","@types/node":"^20.11.19","@types/yargs":"^17.0.32"},"_npmOperationalInternal":{"tmp":"tmp/agent-skill_1.0.2_1788316919456_0.473201595033651","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@butterflysocial/agent-skill","version":"1.1.0","description":"Butterfly Social CLI - Command line interface + AI agent skill for the Butterfly Social API. Fork of the Postiz Agents CLI (gitroomhq/postiz-agent), retargeted at Butterfly Social's backend.","main":"dist/index.js","bin":{"bsocial":"dist/index.js"},"scripts":{"dev":"tsup --watch","build":"tsup","start":"node ./dist/index.js","prepublishOnly":"pnpm run build","publish":"tsup && pnpm publish --access public --no-git-checks"},"keywords":["butterfly-social","cli","social-media","scheduling","automation","ai-agent","command-line","twitter","linkedin","facebook","instagram","tiktok","youtube","reddit"],"author":{"name":"Butterfly Social"},"license":"AGPL-3.0","repository":{"type":"git","url":"git+https://github.com/maestrotechnologysolutions-cmd/butterfly-social.git"},"homepage":"https://github.com/maestrotechnologysolutions-cmd/butterfly-social#readme","bugs":{"url":"https://github.com/maestrotechnologysolutions-cmd/butterfly-social/issues"},"engines":{"node":">=18.0.0"},"dependencies":{"@types/pg":"^8.20.0","node-fetch":"^3.3.2","yargs":"^17.7.2"},"devDependencies":{"@types/node":"^20.11.19","@types/yargs":"^17.0.32","tsup":"^8.5.1","typescript":"^5.3.3"},"gitHead":"a6e07c8b50fd8a423ce3eb9991ae16bd0e997bcc","_id":"@butterflysocial/agent-skill@1.1.0","_nodeVersion":"24.16.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-GioHsZe47DpY/saRSqNW5J9d/xmpP9XWwl9bobtdV64lVctzAQWbP61oAB7Nt6HXNd9RfL0kU2keVju0qllktQ==","shasum":"d7b7334b829cd4c129097efea6dc1c41e374e57e","tarball":"https://registry.npmjs.org/@butterflysocial/agent-skill/-/agent-skill-1.1.0.tgz","fileCount":8,"unpackedSize":159367,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDaihsWwqXcXZlpqoJYHIEgcF5QHW8+4EuCMj+alhm50QIgQnZg59yKPi8Z4GJCHC0R8SGTc2MFtnUnZ3rBXwA6Esk="}]},"_npmUser":{"name":"maestrotechnologysolutions","email":"maestrotechnologysolutions@gmail.com"},"directories":{},"maintainers":[{"name":"maestrotechnologysolutions","email":"maestrotechnologysolutions@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-skill_1.1.0_1788316972602_0.44103120276180263"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-02T02:39:45.721Z","modified":"2026-09-02T02:42:52.889Z","1.0.0":"2026-09-02T02:39:45.971Z","1.0.1":"2026-09-02T02:41:13.260Z","1.0.2":"2026-09-02T02:41:59.580Z","1.1.0":"2026-09-02T02:42:52.727Z"},"bugs":{"url":"https://github.com/maestrotechnologysolutions-cmd/butterfly-social/issues"},"author":{"name":"Butterfly Social"},"license":"AGPL-3.0","homepage":"https://github.com/maestrotechnologysolutions-cmd/butterfly-social#readme","keywords":["butterfly-social","cli","social-media","scheduling","automation","ai-agent","command-line","twitter","linkedin","facebook","instagram","tiktok","youtube","reddit"],"repository":{"type":"git","url":"git+https://github.com/maestrotechnologysolutions-cmd/butterfly-social.git"},"description":"Butterfly Social CLI - Command line interface + AI agent skill for the Butterfly Social API. Fork of the Postiz Agents CLI (gitroomhq/postiz-agent), retargeted at Butterfly Social's backend.","maintainers":[{"name":"maestrotechnologysolutions","email":"maestrotechnologysolutions@gmail.com"}],"readme":"## Install as a skill\n\n```bash\nnpx skills add butterflysocial/agent-skill\n```\n\n# Butterfly Social CLI\n\n**Social media automation CLI for AI agents** - Schedule posts across 28+ platforms programmatically.\n\nThe Butterfly Social CLI provides a command-line interface to the Butterfly Social 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.\n\n---\n\n## Installation\n\n### From npm (Recommended)\n\n```bash\nnpm install -g @butterflysocial/agent-skill\n# or\npnpm install -g @butterflysocial/agent-skill\n```\n\n---\n\n## Authentication\n\n### Option 1: OAuth2 (Recommended)\n\nAuthenticate using the device flow — no client ID or secret needed:\n\n```bash\nbsocial auth:login\n```\n\nThis will:\n1. Display a one-time code in your terminal\n2. Open your browser to authorize\n3. Automatically save credentials to `~/.butterfly-social/credentials.json`\n\n```bash\n# Check current auth status (verifies credentials are still valid)\nbsocial auth:status\n\n# Remove stored credentials\nbsocial auth:logout\n```\n\n#### Self-Hosting the Auth Server\n\nButterfly Social does not run a hosted OAuth2 device-flow auth server. `bsocial auth:login` requires `--auth-server <url>` (or `BUTTERFLY_AUTH_SERVER`) pointing at your own deployment — follow the self-hosting guide in [`server/SERVER.md`](./server/SERVER.md). API key auth (above) is the supported path otherwise.\n\n### Option 2: API Key\n\n```bash\nexport BUTTERFLY_API_KEY=your_api_key_here\n```\n\n**Optional:** Custom API endpoint\n\n```bash\nexport BUTTERFLY_API_URL=https://your-custom-api.com\n```\n\n> **Note:** OAuth2 credentials take priority over the API key when both are present.\n\n---\n\n## Commands\n\n### Discovery & Settings\n\n**List all connected integrations**\n```bash\nbsocial integrations:list\nbsocial integrations:list --group \"customer-id\"\n```\n\nReturns integration IDs, provider names, and metadata. Use `--group` to return only the channels assigned to a specific group (customer).\n\n**List all groups (customers)**\n```bash\nbsocial integrations:groups\n```\n\nReturns all groups (customers) for your organization as `{id, name}`. Use a group's `id` with `integrations:list --group` to filter channels.\n\n**Get integration settings schema**\n```bash\nbsocial integrations:settings <integration-id>\n```\n\nReturns character limits, required settings, and available tools for fetching dynamic data.\n\n**Trigger integration tools**\n```bash\nbsocial integrations:trigger <integration-id> <method-name>\nbsocial integrations:trigger <integration-id> <method-name> -d '{\"key\":\"value\"}'\n```\n\nFetch dynamic data like Reddit flairs, YouTube playlists, LinkedIn companies, etc.\n\n**Examples:**\n```bash\n# Get Reddit flairs\nbsocial integrations:trigger reddit-123 getFlairs -d '{\"subreddit\":\"programming\"}'\n\n# Get YouTube playlists\nbsocial integrations:trigger youtube-456 getPlaylists\n\n# Get LinkedIn companies\nbsocial integrations:trigger linkedin-789 getCompanies\n```\n\n---\n\n### Creating Posts\n\n**Simple scheduled post**\n```bash\nbsocial posts:create -c \"Content\" -s \"2024-12-31T12:00:00Z\" -i \"integration-id\"\n```\n\n**Draft post**\n```bash\nbsocial posts:create -c \"Content\" -s \"2024-12-31T12:00:00Z\" -t draft -i \"integration-id\"\n```\n\n**Post with media**\n```bash\nbsocial posts:create -c \"Content\" -m \"img1.jpg,img2.jpg\" -s \"2024-12-31T12:00:00Z\" -i \"integration-id\"\n```\n\n**Post with comments** (each comment can have its own media)\n```bash\nbsocial posts:create \\\n  -c \"Main post\" -m \"main.jpg\" \\\n  -c \"First comment\" -m \"comment1.jpg\" \\\n  -c \"Second comment\" -m \"comment2.jpg,comment3.jpg\" \\\n  -s \"2024-12-31T12:00:00Z\" \\\n  -i \"integration-id\"\n```\n\n**Multi-platform post**\n```bash\nbsocial posts:create -c \"Content\" -s \"2024-12-31T12:00:00Z\" -i \"twitter-id,linkedin-id,facebook-id\"\n```\n\n**Platform-specific settings**\n```bash\nbsocial posts:create \\\n  -c \"Content\" \\\n  -s \"2024-12-31T12:00:00Z\" \\\n  --settings '{\"subreddit\":[{\"value\":{\"subreddit\":\"programming\",\"title\":\"Post Title\",\"type\":\"text\"}}]}' \\\n  -i \"reddit-id\"\n```\n\n**Complex post from JSON file**\n```bash\nbsocial posts:create --json post.json\n```\n\n**Options:**\n- `-c, --content` - Post/comment content (use multiple times for posts with comments)\n- `-s, --date` - Schedule date in ISO 8601 format (REQUIRED)\n- `-t, --type` - Post type: \"schedule\" or \"draft\" (default: \"schedule\")\n- `-m, --media` - Comma-separated media URLs for corresponding `-c`\n- `-i, --integrations` - Comma-separated integration IDs (required)\n- `-d, --delay` - Delay between comments in minutes (default: 0)\n- `--settings` - Platform-specific settings as JSON string\n- `-j, --json` - Path to JSON file with full post structure\n- `--shortLink` - Use short links (default: true)\n\n---\n\n### Managing Posts\n\n**List posts**\n```bash\nbsocial posts:list\nbsocial posts:list --startDate \"2024-01-01T00:00:00Z\" --endDate \"2024-12-31T23:59:59Z\"\nbsocial posts:list --customer \"customer-id\"\n```\n\nDefaults to last 30 days to next 30 days if dates not specified. Each returned post includes its current `settings` (returned as a JSON string — `JSON.parse` it). The intended workflow is `posts:list` (read current settings) → `posts:settings` (patch them).\n\n**Delete post**\n```bash\nbsocial posts:delete <post-id>\n```\n\n**Change post status (draft ↔ schedule)**\n```bash\nbsocial posts:status <post-id> --status draft\nbsocial posts:status <post-id> --status schedule\n```\n\nMove 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.\n\n**Update a post's provider-specific settings**\n```bash\nbsocial posts:settings <post-id> --settings '{\"content_posting_method\":\"DIRECT_POST\"}'\nbsocial posts:settings <post-id> --settings '{\"subreddit\":[{\"value\":{\"subreddit\":\"/r/selfhosted\",\"title\":\"My title\",\"type\":\"self\",\"is_flair_required\":true}}]}'\n```\n\nPatches a post's settings server-side. The backend **merges** the object — only the keys you pass change, everything else is preserved — so pass a partial object, not the full settings blob. Only **DRAFT/QUEUE** (unpublished) posts can be updated; published posts are rejected. Pass the **main post id**, not a comment id. Do **not** include `__type` — the backend adds it automatically from the integration.\n\n---\n\n### Analytics\n\n**Get platform analytics**\n```bash\nbsocial analytics:platform <integration-id>\nbsocial analytics:platform <integration-id> -d 30\n```\n\nReturns 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).\n\n**Get post analytics**\n```bash\nbsocial analytics:post <post-id>\nbsocial analytics:post <post-id> -d 30\n```\n\nReturns metrics like likes, comments, shares, and impressions for a specific published post.\n\n**⚠️ 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:\n\n```bash\n# 1. List available content from the provider\nbsocial posts:missing <post-id>\n\n# 2. Connect the correct content to the post\nbsocial posts:connect <post-id> --release-id \"7321456789012345678\"\n\n# 3. Analytics will now work\nbsocial analytics:post <post-id>\n```\n\n---\n\n### Connecting Missing Posts\n\nSome 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.\n\n**List available content from the provider**\n```bash\nbsocial posts:missing <post-id>\n```\n\nReturns an array of `{id, url}` items representing recent content from the provider. Returns an empty array if the provider doesn't support this feature.\n\n**Connect a post to its published content**\n```bash\nbsocial posts:connect <post-id> --release-id \"<content-id>\"\n```\n\n---\n\n### Media Upload\n\n**Upload file and get URL**\n```bash\nbsocial upload <file-path>\n```\n\n**⚠️ IMPORTANT: Upload Files Before Posting**\n\nYou **must** upload media files to Butterfly Social before using them in posts. Many platforms (especially TikTok, Instagram, and YouTube) require verified/trusted URLs and will reject external links.\n\n**Workflow:**\n1. Upload your file using `bsocial upload`\n2. Extract the returned URL\n3. Use that URL in your post's `-m` parameter\n\n**Supported formats:**\n- **Images:** PNG, JPG, JPEG, GIF\n- **Videos:** MP4\n\n**Example:**\n```bash\n# 1. Upload the file first\nRESULT=$(bsocial upload video.mp4)\nPATH=$(echo \"$RESULT\" | jq -r '.path')\n\n# 2. Use the Butterfly Social URL in your post\nbsocial posts:create -c \"Check out my video!\" -s \"2024-12-31T12:00:00Z\" -m \"$PATH\" -i \"tiktok-id\"\n```\n\n**Why this is required:**\n- **TikTok, Instagram, YouTube** only accept URLs from trusted domains\n- **Security:** Platforms verify media sources to prevent abuse\n- **Reliability:** Butterfly Social ensures your media is always accessible\n\n---\n\n## Platform-Specific Features\n\n### Reddit\n```bash\n# Get available flairs\nbsocial integrations:trigger reddit-id getFlairs -d '{\"subreddit\":\"programming\"}'\n\n# Post with subreddit and flair\nbsocial posts:create \\\n  -c \"Content\" \\\n  -s \"2024-12-31T12:00:00Z\" \\\n  --settings '{\"subreddit\":[{\"value\":{\"subreddit\":\"programming\",\"title\":\"My Post\",\"type\":\"text\",\"is_flair_required\":true,\"flair\":{\"id\":\"flair-123\",\"name\":\"Discussion\"}}}]}' \\\n  -i \"reddit-id\"\n```\n\n### YouTube\n```bash\n# Get playlists\nbsocial integrations:trigger youtube-id getPlaylists\n\n# Upload video FIRST (required!)\nVIDEO=$(bsocial upload video.mp4)\nVIDEO_URL=$(echo \"$VIDEO\" | jq -r '.path')\n\n# Post with uploaded video URL\nbsocial posts:create \\\n  -c \"Video description\" \\\n  -s \"2024-12-31T12:00:00Z\" \\\n  --settings '{\"title\":\"Video Title\",\"type\":\"public\",\"tags\":[{\"value\":\"tech\",\"label\":\"Tech\"}],\"playlistId\":\"playlist-id\"}' \\\n  -m \"$VIDEO_URL\" \\\n  -i \"youtube-id\"\n```\n\n### TikTok\n```bash\n# Upload video FIRST (TikTok only accepts verified URLs!)\nVIDEO=$(bsocial upload video.mp4)\nVIDEO_URL=$(echo \"$VIDEO\" | jq -r '.path')\n\n# Post with uploaded video URL\nbsocial posts:create \\\n  -c \"Video caption #fyp\" \\\n  -s \"2024-12-31T12:00:00Z\" \\\n  --settings '{\"privacy_level\":\"PUBLIC_TO_EVERYONE\",\"duet\":true,\"stitch\":true,\"content_posting_method\":\"DIRECT_POST\"}' \\\n  -m \"$VIDEO_URL\" \\\n  -i \"tiktok-id\"\n```\n\n### LinkedIn\n```bash\n# Get companies you can post to\nbsocial integrations:trigger linkedin-id getCompanies\n\n# Post as company\nbsocial posts:create \\\n  -c \"Company announcement\" \\\n  -s \"2024-12-31T12:00:00Z\" \\\n  --settings '{\"companyId\":\"company-123\"}' \\\n  -i \"linkedin-id\"\n```\n\n### X (Twitter)\n```bash\n# Create thread\nbsocial posts:create \\\n  -c \"Thread 1/3 🧵\" \\\n  -c \"Thread 2/3\" \\\n  -c \"Thread 3/3\" \\\n  -s \"2024-12-31T12:00:00Z\" \\\n  -d 2000 \\\n  -i \"twitter-id\"\n\n# With reply settings\nbsocial posts:create \\\n  -c \"Tweet content\" \\\n  -s \"2024-12-31T12:00:00Z\" \\\n  --settings '{\"who_can_reply_post\":\"everyone\"}' \\\n  -i \"twitter-id\"\n```\n\n### Instagram\n```bash\n# Upload image FIRST (Instagram requires verified URLs!)\nIMAGE=$(bsocial upload image.jpg)\nIMAGE_URL=$(echo \"$IMAGE\" | jq -r '.path')\n\n# Regular post\nbsocial posts:create \\\n  -c \"Caption #hashtag\" \\\n  -s \"2024-12-31T12:00:00Z\" \\\n  --settings '{\"post_type\":\"post\"}' \\\n  -m \"$IMAGE_URL\" \\\n  -i \"instagram-id\"\n\n# Story (upload first)\nSTORY=$(bsocial upload story.jpg)\nSTORY_URL=$(echo \"$STORY\" | jq -r '.path')\n\nbsocial posts:create \\\n  -c \"\" \\\n  -s \"2024-12-31T12:00:00Z\" \\\n  --settings '{\"post_type\":\"story\"}' \\\n  -m \"$STORY_URL\" \\\n  -i \"instagram-id\"\n```\n\n**See [PROVIDER_SETTINGS.md](./PROVIDER_SETTINGS.md) for all 28+ platforms.**\n\n---\n\n## Features for AI Agents\n\n### Discovery Workflow\nThe CLI enables dynamic discovery of integration capabilities:\n\n1. **List integrations** - Get available social media accounts\n2. **Get settings** - Retrieve character limits, required fields, and available tools\n3. **Trigger tools** - Fetch dynamic data (flairs, playlists, boards, etc.)\n4. **Create posts** - Use discovered data in posts\n5. **Analyze** - Get post analytics; if `{\"missing\": true}` is returned, resolve with `posts:missing` + `posts:connect`\n\nThis allows AI agents to adapt to different platforms without hardcoded knowledge.\n\n### JSON Mode\nFor complex posts with multiple platforms and settings:\n\n```bash\nbsocial posts:create --json complex-post.json\n```\n\nJSON structure:\n```json\n{\n  \"integrations\": [\"twitter-123\", \"linkedin-456\"],\n  \"posts\": [\n    {\n      \"provider\": \"twitter\",\n      \"post\": [\n        {\n          \"content\": \"Tweet version\",\n          \"image\": [\"twitter-image.jpg\"]\n        }\n      ]\n    },\n    {\n      \"provider\": \"linkedin\",\n      \"post\": [\n        {\n          \"content\": \"LinkedIn version with more context...\",\n          \"image\": [\"linkedin-image.jpg\"]\n        }\n      ],\n      \"settings\": {\n        \"__type\": \"linkedin\",\n        \"companyId\": \"company-123\"\n      }\n    }\n  ]\n}\n```\n\n### All Output is JSON\nEvery command outputs JSON for easy parsing:\n\n```bash\nINTEGRATIONS=$(bsocial integrations:list | jq -r '.')\nREDDIT_ID=$(echo \"$INTEGRATIONS\" | jq -r '.[] | select(.identifier==\"reddit\") | .id')\n```\n\n### Threading Support\nComments are automatically converted to threads/replies based on platform:\n- **Twitter/X**: Thread of tweets\n- **Reddit**: Comment replies\n- **LinkedIn**: Comment on post\n- **Instagram**: First comment\n\n```bash\nbsocial posts:create \\\n  -c \"Main post\" \\\n  -c \"Comment 1\" \\\n  -c \"Comment 2\" \\\n  -i \"integration-id\"\n```\n\n---\n\n## Common Workflows\n\n### Reddit Post with Flair\n```bash\n#!/bin/bash\nREDDIT_ID=$(bsocial integrations:list | jq -r '.[] | select(.identifier==\"reddit\") | .id')\nFLAIRS=$(bsocial integrations:trigger \"$REDDIT_ID\" getFlairs -d '{\"subreddit\":\"programming\"}')\nFLAIR_ID=$(echo \"$FLAIRS\" | jq -r '.output[0].id')\n\nbsocial posts:create \\\n  -c \"My post content\" \\\n  -s \"2024-12-31T12:00:00Z\" \\\n  --settings \"{\\\"subreddit\\\":[{\\\"value\\\":{\\\"subreddit\\\":\\\"programming\\\",\\\"title\\\":\\\"Post Title\\\",\\\"type\\\":\\\"text\\\",\\\"is_flair_required\\\":true,\\\"flair\\\":{\\\"id\\\":\\\"$FLAIR_ID\\\",\\\"name\\\":\\\"Discussion\\\"}}}]}\" \\\n  -i \"$REDDIT_ID\"\n```\n\n### YouTube Video Upload\n```bash\n#!/bin/bash\nVIDEO=$(bsocial upload video.mp4)\nVIDEO_PATH=$(echo \"$VIDEO\" | jq -r '.path')\n\nbsocial posts:create \\\n  -c \"Video description...\" \\\n  -s \"2024-12-31T12:00:00Z\" \\\n  --settings '{\"title\":\"My Video\",\"type\":\"public\",\"tags\":[{\"value\":\"tech\",\"label\":\"Tech\"}]}' \\\n  -m \"$VIDEO_PATH\" \\\n  -i \"youtube-id\"\n```\n\n### Multi-Platform Campaign\n```bash\n#!/bin/bash\nbsocial posts:create \\\n  -c \"Same content everywhere\" \\\n  -s \"2024-12-31T12:00:00Z\" \\\n  -m \"image.jpg\" \\\n  -i \"twitter-id,linkedin-id,facebook-id\"\n```\n\n### Batch Scheduling\n```bash\n#!/bin/bash\nDATES=(\"2024-02-14T09:00:00Z\" \"2024-02-15T09:00:00Z\" \"2024-02-16T09:00:00Z\")\nCONTENT=(\"Monday motivation 💪\" \"Tuesday tips 💡\" \"Wednesday wisdom 🧠\")\n\nfor i in \"${!DATES[@]}\"; do\n  bsocial posts:create \\\n    -c \"${CONTENT[$i]}\" \\\n    -s \"${DATES[$i]}\" \\\n    -i \"twitter-id\"\ndone\n```\n\n---\n\n## Documentation\n\n**For AI Agents:**\n- **[SKILL.md](./SKILL.md)** - Complete skill reference with patterns and examples\n\n**Deep-Dive Guides:**\n- **[HOW_TO_RUN.md](./HOW_TO_RUN.md)** - Installation and setup methods\n- **[COMMAND_LINE_GUIDE.md](./COMMAND_LINE_GUIDE.md)** - Complete command syntax reference\n- **[PROVIDER_SETTINGS.md](./PROVIDER_SETTINGS.md)** - All platform settings schemas\n- **[INTEGRATION_TOOLS_WORKFLOW.md](./INTEGRATION_TOOLS_WORKFLOW.md)** - Tools workflow guide\n- **[INTEGRATION_SETTINGS_DISCOVERY.md](./INTEGRATION_SETTINGS_DISCOVERY.md)** - Settings discovery\n- **[SUPPORTED_FILE_TYPES.md](./SUPPORTED_FILE_TYPES.md)** - Media format reference\n- **[PROJECT_STRUCTURE.md](./PROJECT_STRUCTURE.md)** - Code architecture\n- **[PUBLISHING.md](./PUBLISHING.md)** - npm publishing guide\n\n**Examples:**\n- **[examples/EXAMPLES.md](./examples/EXAMPLES.md)** - Comprehensive examples\n- **[examples/](./examples/)** - Ready-to-use scripts and JSON files\n\n---\n\n## API Endpoints\n\nThe CLI interacts with these Butterfly Social API endpoints:\n\n| Endpoint | Method | Purpose |\n|----------|--------|---------|\n| `/public/v1/posts` | POST | Create a post |\n| `/public/v1/posts` | GET | List posts |\n| `/public/v1/posts/:id` | DELETE | Delete a post |\n| `/public/v1/posts/:id/settings` | PUT | Update a post's provider settings (merged; unpublished only) |\n| `/public/v1/posts/:id/missing` | GET | Get missing content from provider |\n| `/public/v1/posts/:id/release-id` | PUT | Update release ID for a post |\n| `/public/v1/integrations` | GET | List integrations (optional `?group=` filter) |\n| `/public/v1/groups` | GET | List groups (customers) |\n| `/public/v1/integration-settings/:id` | GET | Get integration settings |\n| `/public/v1/integration-trigger/:id` | POST | Trigger integration tool |\n| `/public/v1/analytics/:integration` | GET | Get platform analytics |\n| `/public/v1/analytics/post/:postId` | GET | Get post analytics |\n| `/public/v1/upload` | POST | Upload media |\n\n---\n\n## Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `BUTTERFLY_API_KEY` | No* | - | Your Butterfly Social API key |\n| `BUTTERFLY_API_URL` | No | `https://butterfly-social-production.up.railway.app/api` | Custom API endpoint |\n| `BUTTERFLY_AUTH_SERVER` | No | `https://your-auth-server (self-hosted; no hosted default)` | Custom auth server URL |\n\n*Either OAuth2 (via `bsocial auth:login`) or `BUTTERFLY_API_KEY` is required.\n\n---\n\n## Error Handling\n\nThe CLI provides clear error messages with exit codes:\n\n- **Exit code 0**: Success\n- **Exit code 1**: Error occurred\n\n**Common errors:**\n\n| Error | Solution |\n|-------|----------|\n| `Not authenticated` | Run `bsocial auth:login` or set `BUTTERFLY_API_KEY` |\n| `Integration not found` | Run `integrations:list` to get valid IDs |\n| `startDate/endDate required` | Use ISO 8601 format: `\"2024-12-31T12:00:00Z\"` |\n| `Invalid settings` | Check `integrations:settings` for required fields |\n| `Tool not found` | Check available tools in `integrations:settings` output |\n| `Upload failed` | Verify file exists and format is supported |\n| `analytics:post` returns `{\"missing\": true}` | Run `posts:missing <id>` then `posts:connect <id> --release-id \"<rid>\"` |\n\n---\n\n## Development\n\n### Project Structure\n\n```\nsrc/\n├── index.ts              # CLI entry point with yargs\n├── api.ts                # PostizAPI client class\n├── config.ts             # Configuration (OAuth2 + API key)\n└── commands/\n    ├── auth.ts           # OAuth2 authentication (login/logout/status)\n    ├── posts.ts          # Post management commands\n    ├── integrations.ts   # Integration commands\n    ├── analytics.ts      # Analytics commands\n    └── upload.ts         # Media upload command\nexamples/                 # Example scripts and JSON files\npackage.json\ntsconfig.json\ntsup.config.ts            # Build configuration\nREADME.md                 # This file\nSKILL.md                  # AI agent reference\n```\n\n### Scripts\n\n```bash\npnpm run dev       # Watch mode for development\npnpm run build     # Build the CLI\npnpm run start     # Run the built CLI\n```\n\n### Building\n\nThe CLI uses `tsup` for bundling:\n\n```bash\npnpm run build\n```\n\nOutput in `dist/`:\n- `index.js` - Bundled executable with shebang\n- `index.js.map` - Source map\n\n---\n\n## Quick Reference\n\n```bash\n# Authentication\nbsocial auth:login                                              # OAuth2 device flow\nbsocial auth:status                                             # Check auth\nbsocial auth:logout                                             # Remove credentials\nexport BUTTERFLY_API_KEY=your_key                                 # Or use API key\n\n# Discovery\nbsocial integrations:list                           # List integrations\nbsocial integrations:list --group \"<group-id>\"      # List integrations in a group\nbsocial integrations:groups                         # List groups (customers)\nbsocial integrations:settings <id>                  # Get settings\nbsocial integrations:trigger <id> <method> -d '{}'  # Fetch data\n\n# Posting (date is required)\nbsocial posts:create -c \"text\" -s \"2024-12-31T12:00:00Z\" -i \"id\"                    # Simple\nbsocial posts:create -c \"text\" -s \"2024-12-31T12:00:00Z\" -t draft -i \"id\"          # Draft\nbsocial posts:create -c \"text\" -m \"img.jpg\" -s \"2024-12-31T12:00:00Z\" -i \"id\"      # With media\nbsocial posts:create -c \"main\" -c \"comment\" -s \"2024-12-31T12:00:00Z\" -i \"id\"      # With comment\nbsocial posts:create -c \"text\" -s \"2024-12-31T12:00:00Z\" --settings '{}' -i \"id\"   # Platform-specific\nbsocial posts:create --json file.json                                               # Complex\n\n# Management\nbsocial posts:list                                  # List posts\nbsocial posts:delete <id>                          # Delete post\nbsocial posts:status <id> --status draft           # Move to draft (stops workflow)\nbsocial posts:status <id> --status schedule        # Queue draft for publishing\nbsocial posts:settings <id> --settings '{}'        # Patch a post's settings (merged; DRAFT/QUEUE only)\nbsocial upload <file>                              # Upload media\n\n# Analytics\nbsocial analytics:platform <id>                    # Platform analytics (7 days)\nbsocial analytics:platform <id> -d 30             # Platform analytics (30 days)\nbsocial analytics:post <id>                        # Post analytics (7 days)\nbsocial analytics:post <id> -d 30                 # Post analytics (30 days)\n# If analytics:post returns {\"missing\": true}, resolve it:\nbsocial posts:missing <id>                         # List provider content\nbsocial posts:connect <id> --release-id \"<rid>\"    # Connect content to post\n\n# Help\nbsocial --help                                     # Show help\nbsocial posts:create --help                        # Command help\n```\n\n---\n\n## Contributing\n\nThis CLI is part of the [Butterfly Social monorepo](https://github.com/butterflysocial/agent-skill).\n\nTo contribute:\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes in `apps/cli/`\n4. Run tests: `pnpm run build`\n5. Submit a pull request\n\n---\n\n## License\n\nAGPL-3.0\n\n---\n\n## Links\n\n- **Website:** [postiz.com](https://github.com/butterflysocial/agent-skill)\n- **API Docs:** Butterfly Social → Settings → Developers → Public API\n- **GitHub:** [gitroomhq/postiz-app](https://github.com/butterflysocial/agent-skill)\n- **Issues:** [Report bugs](https://github.com/butterflysocial/agent-skill/issues)\n\n---\n\n## Supported Platforms\n\n28+ platforms including:\n\n| Platform | Integration Tools | Settings |\n|----------|------------------|----------|\n| Twitter/X | getLists, getCommunities | who_can_reply_post |\n| LinkedIn | getCompanies | companyId, carousel |\n| Reddit | getFlairs, searchSubreddits | subreddit, title, flair |\n| YouTube | getPlaylists, getCategories | title, type, tags, playlistId |\n| TikTok | - | content_posting_method, privacy_level, comment, brand toggles, duet/stitch/video_made_with_ai (video only), autoAddMusic (photo only) |\n| Instagram | - | post_type (post/story) |\n| Facebook | getPages | - |\n| Pinterest | getBoards, getBoardSections | - |\n| Discord | getChannels | - |\n| Slack | getChannels | - |\n| And 18+ more... | | |\n\n**See [PROVIDER_SETTINGS.md](./PROVIDER_SETTINGS.md) for complete documentation.**\n","readmeFilename":"README.md"}