postiz-agent

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:

1. Display a one-time code in your terminal
2. Open your browser to authorize
3. 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>

---

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