Postiz Agent CLI
Lets AI agents like Claude Code create, schedule, and manage social posts across 28+ platforms from the command line, with analytics included.
- Source repo
- gitroomhq/postiz-agent
- Stars
- ★ 544
- Last updated
- 3d ago
- License
- NOASSERTION
- Primary language
- TypeScript
- FA score
- 54/100 · Major gaps
At a glance
- How it runs
- Works with
- Portable with changesClaude Code
- Cost
- Free tier plus a paid hosted plan
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A developer using Claude Code who wants their agent to schedule posts to Twitter/X, LinkedIn, and other platforms from a conversation
- Not a fit if
- Teams that need fully offline operation; posting and uploads go through Postiz cloud
- Pure chat environments without shell access, since the CLI must be installed locally
- Teams unwilling to create a Postiz account or use its hosted service
- Source review
- 54/100 · Major gaps
What does this agent do, and when should you use it?
Postiz Agent (gitroomhq/postiz-agent) is the agent-facing entry point to the Postiz social media scheduling platform, combining a postiz CLI with distributable skill/plugin packages. It installs as a Claude Code plugin, a Cursor plugin, or a Grok Build plugin (which additionally bundles the hosted Postiz MCP server), and can also be added as a generic skill via npx skills add. The CLI talks to the Postiz public API for authentication (OAuth2 device flow or API key), integration discovery, post creation and scheduling, media uploads, and platform/post analytics. Every command outputs JSON so AI agents can parse and chain results programmatically. It supports 28+ platforms including Twitter/X, LinkedIn, Reddit, YouTube, TikTok, Instagram, and Facebook, with threading, comments, and per-platform settings. Media must be uploaded via postiz upload first, since platforms like TikTok, Instagram, and YouTube only accept URLs from trusted domains.
Once installed, an agent drives the full workflow through the postiz CLI: postiz auth:login (OAuth2 device flow) or setting POSTIZ_API_KEY for authentication; postiz integrations:list to fetch connected accounts and their IDs; postiz integrations:settings to read character limits and required fields; postiz integrations:trigger to pull dynamic data such as Reddit flairs, YouTube playlists, or LinkedIn companies. Posting uses postiz posts:create with -c content, -s ISO 8601 schedule date, -i integration IDs, -m media URLs, and --settings platform-specific JSON — supporting drafts, multi-platform distribution, and automatic thread conversion from multiple content segments. Media goes through postiz upload first to obtain a trusted URL. Published posts can be managed with posts:list, posts:status, posts:settings, and analyzed with analytics:platform and analytics:post; if analytics returns {"missing": true}, posts:missing and posts:connect link the post to its provider content. All output is JSON.
- A developer using Claude Code who wants their agent to schedule posts to Twitter/X, LinkedIn, and other platforms from a conversation
- Agencies managing multi-client social accounts, filtering channels per customer via
integrations:groupsand batch scheduling - Creators publishing image/video content to TikTok, Instagram, or YouTube on a schedule, uploading media first via
postiz upload - Marketers scripting loops around
posts:createto batch-schedule a week of content from a bash script - Data-driven teams pulling follower, impression, and engagement metrics via
analytics:platform/analytics:postinto their own reporting
How do you install or deploy this agent?
As a skill: npx skills add gitroomhq/postiz-agent. As a Claude Code plugin: /plugin marketplace add gitroomhq/postiz-agent then /plugin install postiz@postiz-agent. As a Cursor plugin: find postiz in the Customize panel and install. Also install and authenticate the CLI: npm install -g postiz, then run postiz auth:login (OAuth2 device flow; credentials saved to ~/.postiz/credentials.json) or export POSTIZ_API_KEY=your_api_key_here. Optionally set POSTIZ_API_URL=https://your-custom-api.com for a self-hosted API.
How do you use this agent?
Start with postiz integrations:list to get integration IDs. Basic scheduling: postiz posts:create -c "Content" -s "2024-12-31T12:00:00Z" -i "integration-id". With media (upload first): postiz upload img.jpg, then pass the returned URL via -m "$PATH". Multi-platform: -i "twitter-id,linkedin-id,facebook-id". Threads: pass -c multiple times. Per-platform settings use --settings '{...}' or -- post.json. Manage with posts:list, posts:status, posts:settings, posts:delete; measure with analytics:platform <id> and analytics:post <id>. All commands output JSON, parseable with jq.
What are this agent's strengths and limitations?
- All commands output JSON with a discovery workflow (integrations:list → settings → trigger), letting agents adapt to platforms without hardcoded knowledge
- Native support for 28+ platforms including Reddit flairs, YouTube playlists, LinkedIn company pages, and X threads
- Multiple integration paths: Claude Code plugin, Cursor plugin, Grok Build plugin with hosted MCP server, and generic skill install
- OAuth2 device-flow authentication requires no client secrets, with API key and self-hosted API/auth server options also supported
- Depends on Postiz hosted services (api.postiz.com / cli-auth.postiz.com / mcp.postiz.com); self-hosting requires extra work per server/SERVER.md
- Media must be uploaded via
postiz uploadto get a trusted URL — external links are rejected by TikTok, Instagram, and YouTube, adding a step - Post settings cannot be changed after publishing (only DRAFT/QUEUE posts accept patches), and some platforms don't return a post ID, requiring manual posts:missing/posts:connect before analytics work
- The GitHub license field is NOASSERTION while the README states AGPL-3.0 — verify licensing before commercial integration
- Requires a Node.js runtime and a globally installed CLI; the agent must be able to execute shell commands, so pure chat environments won't work
How does this agent compare with similar options?
The README positions it as a skill/plugin callable by agents such as Claude and OpenClaw, and packages a hosted MCP server (https://mcp.postiz.com/mcp-oauth-dynamic); direct comparisons with other AI social media tools are not listed in the source.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Postiz Agent CLI This agent | 54 · Major gaps | CLIFreemium | ★ 544 | 3d ago | TypeScript | Claude Code |
| Zapier MCP Plugin | 41 · Major gaps | Agent plugin / skill | ★ 449 | 2d ago | — | Codex · Claude Code |
| SwarmVault | 67 · Some gaps | CLIFree + model costs | ★ 730 | 3mo ago | TypeScript | Codex · Claude Code |
| OpenContext | 58 · Major gaps | CLIFree + model costs | ★ 1.3k | 4mo ago | JavaScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Credential scope is limited to the Postiz API with a reasonably narrow surface (least_privilege=2); but posts:create can schedule public posts by default with no built-in confirmation gate (user_confirmation=1); API endpoint table, env vars, and credential locations are disclosed, giving good data-flow transparency (data_flow_transparency=2); OAuth credentials are stored in plaintext at ~/.postiz/credentials. with no encryption or hardening noted (sensitive_data_handling=1); few dependencies but no lockfile or audit evidence (dependency_security=1); the CLI produces public, persistent effects on external social platforms and schedules publishing by default (external_effects=1); rollback paths exist via posts:status (draft terminates workflows) and posts:delete (rollback=2); author and upstream monorepo links are clear (source_attribution=2).
README, command tables, endpoint table, and quick reference are mutually consistent (self_consistency=2); functionality depends on hosted services (api.postiz.com, cli-auth.postiz.com, mcp.postiz.com); self-hosting exists but requires an extra server (dependency_availability=1); error table and exit-code conventions are clear (failure_messages=2).
Explicitly targets developers and AI agents with adequate scenario coverage (audience_and_scenarios=2); boundaries such as character limits, provider quirks, and the missing-post flow are documented (capability_boundaries=2); SKILL.md is referenced but its content is not among the provided files, so trigger precision cannot be verified (trigger_precision=1); Node>=18, npm/pnpm install, multi-host plugin manifests give good environment fit (environment_fit=2).
Documentation is well layered (README/SKILL/topic guides/examples) (information_architecture=2); install paths are complete (install_notes=2); CLI name postiz matches package name and bin (naming_stability=2); rich examples plus workflow scripts (examples_and_faq=2); scattered platform constraints but no consolidated known-limitations section (known_limitations=1); LICENSE is AGPL-3.0 and matches package. despite registry metadata NOASSERTION (license=2); version 2.0.17 exists, CHANGELOG.md is listed in publish files but its content is not provided (versioning_changelog=1); maintenance points to upstream postiz-app issues but this repo's own maintenance commitment is unclear (maintenance_responsibility=1).
All-JSON command output suits piping and agent consumption (output_usability=2); the discovery workflow (settings/trigger/discovery) adds real value over raw API calls (marginal_value=2); draft mode and batch scripts give cost-controlled paths (cost_benefit=2).
Core claims such as '28+ platforms' cannot be itemized against the provided files (claim_traceability=1); no third-party corroboration beyond self-description (cross_source_corroboration=1); documentation largely separates facts from guidance, but some claims mix marketing framing with technical rationale (fact_inference_separation=1).
- Static review only; no commands were executed. All conclusions rest solely on the provided files.
- posts:create schedules public posts by default; agent mistakes have immediate public effects. Prefer -t draft plus human review before scheduling.
- OAuth credentials are stored as plaintext JSON at ~/.postiz/credentials.; watch file permissions and host security.
- Functionality depends heavily on hosted Postiz services (API, OAuth server, MCP); outages or changes directly affect availability.
- SKILL.md referenced by the README was not among the reviewed files, so agent-side behavioral rules could not be verified.
- Registry license metadata is NOASSERTION, inconsistent with the in-repo AGPL-3.0; verify independently before use.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Added - upload --adjust - Adjust the uploaded file to the platforms' limits (videos scaled to 1080p and re-encoded to H.264 MP4 with AAC audio, oversized images scaled down). Off by default. Wait until media:status returns ready before publishing a post with the returned path, or the post uses the original file. - media:status <id> - Check a file uploaded with --adjust via GET /public/v1/media/:id/status: processing until the adjusted file is in place, ready after, and ready with a warning when the adjustment failed and the original is kept.View on GitHub ↗ -
Release notes excerpt
Changed - README.md: document media:list (media section, API endpoint table and quick reference) and add CONTRIBUTING.md with the pull request checklist (version bump, changelog entry, docs and release steps), linked from the README.View on GitHub ↗ -
Release notes excerpt
Fixed - npm publish workflow: pnpm publish ran the publish script in package.json as a lifecycle hook right after publishing, which started a second publish that failed with E409. The script is renamed to publish-cli (docs updated) so the workflow publishes once. Changed - PUBLISHING.md: the release steps now include the gh release create command.View on GitHub ↗
FAQ
Do I have to use Postiz's hosted services?
How does authentication work — OAuth2 vs API key?
postiz auth:login runs an OAuth2 device flow with no client secret needed; credentials are stored in ~/.postiz/credentials.. Alternatively export POSTIZ_API_KEY=.... When both exist, OAuth2 credentials take priority.What are the constraints for posting media?
postiz upload (PNG/JPG/JPEG/GIF and MP4 supported) and use the returned Postiz URL in -m; TikTok, Instagram, and YouTube only accept trusted-domain URLs and reject external links.Can I edit a post after publishing?
posts:settings; published posts are rejected. posts:status toggles between draft and schedule — switching to draft terminates any running publishing workflow.What if analytics returns {"missing": true}?
postiz posts:missing <post-id> to list provider content, then postiz posts:connect <post-id> --release-id "<content-id>" to link it; analytics will then work.