Postiz is a tool to schedule social media and chat posts to 28+ channels X, LinkedIn, LinkedIn Page, Reddit, Instagram, Facebook Page, Threads, YouTube, Google My Business, TikTok, Pinterest, Dribbble, Discord, Slack, Kick, Twitch, Mastodon, Bluesky, Lemmy, Farcaster, Telegram, Nostr, VK, Medium, Dev.to, Hashnode, WordPress, ListMonk
npm install -g postiz
# or
pnpm install -g postiz
| Property | Value |
|---|---|
| name | postiz |
| description | Social media automation CLI for scheduling posts across 28+ platforms |
| allowed-tools | Bash(postiz:*) |
The fundamental pattern for using Postiz CLI:
{"missing": true}, run posts:missing to list provider content, then posts:connect to link it# 1. Discover
postiz integrations:list
postiz integrations:settings <integration-id>
# 2. Fetch (if needed)
postiz integrations:trigger <integration-id> <method> -d '{"key":"value"}'
# 3. Prepare
postiz upload image.jpg
# 4. Post
postiz posts:create -c "Content" -m "image.jpg" -i "<integration-id>"
# 5. Analyze
postiz analytics:platform <integration-id> -d 30
postiz analytics:post <post-id> -d 7
# 6. Resolve (if analytics returns {"missing": true})
postiz posts:missing <post-id>
postiz posts:connect <post-id> --release-id "<content-id>"
# Required environment variable
export POSTIZ_API_KEY=your_api_key_here
# Optional custom API URL
export POSTIZ_API_URL=https://custom-api-url.com
# List all connected integrations
postiz integrations:list
# Get settings schema for specific integration
postiz integrations:settings <integration-id>
# Trigger integration tool to fetch dynamic data
postiz integrations:trigger <integration-id> <method-name>
postiz integrations:trigger <integration-id> <method-name> -d '{"param":"value"}'
# Simple post (date is REQUIRED)
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 with 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":"My Post","type":"text"}}]}' \
-i "reddit-id"
# Complex post from JSON file
postiz posts:create --json post.json
# List posts (defaults to last 30 days to next 30 days)
postiz posts:list
# List posts in date range
postiz posts:list --startDate "2024-01-01T00:00:00Z" --endDate "2024-12-31T23:59:59Z"
# Delete post
postiz posts:delete <post-id>
# Get platform analytics (default: last 7 days)
postiz analytics:platform <integration-id>
# Get platform analytics for last 30 days
postiz analytics:platform <integration-id> -d 30
# Get post analytics (default: last 7 days)
postiz analytics:post <post-id>
# Get post analytics for last 30 days
postiz analytics:post <post-id> -d 30
Returns an array of metrics (e.g. Followers, Impressions, Likes, Comments) with daily data points and percentage change over the period.
⚠️ IMPORTANT: Missing Release ID Handling
If analytics:post returns {"missing": true} instead of an analytics array, the post was published but the platform didn't return a usable post ID. You must resolve this before analytics will work:
# 1. analytics:post returns {"missing": true}
postiz analytics:post <post-id>
# 2. Get available content from the provider
postiz posts:missing <post-id>
# Returns: [{"id": "7321456789012345678", "url": "https://...cover.jpg"}, ...]
# 3. Connect the correct content to the post
postiz posts:connect <post-id> --release-id "7321456789012345678"
# 4. Now analytics will work
postiz analytics:post <post-id>
Some platforms (e.g. TikTok) don't return a post ID immediately after publishing. When this happens, the post's releaseId is set to "missing" and analytics are unavailable until resolved.
# List recent content from the provider for a post with missing release ID
postiz posts:missing <post-id>
# Connect a post to its published content
postiz posts:connect <post-id> --release-id "<content-id>"
Returns an empty array if the provider doesn't support this feature or if the post doesn't have a missing release ID.
⚠️ IMPORTANT: Always upload files to Postiz before using them in posts. Many platforms (TikTok, Instagram, YouTube) require verified URLs and will reject external links.
# Upload file and get URL
postiz upload image.jpg
# Supports: images (PNG, JPG, GIF, WEBP, SVG), videos (MP4, MOV, AVI, MKV, WEBM),
# audio (MP3, WAV, OGG, AAC), documents (PDF, DOC, DOCX)
# Workflow: Upload → Extract URL → Use in post
VIDEO=$(postiz upload video.mp4)
VIDEO_PATH=$(echo "$VIDEO" | jq -r '.path')
postiz posts:create -c "Content" -s "2024-12-31T12:00:00Z" -m "$VIDEO_PATH" -i "tiktok-id"
Reddit - Get flairs for a subreddit:
# Get Reddit integration ID
REDDIT_ID=$(postiz integrations:list | jq -r '.[] | select(.identifier=="reddit") | .id')
# Fetch available flairs
FLAIRS=$(postiz integrations:trigger "$REDDIT_ID" getFlairs -d '{"subreddit":"programming"}')
FLAIR_ID=$(echo "$FLAIRS" | jq -r '.output[0].id')
# Use in post
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 - Get playlists:
YOUTUBE_ID=$(postiz integrations:list | jq -r '.[] | select(.identifier=="youtube") | .id')
PLAYLISTS=$(postiz integrations:trigger "$YOUTUBE_ID" getPlaylists)
PLAYLIST_ID=$(echo "$PLAYLISTS" | jq -r '.output[0].id')
postiz posts:create \
-c "Video description" \
-s "2024-12-31T12:00:00Z" \
--settings "{\"title\":\"My Video\",\"type\":\"public\",\"playlistId\":\"$PLAYLIST_ID\"}" \
-m "video.mp4" \
-i "$YOUTUBE_ID"
LinkedIn - Post as company:
LINKEDIN_ID=$(postiz integrations:list | jq -r '.[] | select(.identifier=="linkedin") | .id')
COMPANIES=$(postiz integrations:trigger "$LINKEDIN_ID" getCompanies)
COMPANY_ID=$(echo "$COMPANIES" | jq -r '.output[0].id')
postiz posts:create \
-c "Company announcement" \
-s "2024-12-31T12:00:00Z" \
--settings "{\"companyId\":\"$COMPANY_ID\"}" \
-i "$LINKEDIN_ID"
# Upload multiple files
VIDEO_RESULT=$(postiz upload video.mp4)
VIDEO_PATH=$(echo "$VIDEO_RESULT" | jq -r '.path')
THUMB_RESULT=$(postiz upload thumbnail.jpg)
THUMB_PATH=$(echo "$THUMB_RESULT" | jq -r '.path')
# Use in post
postiz posts:create \
-c "Check out my video!" \
-s "2024-12-31T12:00:00Z" \
-m "$VIDEO_PATH" \
-i "tiktok-id"
postiz posts:create \
-c "🧵 Thread starter (1/4)" -m "intro.jpg" \
-c "Point one (2/4)" -m "point1.jpg" \
-c "Point two (3/4)" -m "point2.jpg" \
-c "Conclusion (4/4)" -m "outro.jpg" \
-s "2024-12-31T12:00:00Z" \
-d 2000 \
-i "twitter-id"
# Create JSON file with platform-specific content
cat > campaign.json << 'EOF'
{
"integrations": ["twitter-123", "linkedin-456", "facebook-789"],
"posts": [
{
"provider": "twitter",
"post": [
{
"content": "Short tweet version #tech",
"image": ["twitter-image.jpg"]
}
]
},
{
"provider": "linkedin",
"post": [
{
"content": "Professional LinkedIn version with more context...",
"image": ["linkedin-image.jpg"]
}
]
}
]
}
EOF
postiz posts:create --json campaign.json
#!/bin/bash
INTEGRATION_ID="twitter-123"
CONTENT="Your post content here"
# Get integration settings and extract max length
SETTINGS_JSON=$(postiz integrations:settings "$INTEGRATION_ID")
MAX_LENGTH=$(echo "$SETTINGS_JSON" | jq '.output.maxLength')
# Check character limit and truncate if needed
if [ ${#CONTENT} -gt "$MAX_LENGTH" ]; then
echo "Content exceeds $MAX_LENGTH chars, truncating..."
CONTENT="${CONTENT:0:$((MAX_LENGTH - 3))}..."
fi
# Create post with settings
postiz posts:create \
-c "$CONTENT" \
-s "2024-12-31T12:00:00Z" \
--settings '{"key": "value"}' \
-i "$INTEGRATION_ID"
#!/bin/bash
# Schedule posts for the week
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" \
-m "post-${i}.jpg"
echo "Scheduled: ${CONTENT[$i]} for ${DATES[$i]}"
done
#!/bin/bash
CONTENT="Your post content"
INTEGRATION_ID="twitter-123"
DATE="2024-12-31T12:00:00Z"
MAX_RETRIES=3
for attempt in $(seq 1 $MAX_RETRIES); do
if postiz posts:create -c "$CONTENT" -s "$DATE" -i "$INTEGRATION_ID"; then
echo "Post created successfully"
break
else
echo "Attempt $attempt failed"
if [ "$attempt" -lt "$MAX_RETRIES" ]; then
DELAY=$((2 ** attempt))
echo "Retrying in ${DELAY}s..."
sleep "$DELAY"
else
echo "Failed after $MAX_RETRIES attempts"
exit 1
fi
fi
done
Many integrations require dynamic data (IDs, tags, playlists) that can't be hardcoded. The tools workflow enables discovery and usage:
integrations:settings returns a tools arraymethodName, description, and dataSchemaintegrations:trigger with required parametersExample tools by platform:
getFlairs, searchSubreddits, getSubredditsgetPlaylists, getCategories, getChannelsgetCompanies, getOrganizationsgetListsowned, getCommunitiesgetBoards, getBoardSectionsPlatform-specific settings use a discriminator pattern with __type field:
{
"posts": [
{
"provider": "reddit",
"post": [{ "content": "...", "image": [...] }],
"settings": {
"__type": "reddit",
"subreddit": [{
"value": {
"subreddit": "programming",
"title": "Post Title",
"type": "text",
"url": "",
"is_flair_required": false
}
}]
}
}
]
}
Pass settings directly:
postiz posts:create -c "Content" -s "2024-12-31T12:00:00Z" --settings '{"subreddit":[...]}' -i "reddit-id"
# Backend automatically adds "__type" based on integration ID
Posts can have comments (threads on Twitter/X, replies elsewhere). Each comment can have its own media:
# Using multiple -c and -m flags
postiz posts:create \
-c "Main post" -m "image1.jpg,image2.jpg" \
-c "Comment 1" -m "comment-img.jpg" \
-c "Comment 2" -m "another.jpg,more.jpg" \
-s "2024-12-31T12:00:00Z" \
-d 5 \ # Delay between comments in minutes
-i "integration-id"
Internally creates:
{
"posts": [{
"value": [
{ "content": "Main post", "image": ["image1.jpg", "image2.jpg"] },
{ "content": "Comment 1", "image": ["comment-img.jpg"], "delay": 5 },
{ "content": "Comment 2", "image": ["another.jpg", "more.jpg"], "delay": 5 }
]
}]
}
All dates use ISO 8601 format:
-s "2024-12-31T12:00:00Z"--startDate "2024-01-01T00:00:00Z" --endDate "2024-12-31T23:59:59Z"posts:list uses 30 days ago to 30 days from nowUpload returns JSON with path and metadata:
{
"path": "https://cdn.postiz.com/uploads/abc123.jpg",
"size": 123456,
"type": "image/jpeg"
}
Extract path for use in posts:
RESULT=$(postiz upload image.jpg)
PATH=$(echo "$RESULT" | jq -r '.path')
postiz posts:create -c "Content" -s "2024-12-31T12:00:00Z" -m "$PATH" -i "integration-id"
CLI flags - Quick posts:
postiz posts:create -c "Content" -m "img.jpg" -i "twitter-id"
JSON mode - Complex posts with multiple platforms and settings:
postiz posts:create --json post.json
JSON mode supports:
postiz posts:create \
-c "Post content" \
-s "2024-12-31T12:00:00Z" \
--settings '{"subreddit":[{"value":{"subreddit":"programming","title":"My Title","type":"text","url":"","is_flair_required":false}}]}' \
-i "reddit-id"
# Upload video first (required!)
VIDEO=$(postiz upload video.mp4)
VIDEO_URL=$(echo "$VIDEO" | jq -r '.path')
postiz posts:create \
-c "Video description" \
-s "2024-12-31T12:00:00Z" \
--settings '{"title":"Video Title","type":"public","tags":[{"value":"tech","label":"Tech"}]}' \
-m "$VIDEO_URL" \
-i "youtube-id"
# Upload video first (TikTok only accepts verified URLs!)
VIDEO=$(postiz upload video.mp4)
VIDEO_URL=$(echo "$VIDEO" | jq -r '.path')
postiz posts:create \
-c "Video caption #fyp" \
-s "2024-12-31T12:00:00Z" \
--settings '{"privacy":"PUBLIC_TO_EVERYONE","duet":true,"stitch":true}' \
-m "$VIDEO_URL" \
-i "tiktok-id"
postiz posts:create \
-c "Tweet content" \
-s "2024-12-31T12:00:00Z" \
--settings '{"who_can_reply_post":"everyone"}' \
-i "twitter-id"
# Personal post
postiz posts:create -c "Content" -s "2024-12-31T12:00:00Z" -i "linkedin-id"
# Company post
postiz posts:create \
-c "Content" \
-s "2024-12-31T12:00:00Z" \
--settings '{"companyId":"company-123"}' \
-i "linkedin-id"
# 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
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"
Deep-dive documentation:
Ready-to-use examples:
export POSTIZ_API_KEY=key before using CLIintegrations:list to get current IDsintegrations:settings for required fieldspostiz upload first, then use the returned URL in -m. External URLs will be rejected!--settings '{...}'"2024-12-31T12:00:00Z" and is REQUIREDintegrations:settings outputmaxLength in settings{"missing": true} - The post was published but the platform didn't return a post ID. Run posts:missing <post-id> to get available content, then posts:connect <post-id> --release-id "<id>" to link it. Analytics will work after connecting.# Environment
export POSTIZ_API_KEY=key
# Discovery
postiz integrations:list # Get integration IDs
postiz integrations:settings <id> # Get settings schema
postiz integrations:trigger <id> <method> -d '{}' # Fetch dynamic 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 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