Social media command-line interface — JSON-first publishing for agents, CI and cron
bundlesocial-cli is a scriptable, agent-friendly command-line interface over the bundle.social API. JSON to stdout, status text to stderr, one command per workflow. Ships with a SKILL.md so agent runtimes auto-discover it.
Last updated: May 2026
1$ npx bundlesocial-cli posts:create \2 -c "We just shipped dark mode 🌙" \3 -i x -i bluesky -i mastodon45{6 "id": "post_3sf9k2",7 "status": "SCHEDULED",8 "socialAccountTypes": ["TWITTER", "BLUESKY", "MASTODON"],9 "data": {10 "TWITTER": { "text": "We just shipped dark mode 🌙" },11 "BLUESKY": { "text": "We just shipped dark mode 🌙" },12 "MASTODON": { "text": "We just shipped dark mode 🌙" }13 }14}1516# JSON on stdout, status text on stderr — easy for an agent to parse.17# Ships with a SKILL.md for agent-skill runtimes:18# $ npx skills add bundleglobal/bundlesocial-cliGlueing curl + jq to every social platform
What bundle.social handles
A CLI that's actually agent-friendly
Designed for shell-out agents, CI runners and cron — JSON by default, per-command exit codes, structured errors, no interactive prompts. The same CLI a human can use to ship a one-off post.
Workflow
How it works
Connect accounts once, then create and schedule posts with channel-specific fields from one API.
Install with npx
npx bundlesocial-cli@latest — or pin a version in package.json / a CI image.
Authenticate with an API key
Set BUNDLESOCIAL_API_KEY or pass --api-key. Org-scoped — no per-platform OAuth on the agent side.
Run commands or wire into CI
posts:create / posts:schedule / analytics:get — JSON in, JSON out. Drop into GitHub Actions, cron, or an agent's shell-out path.
Capabilities
CLI surface designed for automation
Every command returns structured JSON, supports --help, and behaves predictably in non-interactive shells.
posts:create / posts:schedule
Multi-platform posts in one invocation. -i x -i bluesky -i mastodon to fan out; --platform-settings to pass per-platform options.
media:upload
Upload a local file or URL, get an upload ID back. Reference the ID from posts:create — no base64, no chunking ceremony.
accounts:list / teams:list
Discover what an agent can post to before it tries. Filter by platform, team or account status.
analytics:get
Pull per-post and per-account analytics as JSON. Pipe into jq, into a dashboard, into an LLM as context.
Developer example
Schedule a multi-platform post from the shell
Examples use bundle.social's public API shape: API key authentication, a post date, selected social account types, and platform-specific data.
1$ npx bundlesocial-cli posts:create \2 -c "We just shipped dark mode 🌙" \3 -i x -i bluesky -i mastodon45{6 "id": "post_3sf9k2",7 "status": "SCHEDULED",8 "socialAccountTypes": ["TWITTER", "BLUESKY", "MASTODON"],9 "data": {10 "TWITTER": { "text": "We just shipped dark mode 🌙" },11 "BLUESKY": { "text": "We just shipped dark mode 🌙" },12 "MASTODON": { "text": "We just shipped dark mode 🌙" }13 }14}1516# JSON on stdout, status text on stderr — easy for an agent to parse.17# Ships with a SKILL.md for agent-skill runtimes:18# $ npx skills add bundleglobal/bundlesocial-cliSupported content
Honest limitations
- Node 20+ required. (Use npx if you don't want a global install.)
- Interactive prompts are off by default — meant for non-interactive shells. Enable with --interactive if you want them.
- Same per-platform rules apply (TikTok privacy enum, YouTube category, X media constraints) — the CLI surfaces validation errors structured, not bypassed.
Guarantees
Developer-first infrastructure
2% error rate
We handle the platform edge cases, media processing, and rate limits so your requests succeed.
Verbose errors
When native APIs fail, we return human-readable error messages and actionable recovery steps.
Flat pricing
No per-post counting. Predictable pricing for teams managing many users, workspaces, and connected accounts.
Same-day support
Direct access to the engineers building the API. We respond to technical issues the same day. Sometimes the same hour. Test us c;
Resources
Technical guides & documentation
FAQ
Questions developers ask before building
Is this a wrapper over the SDK?
Yes. The CLI uses the bundlesocial TypeScript SDK underneath. Anything you can do from the CLI you can do from the SDK and the REST API directly.
How does the SKILL.md work?
Agent-skill runtimes look for SKILL.md inside published packages to auto-document tools they can shell out to. We ship one in bundlesocial-cli — npx skills add bundleglobal/bundlesocial-cli registers it with your skill runtime.
Does it work in CI?
Yes. It's the primary target. JSON-by-default output, non-interactive shells, exit codes per command, no global config needed — just BUNDLESOCIAL_API_KEY as a secret.
How is this different from the MCP server?
Use the CLI when an agent shells out (Claude Code subprocess, OpenCode, CI runners, cron). Use the MCP server when the client speaks the Model Context Protocol (Claude Desktop, Cursor). Same auth, same posts, different transport.