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.
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.
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
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 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.) 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.. 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.
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.
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.