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
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.
Delete post
postiz posts:delete <post-id>
