Install as a skill
npx skills add gitroomhq/postiz-agent
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
Returns integration IDs, provider names, and metadata.
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.
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.
Analytics