Schedule posts with agents to:
ChatGPT ·
Claude ·
Claude Cowork ·
Claude Code ·
Codex ·
Cursor ·
OpenClaw ·
Hermes Agent ·
Grok Bot ·
Grok Build ·
Muse ·
Perplexity Computer ·
nanoclaw ·
Paperclip ·
MCP Server ·
AI Agents CLI
Install as a skill
npx skills add gitroomhq/postiz-agent
Claude Code plugin
/plugin marketplace add gitroomhq/postiz-agent
/plugin install postiz@postiz-agent
Grok Build plugin
Postiz is listed in the xAI plugin marketplace — install it from the marketplace inside Grok Build. This repo also carries its own .grok-plugin/plugin.json manifest and .grok-plugin/marketplace.json catalog, so it can be added as a marketplace source directly.
The Grok plugin also bundles the hosted Postiz MCP server (https://mcp.postiz.com/mcp-oauth-dynamic) via the mcpServers field in .grok-plugin/plugin.json — you'll be asked to sign in to Postiz on first connection; no token or local install needed. The Claude Code and Cursor plugins are skill/CLI-only and do not register an MCP server.
Cursor plugin
This repo ships a Cursor plugin manifest at .cursor-plugin/plugin.json.
From the marketplace / Customize panel: open Customize in the Cursor sidebar, find postiz, and select Install (project or user scope).
Local install (development):
git clone https://github.com/gitroomhq/postiz-agent.git
ln -s "$(pwd)/postiz-agent" ~/.cursor/plugins/local/postiz
then restart Cursor or run Developer: Reload Window.
The plugin exposes the postiz skill, which drives the postiz CLI (the CLI handles media uploads, which is required for image/video posts). Make sure the CLI is installed (npm install -g postiz) and authenticated (postiz auth:login or export POSTIZ_API_KEY=...) before asking the agent to post.
Gemini CLI extension
This repo is a Gemini CLI extension (gemini-extension.json at the root) and is indexed in the extensions gallery.
gemini extensions install https://github.com/gitroomhq/postiz-agent
It installs the postiz skill and the hosted Postiz MCP server (https://mcp.postiz.com/mcp-oauth-dynamic). Gemini CLI opens a browser to sign in to Postiz on first use; run /mcp auth postiz to re-authenticate. The skill drives the postiz CLI for media uploads, so install it with npm install -g postiz for image or video posts.
Qwen Code
Qwen Code installs Claude Code marketplaces directly, so no separate manifest is needed:
qwen extensions install gitroomhq/postiz-agent:postiz
DeepSeek Harness plugin
This repo ships a DeepSeek Harness (dsh) bundle at plugins/dsh-postiz. It connects the agent to the hosted Postiz MCP server and registers a postiz workflow skill.
dsh plugin --profile web add "github:gitroomhq/postiz-agent#path:/plugins/dsh-postiz"
export POSTIZ_API_KEY=your-api-key # Postiz → Settings → Developers → Public API
dsh web
The Postiz tools then appear as mcp__postiz__* (integrationList, integrationSchema, schedulePostTool, ...). Self-hosted instances override baseUrl on the postiz row. See the plugin README for configuration.
Postiz CLI
Social media automation CLI for AI agents - Schedule posts across 28+ platforms programmatically.
The Postiz CLI provides a command-line interface to the Postiz 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.
Installation
From npm (Recommended)
npm install -g postiz
# or
pnpm install -g postiz
Authentication
Option 1: OAuth2 (Recommended)
Authenticate using the device flow — no client ID or secret needed:
postiz auth:login
This will:
- Display a one-time code in your terminal
- Open your browser to authorize
- Automatically save credentials to
~/.postiz/credentials.json
# Check current auth status (verifies credentials are still valid)
postiz auth:status
# Remove stored credentials
postiz auth:logout
Self-Hosting the Auth Server
By default, postiz auth:login uses the hosted auth server at cli-auth.postiz.com. If you want to self-host the OAuth2 device flow server, follow the guide in server/SERVER.md.
Option 2: API Key
export POSTIZ_API_KEY=your_api_key_here
Optional: Custom API endpoint
export POSTIZ_API_URL=https://your-custom-api.com
Note: OAuth2 credentials take priority over the API key when both are present.
Commands
Discovery & Settings
List all connected integrations
postiz integrations:list
postiz integrations:list --group "customer-id"
Returns integration IDs, provider names, and metadata. Use --group to return only the channels assigned to a specific group (customer).
List all groups (customers)
postiz integrations:groups
Returns all groups (customers) for your organization as {id, name}. Use a group's id with integrations:list --group to filter channels.
Get integration settings schema
postiz integrations:settings <integration-id>
Returns character limits, required settings, and available tools for fetching dynamic data.
Trigger integration tools
postiz integrations:trigger <integration-id> <method-name>
postiz integrations:trigger <integration-id> <method-name> -d '{"key":"value"}'
Fetch dynamic data like Reddit flairs, YouTube playlists, LinkedIn companies, etc.
Examples:
# Get Reddit flairs
postiz integrations:trigger reddit-123 getFlairs -d '{"subreddit":"programming"}'
# Get YouTube playlists
postiz integrations:trigger youtube-456 getPlaylists
# Get LinkedIn companies
postiz integrations:trigger linkedin-789 getCompanies
Creating Posts
Simple scheduled post
postiz posts:create -c "Content" -s "2024-12-31T12:00:00Z" -i "integration-id"
Draft post
postiz posts:create -c "Content" -s "2024-12-31T12:00:00Z" -t draft -i "integration-id"
Post with media
postiz posts:create -c "Content" -m "img1.jpg,img2.jpg" -s "2024-12-31T12:00:00Z" -i "integration-id"
Post with comments (each comment can have its own media)
postiz posts:create \
-c "Main post" -m "main.jpg" \
-c "First comment" -m "comment1.jpg" \
-c "Second comment" -m "comment2.jpg,comment3.jpg" \
-s "2024-12-31T12:00:00Z" \
-i "integration-id"
Multi-platform post
postiz posts:create -c "Content" -s "2024-12-31T12:00:00Z" -i "twitter-id,linkedin-id,facebook-id"
Platform-specific settings
postiz posts:create \
-c "Content" \
-s "2024-12-31T12:00:00Z" \
--settings '{"subreddit":[{"value":{"subreddit":"programming","title":"Post Title","type":"text"}}]}' \
-i "reddit-id"
Complex post from JSON file
postiz posts:create --json post.json
Options:
-c, --content - Post/comment content (use multiple times for posts with comments)-s, --date - Schedule date in ISO 8601 format (REQUIRED)-t, --type - Post type: "schedule" or "draft" (default: "schedule")-m, --media - Comma-separated media URLs for corresponding -c-i, --integrations - Comma-separated integration IDs (required)-d, --delay - Delay between comments in minutes (default: 0)--settings - Platform-specific settings as JSON string-j, --json - Path to JSON file with full post structure--shortLink - Use short links (default: true)
Managing Posts
List posts
postiz posts:list
postiz posts:list --startDate "2024-01-01T00:00:00Z" --endDate "2024-12-31T23:59:59Z"
postiz posts:list --customer "customer-id"
Defaults 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).
Delete post
postiz posts:delete <post-id>
Change post status (draft ↔ schedule)
postiz posts:status <post-id> --status draft
postiz posts:status <post-id> --status schedule
Move 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.
Update a post's provider-specific settings
postiz posts:settings <post-id> --settings '{"content_posting_method":"DIRECT_POST"}'
postiz posts:settings <post-id> --settings '{"subreddit":[{"value":{"subreddit":"/r/selfhosted","title":"My title","type":"self","is_flair_required":true}}]}'
Patches 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.
Analytics
Get platform analytics
postiz analytics:platform <integration-id>
postiz analytics:platform <integration-id> -d 30
Returns 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).
Get post analytics
postiz analytics:post <post-id>
postiz analytics:post <post-id> -d 30
Returns metrics like likes, comments, shares, and impressions for a specific published post.
⚠️ 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:
# 1. List available content from the provider
postiz posts:missing <post-id>
# 2. Connect the correct content to the post
postiz posts:connect <post-id> --release-id "7321456789012345678"
# 3. Analytics will now work
postiz analytics:post <post-id>
Connecting Missing Posts
Some 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.
List available content from the provider
postiz posts:missing <post-id>
Returns an array of {id, url} items representing recent content from the provider. Returns an empty array if the provider doesn't support this feature.
Connect a post to its published content
postiz posts:connect <post-id> --release-id "<content-id>"
Upload file and get URL
postiz upload <file-path>
⚠️ IMPORTANT: Upload Files Before Posting
You must upload media files to Postiz before using them in posts. Many platforms (especially TikTok, Instagram, and YouTube) require verified/trusted URLs and will reject external links.
Workflow:
- Upload your file using
postiz upload
- Extract the returned URL
- Use that URL in your post's
-m parameter
Supported formats:
- Images: PNG, JPG, JPEG, GIF
- Videos: MP4
Example:
# 1. Upload the file first
RESULT=$(postiz upload video.mp4)
PATH=$(echo "$RESULT" | jq -r '.path')
# 2. Use the Postiz URL in your post
postiz posts:create -c "Check out my video!" -s "2024-12-31T12:00:00Z" -m "$PATH" -i "tiktok-id"
Why this is required:
- TikTok, Instagram, YouTube only accept URLs from trusted domains
- Security: Platforms verify media sources to prevent abuse
- Reliability: Postiz ensures your media is always accessible
Clipping
Turn a long YouTube video into short vertical clips with burned-in captions. The best parts are picked automatically and every clip is saved to your media library. Pass integrations to also get a draft post per clip on every channel (nothing is scheduled or published).
Start a clipping
postiz clipping:create "https://www.youtube.com/watch?v=VIDEO_ID"
postiz clipping:create "https://www.youtube.com/watch?v=VIDEO_ID" -n 3 -f crop -i "tiktok-id,instagram-id"
| Option |
Alias |
Description |
--integrations |
-i |
Comma-separated integration IDs to create a draft post for every clip |
--clips |
-n |
Maximum number of clips, 1-10 (default: 5) |
--fit |
-f |
blur (default) keeps the whole picture over a blurred copy of itself, crop fills the clip and cuts the sides |
Returns {"id": "<clipping-id>"} right away — clipping takes several minutes.
Check the status and get the clips
postiz clipping:status <clipping-id>
The status moves through analysing, transcribing (only when the video has no usable captions), picking and rendering, and ends on completed or failed. When completed, every clip carries its title, content, hosted video path and thumbnail. When failed, error says why and the clipping minutes are given back.
List clippings
postiz clipping:list
postiz clipping:list --page 2
Clipping uses the clipping minutes of your subscription: one minute for every minute of the source video. Only one clipping runs at a time per account.
Reddit
# Get available flairs
postiz integrations:trigger reddit-id getFlairs -d '{"subreddit":"programming"}'
# Post with subreddit and flair
postiz posts:create \
-c "Content" \
-s "2024-12-31T12:00:00Z" \
--settings '{"subreddit":[{"value":{"subreddit":"programming","title":"My Post","type":"text","is_flair_required":true,"flair":{"id":"flair-123","name":"Discussion"}}}]}' \
-i "reddit-id"
YouTube
# Get playlists
postiz integrations:trigger youtube-id getPlaylists
# Upload video FIRST (required!)
VIDEO=$(postiz upload video.mp4)
VIDEO_URL=$(echo "$VIDEO" | jq -r '.path')
# Post with uploaded video URL
postiz posts:create \
-c "Video description" \
-s "2024-12-31T12:00:00Z" \
--settings '{"title":"Video Title","type":"public","tags":[{"value":"tech","label":"Tech"}],"playlistId":"playlist-id"}' \
-m "$VIDEO_URL" \
-i "youtube-id"
TikTok
# Upload video FIRST (TikTok only accepts verified URLs!)
VIDEO=$(postiz upload video.mp4)
VIDEO_URL=$(echo "$VIDEO" | jq -r '.path')
# Post with uploaded video URL
postiz posts:create \
-c "Video caption #fyp" \
-s "2024-12-31T12:00:00Z" \
--settings '{"privacy_level":"PUBLIC_TO_EVERYONE","duet":true,"stitch":true,"content_posting_method":"DIRECT_POST"}' \
-m "$VIDEO_URL" \
-i "tiktok-id"
LinkedIn
# Get companies you can post to
postiz integrations:trigger linkedin-id getCompanies
# Post as company
postiz posts:create \
-c "Company announcement" \
-s "2024-12-31T12:00:00Z" \
--settings '{"companyId":"company-123"}' \
-i "linkedin-id"
# Create thread
postiz posts:create \
-c "Thread 1/3 🧵" \
-c "Thread 2/3" \
-c "Thread 3/3" \
-s "2024-12-31T12:00:00Z" \
-d 2000 \
-i "twitter-id"
# With reply settings
postiz posts:create \
-c "Tweet content" \
-s "2024-12-31T12:00:00Z" \
--settings '{"who_can_reply_post":"everyone"}' \
-i "twitter-id"
Instagram
# Upload image FIRST (Instagram requires verified URLs!)
IMAGE=$(postiz upload image.jpg)
IMAGE_URL=$(echo "$IMAGE" | jq -r '.path')
# Regular post
postiz posts:create \
-c "Caption #hashtag" \
-s "2024-12-31T12:00:00Z" \
--settings '{"post_type":"post"}' \
-m "$IMAGE_URL" \
-i "instagram-id"
# Story (upload first)
STORY=$(postiz upload story.jpg)
STORY_URL=$(echo "$STORY" | jq -r '.path')
postiz posts:create \
-c "" \
-s "2024-12-31T12:00:00Z" \
--settings '{"post_type":"story"}' \
-m "$STORY_URL" \
-i "instagram-id"
See PROVIDER_SETTINGS.md for all 28+ platforms.
Features for AI Agents
Discovery Workflow
The CLI enables dynamic discovery of integration capabilities:
- List integrations - Get available social media accounts
- Get settings - Retrieve character limits, required fields, and available tools
- Trigger tools - Fetch dynamic data (flairs, playlists, boards, etc.)
- Create posts - Use discovered data in posts
- Analyze - Get post analytics; if
{"missing": true} is returned, resolve with posts:missing + posts:connect
This allows AI agents to adapt to different platforms without hardcoded knowledge.
JSON Mode
For complex posts with multiple platforms and settings:
postiz posts:create --json complex-post.json
JSON structure:
{
"integrations": ["twitter-123", "linkedin-456"],
"posts": [
{
"provider": "twitter",
"post": [
{
"content": "Tweet version",
"image": ["twitter-image.jpg"]
}
]
},
{
"provider": "linkedin",
"post": [
{
"content": "LinkedIn version with more context...",
"image": ["linkedin-image.jpg"]
}
],
"settings": {
"__type": "linkedin",
"companyId": "company-123"
}
}
]
}
All Output is JSON
Every command outputs JSON for easy parsing:
INTEGRATIONS=$(postiz integrations:list | jq -r '.')
REDDIT_ID=$(echo "$INTEGRATIONS" | jq -r '.[] | select(.identifier=="reddit") | .id')
Threading Support
Comments are automatically converted to threads/replies based on platform:
- Twitter/X: Thread of tweets
- Reddit: Comment replies
- LinkedIn: Comment on post
- Instagram: First comment
postiz posts:create \
-c "Main post" \
-c "Comment 1" \
-c "Comment 2" \
-i "integration-id"
Common Workflows
Reddit Post with Flair
#!/bin/bash
REDDIT_ID=$(postiz integrations:list | jq -r '.[] | select(.identifier=="reddit") | .id')
FLAIRS=$(postiz integrations:trigger "$REDDIT_ID" getFlairs -d '{"subreddit":"programming"}')
FLAIR_ID=$(echo "$FLAIRS" | jq -r '.output[0].id')
postiz posts:create \
-c "My post content" \
-s "2024-12-31T12:00:00Z" \
--settings "{\"subreddit\":[{\"value\":{\"subreddit\":\"programming\",\"title\":\"Post Title\",\"type\":\"text\",\"is_flair_required\":true,\"flair\":{\"id\":\"$FLAIR_ID\",\"name\":\"Discussion\"}}}]}" \
-i "$REDDIT_ID"
YouTube Video Upload
#!/bin/bash
VIDEO=$(postiz upload video.mp4)
VIDEO_PATH=$(echo "$VIDEO" | jq -r '.path')
postiz posts:create \
-c "Video description..." \
-s "2024-12-31T12:00:00Z" \
--settings '{"title":"My Video","type":"public","tags":[{"value":"tech","label":"Tech"}]}' \
-m "$VIDEO_PATH" \
-i "youtube-id"
#!/bin/bash
postiz posts:create \
-c "Same content everywhere" \
-s "2024-12-31T12:00:00Z" \
-m "image.jpg" \
-i "twitter-id,linkedin-id,facebook-id"
Batch Scheduling
#!/bin/bash
DATES=("2024-02-14T09:00:00Z" "2024-02-15T09:00:00Z" "2024-02-16T09:00:00Z")
CONTENT=("Monday motivation 💪" "Tuesday tips 💡" "Wednesday wisdom 🧠")
for i in "${!DATES[@]}"; do
postiz posts:create \
-c "${CONTENT[$i]}" \
-s "${DATES[$i]}" \
-i "twitter-id"
done
Documentation
For AI Agents:
- SKILL.md - Complete skill reference with patterns and examples
Deep-Dive Guides:
Examples:
API Endpoints
The CLI interacts with these Postiz API endpoints:
| Endpoint |
Method |
Purpose |
/public/v1/posts |
POST |
Create a post |
/public/v1/posts |
GET |
List posts |
/public/v1/posts/:id |
DELETE |
Delete a post |
/public/v1/posts/:id/settings |
PUT |
Update a post's provider settings (merged; unpublished only) |
/public/v1/posts/:id/missing |
GET |
Get missing content from provider |
/public/v1/posts/:id/release-id |
PUT |
Update release ID for a post |
/public/v1/integrations |
GET |
List integrations (optional ?group= filter) |
/public/v1/groups |
GET |
List groups (customers) |
/public/v1/integration-settings/:id |
GET |
Get integration settings |
/public/v1/integration-trigger/:id |
POST |
Trigger integration tool |
/public/v1/analytics/:integration |
GET |
Get platform analytics |
/public/v1/analytics/post/:postId |
GET |
Get post analytics |
/public/v1/upload |
POST |
Upload media |
/public/v1/clipping |
POST |
Start clipping a YouTube video |
/public/v1/clipping |
GET |
List clippings (optional ?page=) |
/public/v1/clipping/:id |
GET |
Get a clipping and its clips |
Environment Variables
| Variable |
Required |
Default |
Description |
POSTIZ_API_KEY |
No* |
- |
Your Postiz API key |
POSTIZ_API_URL |
No |
https://api.postiz.com |
Custom API endpoint |
POSTIZ_AUTH_SERVER |
No |
https://cli-auth.postiz.com |
Custom auth server URL |
*Either OAuth2 (via postiz auth:login) or POSTIZ_API_KEY is required.
Error Handling
The CLI provides clear error messages with exit codes:
- Exit code 0: Success
- Exit code 1: Error occurred
Common errors:
| Error |
Solution |
Not authenticated |
Run postiz auth:login or set POSTIZ_API_KEY |
Integration not found |
Run integrations:list to get valid IDs |
startDate/endDate required |
Use ISO 8601 format: "2024-12-31T12:00:00Z" |
Invalid settings |
Check integrations:settings for required fields |
Tool not found |
Check available tools in integrations:settings output |
Upload failed |
Verify file exists and format is supported |
analytics:post returns {"missing": true} |
Run posts:missing <id> then posts:connect <id> --release-id "<rid>" |
Development
Project Structure
src/
├── index.ts # CLI entry point with yargs
├── api.ts # PostizAPI client class
├── config.ts # Configuration (OAuth2 + API key)
└── commands/
├── auth.ts # OAuth2 authentication (login/logout/status)
├── posts.ts # Post management commands
├── integrations.ts # Integration commands
├── analytics.ts # Analytics commands
└── upload.ts # Media upload command
examples/ # Example scripts and JSON files
package.json
tsconfig.json
tsup.config.ts # Build configuration
README.md # This file
SKILL.md # AI agent reference
Scripts
pnpm run dev # Watch mode for development
pnpm run build # Build the CLI
pnpm run start # Run the built CLI
Building
The CLI uses tsup for bundling:
pnpm run build
Output in dist/:
index.js - Bundled executable with shebangindex.js.map - Source map
Quick Reference
# Authentication
postiz auth:login # OAuth2 device flow
postiz auth:status # Check auth
postiz auth:logout # Remove credentials
export POSTIZ_API_KEY=your_key # Or use API key
# Discovery
postiz integrations:list # List integrations
postiz integrations:list --group "<group-id>" # List integrations in a group
postiz integrations:groups # List groups (customers)
postiz integrations:settings <id> # Get settings
postiz integrations:trigger <id> <method> -d '{}' # Fetch data
# Posting (date is required)
postiz posts:create -c "text" -s "2024-12-31T12:00:00Z" -i "id" # Simple
postiz posts:create -c "text" -s "2024-12-31T12:00:00Z" -t draft -i "id" # Draft
postiz posts:create -c "text" -m "img.jpg" -s "2024-12-31T12:00:00Z" -i "id" # With media
postiz posts:create -c "main" -c "comment" -s "2024-12-31T12:00:00Z" -i "id" # With comment
postiz posts:create -c "text" -s "2024-12-31T12:00:00Z" --settings '{}' -i "id" # Platform-specific
postiz posts:create --json file.json # Complex
# Management
postiz posts:list # List posts
postiz posts:delete <id> # Delete post
postiz posts:status <id> --status draft # Move to draft (stops workflow)
postiz posts:status <id> --status schedule # Queue draft for publishing
postiz posts:settings <id> --settings '{}' # Patch a post's settings (merged; DRAFT/QUEUE only)
postiz upload <file> # Upload media
# Analytics
postiz analytics:platform <id> # Platform analytics (7 days)
postiz analytics:platform <id> -d 30 # Platform analytics (30 days)
postiz analytics:post <id> # Post analytics (7 days)
postiz analytics:post <id> -d 30 # Post analytics (30 days)
# If analytics:post returns {"missing": true}, resolve it:
postiz posts:missing <id> # List provider content
postiz posts:connect <id> --release-id "<rid>" # Connect content to post
# Help
postiz --help # Show help
postiz posts:create --help # Command help
Contributing
This CLI is part of the Postiz monorepo.
To contribute:
- Fork the repository
- Create a feature branch
- Make your changes in
apps/cli/
- Run tests:
pnpm run build
- Submit a pull request
License
AGPL-3.0
Links
28+ platforms including:
| Platform |
Integration Tools |
Settings |
| Twitter/X |
getLists, getCommunities |
who_can_reply_post |
| LinkedIn |
getCompanies |
companyId, carousel |
| Reddit |
getFlairs, searchSubreddits |
subreddit, title, flair |
| YouTube |
getPlaylists, getCategories |
title, type, tags, playlistId |
| TikTok |
- |
content_posting_method, privacy_level, comment, brand toggles, duet/stitch/video_made_with_ai (video only), autoAddMusic (photo only) |
| Instagram |
- |
post_type (post/story) |
| Facebook |
getPages |
- |
| Pinterest |
getBoards, getBoardSections |
- |
| Discord |
getChannels |
- |
| Slack |
getChannels |
- |
| And 18+ more... |
|
|
See PROVIDER_SETTINGS.md for complete documentation.
Postiz Agents —— 一个命令行工具加一组 AI 代理技能，让 Claude Code 或 OpenClaw 这类 AI 代理通过 Postiz API 在 28 个以上的平台上定时发布和管理社交媒体帖子。