Postiz CLI - Advanced Examples

February 17, 2026 · View on GitHub

This directory contains examples demonstrating the full capabilities of the Postiz CLI, including posts with comments and multiple media.

Understanding the Post Structure

The Postiz API supports a rich post structure:

{
  type: 'now' | 'schedule' | 'draft' | 'update',
  date: string,              // ISO 8601 date
  shortLink: boolean,        // Use URL shortener
  tags: Tag[],              // Post tags
  posts: [                  // Can post to multiple platforms at once
    {
      integration: { id: string },    // Platform integration ID
      value: [                        // Main post + comments/thread
        {
          content: string,            // Post/comment text
          image: MediaDto[],          // Multiple media attachments
          delay?: number              // Delay in minutes before posting (for comments)
        },
        // ... more comments
      ],
      settings: { __type: 'EmptySettings' }
    }
  ]
}

Simple Usage Examples

Basic Post

postiz posts:create \
  -c "Hello World!" \
  -i "twitter-123"

Post with Multiple Images

postiz posts:create \
  -c "Check out these images!" \
  --image "https://example.com/img1.jpg,https://example.com/img2.jpg,https://example.com/img3.jpg" \
  -i "twitter-123"

Post with Comments (Simple)

postiz posts:create \
  -c "Main post content" \
  --comments "First comment;Second comment;Third comment" \
  -i "twitter-123"

Scheduled Post

postiz posts:create \
  -c "Future post" \
  -s "2024-12-31T12:00:00Z" \
  -i "twitter-123,linkedin-456"

Advanced JSON Examples

For complex posts with comments that have their own media, use JSON files:

1. Post with Comments and Media

File: post-with-comments.json

postiz posts:create --json examples/post-with-comments.json

This creates:

Main post with 2 images
First comment with 1 image (posted 5s after main)
Second comment with 2 images (posted 10s after main)

2. Multi-Platform Campaign

File: multi-platform-post.json

postiz posts:create --json examples/multi-platform-post.json

This creates:

Twitter post with main + comment
LinkedIn post with single content
Facebook post with main + comment All scheduled for the same time with platform-specific content and media!

3. Twitter Thread

File: thread-post.json

postiz posts:create --json examples/thread-post.json

This creates a 5-part Twitter thread, with each tweet having its own image and a 2-second delay between tweets.

JSON File Structure Explained

Basic Structure

{
  "type": "now",                    // "now", "schedule", "draft", "update"
  "date": "2024-01-15T12:00:00Z",  // When to post (ISO 8601)
  "shortLink": true,                // Enable URL shortening
  "tags": [],                       // Array of tags
  "posts": [...]                    // Array of posts
}

Post Structure

{
  "integration": {
    "id": "twitter-123"              // Get this from integrations:list
  },
  "value": [                         // Array of content (main + comments)
    {
      "content": "Post text",        // The actual content
      "image": [                     // Array of media
        {
          "id": "unique-id",         // Unique identifier
          "path": "https://..."      // URL to the image
        }
      ],
      "delay": 5                     // Optional delay in minutes
    }
  ],
  "settings": {
    "__type": "EmptySettings"        // Platform-specific settings
  }
}

Use Cases

1. Product Launch Campaign

Create a coordinated multi-platform launch:

{
  "type": "schedule",
  "date": "2024-03-15T09:00:00Z",
  "posts": [
    {
      "integration": { "id": "twitter-id" },
      "value": [
        { "content": "🚀 Launching today!", "image": [...] },
        { "content": "Special features:", "image": [...], "delay": 3600000 },
        { "content": "Get it now:", "image": [...], "delay": 7200000 }
      ]
    },
    {
      "integration": { "id": "linkedin-id" },
      "value": [
        { "content": "Professional announcement...", "image": [...] }
      ]
    }
  ]
}

2. Tutorial Series

Create an educational thread:

{
  "type": "now",
  "posts": [
    {
      "integration": { "id": "twitter-id" },
      "value": [
        { "content": "🧵 How to X (1/5)", "image": [...] },
        { "content": "Step 1: ... (2/5)", "image": [...], "delay": 2000 },
        { "content": "Step 2: ... (3/5)", "image": [...], "delay": 2000 },
        { "content": "Step 3: ... (4/5)", "image": [...], "delay": 2000 },
        { "content": "Conclusion (5/5)", "image": [...], "delay": 2000 }
      ]
    }
  ]
}

3. Event Coverage

Live event updates with media:

{
  "type": "now",
  "posts": [
    {
      "integration": { "id": "twitter-id" },
      "value": [
        {
          "content": "📍 Event starting now!",
          "image": [
            { "id": "1", "path": "venue-photo.jpg" }
          ]
        },
        {
          "content": "First speaker taking stage",
          "image": [
            { "id": "2", "path": "speaker-photo.jpg" }
          ],
          "delay": 1800000
        }
      ]
    }
  ]
}

Getting Integration IDs

Before creating posts, get your integration IDs:

postiz integrations:list

Output:

[
  { "id": "abc-123-twitter", "provider": "twitter", "name": "@myaccount" },
  { "id": "def-456-linkedin", "provider": "linkedin", "name": "My Company" }
]

Use these IDs in your integration.id fields.

Tips for AI Agents

Use JSON for complex posts - If you need comments with media, always use JSON files
Delays matter - Use appropriate delays between comments (Twitter: 2-5s, others: 30s-1min)
Image IDs - Generate unique IDs for each image (can use UUIDs or random strings)
Validate before sending - Check that all integration IDs exist
Test with "draft" type - Use "type": "draft" to create without posting

Automation Scripts

Batch Create from Directory

#!/bin/bash
# Create posts from all JSON files in a directory

for file in posts/*.json; do
  echo "Creating post from $file..."
  postiz posts:create --json "$file"
  sleep 2
done

Generate JSON Programmatically

# Generate a thread JSON file
cat > thread.json << 'EOF'
{
  "type": "now",
  "date": "2024-12-31T12:00:00Z",
  "shortLink": true,
  "tags": [],
  "posts": [{
    "integration": { "id": "twitter-123" },
    "value": [
      { "content": "Tweet 1", "image": [] },
      { "content": "Tweet 2", "image": [], "delay": 2000 },
      { "content": "Tweet 3", "image": [], "delay": 2000 }
    ],
    "settings": { "__type": "EmptySettings" }
  }]
}
EOF

# Post using the JSON file
postiz posts:create --json thread.json

Error Handling

Common errors and solutions:

Invalid integration ID - Run integrations:list to get valid IDs
Invalid image path - Ensure images are accessible URLs or uploaded to Postiz first
Missing required fields - Check that type, date, shortLink, tags, and posts are all present
Invalid date format - Use ISO 8601 format: YYYY-MM-DDTHH:mm:ssZ