Postiz Agent CLI: Hand Your AI the Keys to 28 Social Platforms

John Doe
Tools , Agent
09 May, 2026

You built an agent that reads RSS feeds, summarizes papers, and generates cover images. Then you hit the last mile: it cannot actually publish anything.

Not because of a technical blocker, but because the ecosystem is fragmented. Most social platforms are built for humans, not programs. API docs live in scattered developer portals. Auth flows range from OAuth2 to custom tokens. Rate limits follow five different rules. You want your agent to auto-post a Twitter thread and cross-post to LinkedIn and Reddit, and suddenly you are debugging three SDKs, four token expiry strategies, and a maze of platform-specific gotchas.

Postiz Agent CLI closes that gap. It wraps 28 social platforms behind a single command-line interface, outputs pure JSON, handles auth via OAuth2 device flow, and lets agents discover platform capabilities dynamically instead of baking them in at training time.

This Is Not Another Buffer

Buffer and Hootsuite are for human operators. Their APIs are afterthoughts; the core interaction happens in a browser.

Postiz CLI is designed in reverse: the command line is the primary interface. Every operation returns structured JSON. Every platform capability can be queried at runtime. Your agent does not need to hardcode “Reddit needs a subreddit and flair.” It asks at execution time:

integrations:list —— what accounts do I have access to?
integrations:settings —— what parameters does this platform require? What is the character limit?
integrations:trigger —— what dynamic data can I fetch?

This means when a subreddit changes its rules, YouTube adds a required field, or you swap Reddit accounts, the agent does not need retraining or code changes. It adapts on the next publish cycle.

What Makes It Different

Dynamic Discovery, Zero Hardcoding

The discovery workflow is the biggest architectural difference between Postiz CLI and other social API wrappers:

integrations:list returns connected account IDs and platform types
integrations:settings returns character limits, required fields, and available tools per platform
integrations:trigger calls platform-specific tools — Reddit flairs, YouTube playlists, LinkedIn companies
The agent constructs its publish request from live data

This is not a convenience feature. It is an architectural choice. Hardcoded agents break when platform rules change. Discovery-based agents adapt.

JSON-Only Output

Every command outputs machine-parseable JSON. No human-friendly tables, no progress bar animations, no regex-extraction needed:

INTEGRATIONS=$(postiz integrations:list | jq -r '.')
REDDIT_ID=$(echo "$INTEGRATIONS" | jq -r '.[] | select(.identifier=="reddit") | .id')

Agents pipe output directly into downstream logic without a text-parsing layer.

28+ Platforms, One Interface

Twitter/X, LinkedIn, Reddit, YouTube, TikTok, Instagram, Facebook, Pinterest, Discord, Slack, Bluesky, Mastodon, Telegram, Medium, Dev.to — all share the same command structure:

posts:create — publish or schedule
posts:list / posts:delete / posts:status — manage
analytics:platform / analytics:post — metrics
upload — media hosting (mandatory step)

Platform-specific configs go through the settings flag, not an entirely different API.

Threads and Comments

A single command publishes a post with follow-up comments, automatically mapped to the correct format per platform:

Twitter/X: thread
Reddit: comment replies
LinkedIn: comment on post
Instagram: first comment

postiz posts:create \
  -c "Main post" \
  -c "Follow-up 1" \
  -c "Follow-up 2" \
  -s "2026-05-10T09:00:00Z" \
  -i "twitter-id"

When to Use It

Autonomous Content Agents

An agent that monitors GitHub releases, writes release notes, generates a cover image, and schedules the announcement. Postiz CLI lets it publish without knowing the difference between the Twitter API and the LinkedIn API. It only needs to know “postiz posts:create.”

Cross-Platform Sync Workflows

Same content, different platform variants: Twitter gets the short version with hashtags, LinkedIn gets the long-form professional take, Reddit needs a subreddit and flair. Define all variants in one JSON file and publish to every channel in a single command.

Data-Driven Publishing

The agent pulls analytics:platform for the last 30 days of engagement data, decides on timing and angle, publishes, then tracks performance with analytics:post. Closed loop.

The Gotchas

Media Must Be Uploaded First

TikTok, Instagram, and YouTube only accept Postiz-hosted URLs. External links or local paths are rejected:

# Wrong: passing a local file directly
postiz posts:create -c "Hello" -m "video.mp4" -i "tiktok-id"

# Right: upload first, then use the returned URL
VIDEO=$(postiz upload video.mp4 | jq -r '.path')
postiz posts:create -c "Hello" -m "$VIDEO" -i "tiktok-id"

This is not a Postiz quirk. It is a platform security policy. But newcomers trip on it almost every time.

analytics:post Returns missing

Some platforms — TikTok is the worst offender — do not return a post ID immediately after publishing. analytics:post returns {“missing”: true}. You must manually resolve it with posts:missing and posts:connect:

postiz posts:missing <post-id>
postiz posts:connect <post-id> --release-id "<content-id>"

This means a fully automated analytics loop is delayed for these platforms.

The __type Field in Settings

In JSON mode, each platform’s settings object needs a __type field identifying the platform. Forget it and you get a vague validation error instead of a clear “missing __type” message.

Installation and Auth

npm install -g postiz
# or
pnpm install -g postiz

Two auth methods. OAuth2 is recommended:

# Option 1: OAuth2 device flow, no client ID/secret needed
postiz auth:login

# Option 2: API Key
export POSTIZ_API_KEY=your_key

OAuth2 credentials are stored in ~/.postiz/credentials.json and take priority over API keys.

Quick Start: Agent Publishing Loop

A complete agent workflow:

#!/bin/bash

# 1. Auth check
postiz auth:status || postiz auth:login

# 2. Discover available accounts
REDDIT_ID=$(postiz integrations:list | jq -r '.[] | select(.identifier=="reddit") | .id')

# 3. Fetch dynamic data (flairs)
FLAIRS=$(postiz integrations:trigger "$REDDIT_ID" getFlairs -d '{"subreddit":"programming"}')
FLAIR_ID=$(echo "$FLAIRS" | jq -r '.output[0].id')

# 4. Upload media
IMG=$(postiz upload cover.jpg | jq -r '.path')

# 5. Publish
postiz posts:create \
  -c "Launching a new open-source CLI for social media automation" \
  -s "2026-05-10T14:00:00Z" \
  -m "$IMG" \
  --settings "{\"subreddit\":[{\"value\":{\"subreddit\":\"programming\",\"title\":\"Postiz CLI: Social Media Automation for Agents\",\"type\":\"text\",\"flair\":{\"id\":\"$FLAIR_ID\",\"name\":\"Showcase\"}}}]" \
  -i "$REDDIT_ID"

In Practice: Multi-Platform Campaign

Define cross-platform content variants in a JSON file:

{
  "type": "schedule",
  "date": "2026-05-10T09:00:00Z",
  "posts": [
    {
      "integration": { "id": "twitter-123" },
      "value": [{
        "content": "New CLI drops today. Auto-post to 28+ platforms from your agent. No API wrangling.",
        "image": [{ "id": "t1", "path": "twitter-cover.jpg" }]
      }]
    },
    {
      "integration": { "id": "linkedin-456" },
      "value": [{
        "content": "We built a CLI that lets AI agents publish to social media at scale. Here is why the architecture matters...",
        "image": [{ "id": "l1", "path": "linkedin-cover.jpg" }]
      }]
    }
  ]
}

postiz posts:create --json campaign.json

When Not to Use It

You only manage 1-2 platforms at low frequency — native APIs or official tools are lighter
Your agent needs real-time interaction (replying to comments, DMs) — Postiz CLI is a publishing tool, not a social CRM
You are latency-sensitive to the second — the scheduling system has minimum granularity limits

The Bottom Line

Social media publishing is the last mile for most content agents, and it is the messiest. Postiz CLI standardizes that last mile into a set of commands your agent can call like functions.

Its real value is not the “28 platforms” number. It is the discovery workflow: the agent does not need to know platform rules in advance. It queries them at runtime and adapts. That means your agent does not break when Twitter changes its API or Reddit adds a new required field.

GitHub: https://github.com/gitroomhq/postiz-agent npm: postiz