postiz-agent
Postiz Agents CLI - connect it to Claude / OpenClaw / etc, to schedule social media posts ๐ค
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/gitroomhq/postiz-agent with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/gitroomhq/postiz-agent'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/gitroomhq-postiz-agent)HTML
<a href="/listings/gitroomhq-postiz-agent"><img src="/api/listings/gitroomhq-postiz-agent/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
npx skills add gitroomhq/postiz-agent
Claude Code plugin
/plugin marketplace add gitroomhq/postiz-agent /plugin install postiz@postiz-agent
Grok Build plugin
Postiz is listed in the [xAI plugin marketplace](https://github.com/xai-org/plugin-marketplace) โ install it from the marketplace inside Grok Build. This repo also carries its own `.grok-plugin/plugin.json` manifest and `.grok-plugin/marketplace.json` catalog, so it can be added as a marketplace source directly.
The Grok plugin also bundles the hosted Postiz MCP server (`https://mcp.postiz.com/mcp-oauth-dynamic`) via the `mcpServers` field in `.grok-plugin/plugin.json` โ you'll be asked to sign in to Postiz on first connection; no token or local install needed. The Claude Code and Cursor plugins are skill/CLI-only and do not register an MCP server.
Cursor plugin
This repo ships a [Cursor plugin](https://cursor.com/docs/reference/plugins) manifest at `.cursor-plugin/plugin.json`.
- **From the marketplace / Customize panel:** open **Customize** in the Cursor sidebar, find **postiz**, and select **Install** (project or user scope). - **Local install (development):**
git clone https://github.com/gitroomhq/postiz-agent.git ln -s "$(pwd)/postiz-agent" ~/.cursor/plugins/local/postiz
then restart Cursor or run **Developer: Reload Window**.
The plugin exposes the `postiz` skill, which drives the `postiz` CLI (the CLI handles media uploads, which is required for image/video posts). Make sure the CLI is installed (`npm install -g postiz`) and authenticated (`postiz auth:login` or `export POSTIZ_API_KEY=...`) before asking the agent to post.
Gemini CLI extension
This repo is a [Gemini CLI extension](https://geminicli.com/docs/extensions/) (`gemini-extension.json` at the root) and is indexed in the [extensions gallery](https://geminicli.com/extensions/browse/).
gemini extensions install https://github.com/gitroomhq/postiz-agent
It installs the `postiz` skill and the hosted Postiz MCP server (`https://mcp.postiz.com/mcp-oauth-dynamic`). Gemini CLI opens a browser to sign in to Postiz on first use; run `/mcp auth postiz` to re-authenticate. The skill drives the `postiz` CLI for media uploads, so install it with `npm install -g postiz` for image or video posts.
Qwen Code
Qwen Code installs Claude Code marketplaces directly, so no separate manifest is needed:
qwen extensions install gitroomhq/postiz-agent:postiz
DeepSeek Harness plugin
This repo ships a [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`) bundle at [`plugins/dsh-postiz`](plugins/dsh-postiz). It connects the agent to the hosted Postiz MCP server and registers a `postiz` workflow skill.
dsh plugin --profile web add "github:gitroomhq/postiz-agent#path:/plugins/dsh-postiz" export POSTIZ_API_KEY=your-api-key # Postiz โ Settings โ Developers โ Public API dsh web
The Postiz tools then appear as `mcp__postiz__*` (`integrationList`, `integrationSchema`, `schedulePostTool`, ...). Self-hosted instances override `baseUrl` on the `postiz` row. See the [plugin README](plugins/dsh-postiz/README.md) for configuration.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json ยท Manifest ยท 22 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- {
- "name": "postiz-agent",
- "owner": {
- "name": "Nevo David",
- "email": "nevo@postiz.com"
- },
- "metadata": {
- "description": "Postiz social media automation skill for scheduling posts across 28+ platforms",
- "version": "1.0.0"
- },
- "plugins": [
- {
- "name": "postiz",
- "description": "Social media automation CLI and MCP server for scheduling posts, managing integrations, uploading media, and tracking analytics across 28+ platforms including X, LinkedIn, LinkedIn Pages, Instagram, Facebook, Threads, YouTube, TikTok, Reddit, Pinterest, Bluesky, Mastodon, Google My Business, Discord, Slack, Telegram, Twitch, Kick, Lemmy, Farcaster, Nostr, VK, MeWe, Tumblr, Skool, Whop, Moltbook, Dribbble, Medium, Dev.to, Hashnode, WordPress, and ListMonk",
- "source": "./",
- "strict": false,
- "skills": [
- "./"
- ]
- }
- ]
- }
README.md ยท README ยท 910 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- <p align="center">
- <img src="assets/logo.svg" alt="Postiz" width="96" />
- </p>
- <p align="center">
- <strong>Schedule posts with agents to:</strong><br />
- <a href="https://postiz.com/chatgpt">ChatGPT</a> ยท
- <a href="https://postiz.com/claude">Claude</a> ยท
- <a href="https://postiz.com/claude-cowork">Claude Cowork</a> ยท
- <a href="https://postiz.com/claude-code">Claude Code</a> ยท
- <a href="https://postiz.com/codex">Codex</a> ยท
- <a href="https://postiz.com/cursor">Cursor</a> ยท
- <a href="https://postiz.com/openclaw">OpenClaw</a> ยท
- <a href="https://postiz.com/hermes">Hermes Agent</a> ยท
- <a href="https://postiz.com/grok-bot">Grok Bot</a> ยท
- <a href="https://postiz.com/grok-build">Grok Build</a> ยท
- <a href="https://postiz.com/muse">Muse</a> ยท
- <a href="https://postiz.com/perplexity-computer">Perplexity Computer</a> ยท
- <a href="https://postiz.com/nanoclaw">nanoclaw</a> ยท
- <a href="https://postiz.com/paperclip">Paperclip</a> ยท
- <a href="https://postiz.com/mcp">MCP Server</a> ยท
- <a href="https://postiz.com/agent">AI Agents CLI</a>
- </p>
- ## Install as a skill
- ```bash
- npx skills add gitroomhq/postiz-agent
- ```
- ### Claude Code plugin
- ```bash
- /plugin marketplace add gitroomhq/postiz-agent
- /plugin install postiz@postiz-agent
- ```
- ### Grok Build plugin
- Postiz is listed in the [xAI plugin marketplace](https://github.com/xai-org/plugin-marketplace) โ install it from the marketplace inside Grok Build. This repo also carries its own `.grok-plugin/plugin.json` manifest and `.grok-plugin/marketplace.json` catalog, so it can be added as a marketplace source directly.
- The Grok plugin also bundles the hosted Postiz MCP server (`https://mcp.postiz.com/mcp-oauth-dynamic`) via the `mcpServers` field in `.grok-plugin/plugin.json` โ you'll be asked to sign in to Postiz on first connection; no token or local install needed. The Claude Code and Cursor plugins are skill/CLI-only and do not register an MCP server.
- ### Cursor plugin
- This repo ships a [Cursor plugin](https://cursor.com/docs/reference/plugins) manifest at `.cursor-plugin/plugin.json`.
- - **From the marketplace / Customize panel:** open **Customize** in the Cursor sidebar, find **postiz**, and select **Install** (project or user scope).
- - **Local install (development):**
- ```bash
- git clone https://github.com/gitroomhq/postiz-agent.git
- ln -s "$(pwd)/postiz-agent" ~/.cursor/plugins/local/postiz
- ```
- then restart Cursor or run **Developer: Reload Window**.
- The plugin exposes the `postiz` skill, which drives the `postiz` CLI (the CLI handles media uploads, which is required for image/video posts). Make sure the CLI is installed (`npm install -g postiz`) and authenticated (`postiz auth:login` or `export POSTIZ_API_KEY=...`) before asking the agent to post.
- ### Gemini CLI extension
- This repo is a [Gemini CLI extension](https://geminicli.com/docs/extensions/) (`gemini-extension.json` at the root) and is indexed in the [extensions gallery](https://geminicli.com/extensions/browse/).
- ```bash
- gemini extensions install https://github.com/gitroomhq/postiz-agent
- ```
- It installs the `postiz` skill and the hosted Postiz MCP server (`https://mcp.postiz.com/mcp-oauth-dynamic`). Gemini CLI opens a browser to sign in to Postiz on first use; run `/mcp auth postiz` to re-authenticate. The skill drives the `postiz` CLI for media uploads, so install it with `npm install -g postiz` for image or video posts.
- ### Qwen Code
- Qwen Code installs Claude Code marketplaces directly, so no separate manifest is needed:
- ```bash
- qwen extensions install gitroomhq/postiz-agent:postiz
- ```
- ### DeepSeek Harness plugin
- This repo ships a [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`) bundle at [`plugins/dsh-postiz`](plugins/dsh-postiz). It connects the agent to the hosted Postiz MCP server and registers a `postiz` workflow skill.
- ```bash
- dsh plugin --profile web add "github:gitroomhq/postiz-agent#path:/plugins/dsh-postiz"
- export POSTIZ_API_KEY=your-api-key # Postiz โ Settings โ Developers โ Public API
- dsh web
- ```
- The Postiz tools then appear as `mcp__postiz__*` (`integrationList`, `integrationSchema`, `schedulePostTool`, ...). Self-hosted instances override `baseUrl` on the `postiz` row. See the [plugin README](plugins/dsh-postiz/README.md) for configuration.
- # 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)
- ```bash
- 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:
- ```bash
- 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`
- ```bash
- # 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`](./server/SERVER.md).
- ### Option 2: API Key
- ```bash
- export POSTIZ_API_KEY=your_api_key_here
- ```
- **Optional:** Custom API endpoint
- ```bash
- 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**
- ```bash
- 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)**
- ```bash
- 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**
- ```bash
- postiz integrations:settings <integration-id>
- ```
- Returns character limits, required settings, and available tools for fetching dynamic data.
- **Trigger integration tools**
- ```bash
- 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:**
- ```bash
- # 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
- # Find a LinkedIn company page to tag, by its exact vanity name
- postiz integrations:trigger linkedin-789 mention -d '{"query":"microsoft"}'
- ```
- ---
- ### Creating Posts
- **Simple scheduled post**
- ```bash
- postiz posts:create -c "Content" -s "2024-12-31T12:00:00Z" -i "integration-id"
- ```
- **Draft post**
- ```bash
- postiz posts:create -c "Content" -s "2024-12-31T12:00:00Z" -t draft -i "integration-id"
- ```
- **Post with media**
- ```bash
- 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)
- ```bash
- 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**
- ```bash
- postiz posts:create -c "Content" -s "2024-12-31T12:00:00Z" -i "twitter-id,linkedin-id,facebook-id"
- ```
- **Platform-specific settings**
- ```bash
- 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**
- ```bash
- 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`
- - `--alt` - Comma-separated alt texts for the media of the corresponding `-m`, same order (use `--json` with `image[].alt` for alt texts containing commas)
- - `-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**
- ```bash
- 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. Each returned post includes its current `settings` (returned as a JSON string โ `JSON.parse` it). The intended workflow is `posts:list` (read current settings) โ `posts:settings` (patch them).
- **Delete post**
- ```bash
- postiz posts:delete <post-id>
- ```
- **Change post status (draft โ schedule)**
- ```bash
- postiz posts:status <post-id> --status draft
- postiz posts:status <post-id> --status schedule
- ```
- Move a scheduled post back to a draft, or promote a draft into the publishing queue. Switching to `draft` also terminates any workflow that's already running for the post, so it won't publish. Switching to `schedule` queues the post for publishing at its stored date.
- **Replace a post's attachments**
- ```bash
- postiz posts:attachments <post-id> -m "https://uploads.postiz.com/a.png,https://uploads.postiz.com/b.png"
- postiz posts:attachments <post-id> -m "https://uploads.postiz.com/a.png" --alt "A red bicycle"
- postiz posts:attachments <post-id> -m ""
- ```
- Replaces the attachments of the main post server-side. The list you pass **replaces** all the existing attachments, so pass the full list the post should have; `-m ""` removes them all. The content, settings and publish date stay as they are. Only **DRAFT/QUEUE** (unpublished) posts can be updated; published posts are rejected. Pass the **main post id**, not a comment id; the attachments of comments are not changed. Removing all the attachments is refused when it would leave the post invalid: a post with no text, or a scheduled post on a platform that requires media.
- **Update a post's provider-specific settings**
- ```bash
- postiz posts:settings <post-id> --settings '{"content_posting_method":"DIRECT_POST"}'
- postiz posts:settings <post-id> --settings '{"subreddit":[{"value":{"subreddit":"/r/selfhosted","title":"My title","type":"self","is_flair_required":true}}]}'
- ```
- Patches a post's settings server-side. The backend **merges** the object โ only the keys you pass change, everything else is preserved โ so pass a partial object, not the full settings blob. Only **DRAFT/QUEUE** (unpublished) posts can be updated; published posts are rejected. Pass the **main post id**, not a comment id. Do **not** include `__type` โ the backend adds it automatically from the integration.
- ---
- ### Analytics
- **Get platform analytics**
- ```bash
- 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**
- ```bash
- postiz analytics:post <post-id>
- postiz analytics:post <post-id> -d 30
- ```
- Returns metrics like likes, comments, shares, and impressions for a specific published post.
- **โ ๏ธ If `analytics:post` returns `{"missing": true}`**, the post was published but the platform didn't return a usable post ID. You must resolve this before analytics will work:
- ```bash
- # 1. List available content from the provider
- postiz posts:missing <post-id>
- # 2. Connect the correct content to the post
- postiz posts:connect <post-id> --release-id "7321456789012345678"
- # 3. Analytics will now work
- postiz analytics:post <post-id>
- ```
- ---
- ### Connecting Missing Posts
- Some platforms (e.g. TikTok) don't return a post ID immediately after publishing. The post's `releaseId` is set to `"missing"` and analytics won't work until resolved.
- **List available content from the provider**
- ```bash
- postiz posts:missing <post-id>
- ```
- Returns an array of `{id, url}` items representing recent content from the provider. Returns an empty array if the provider doesn't support this feature.
- **Connect a post to its published content**
- ```bash
- postiz posts:connect <post-id> --release-id "<content-id>"
- ```
- ---
- ### Media Upload
- **Upload file and get URL**
- ```bash
- postiz upload <file-path>
- ```
- **โ ๏ธ IMPORTANT: Upload Files Before Posting**
- You **must** upload media files to Postiz before using them in posts. Many platforms (especially TikTok, Instagram, and YouTube) require verified/trusted URLs and will reject external links.
- **Workflow:**
- 1. Upload your file using `postiz upload`
- 2. Extract the returned URL
- 3. Use that URL in your post's `-m` parameter
- **Supported formats:**
- - **Images:** PNG, JPG, JPEG, GIF
- - **Videos:** MP4
- **Example:**
- ```bash
- # 1. Upload the file first
- RESULT=$(postiz upload video.mp4)
- PATH=$(echo "$RESULT" | jq -r '.path')
- # 2. Use the Postiz URL in your post
- postiz posts:create -c "Check out my video!" -s "2024-12-31T12:00:00Z" -m "$PATH" -i "tiktok-id"
- ```
- **Adjust media to the platforms' limits**
- Platforms reject media that is too large, too small or in an encoding they don't accept. Add `--adjust` (off by default) to adjust the file after the upload: videos get their short side scaled to 1080 px (long side at most 1920 px) and are re-encoded to H.264 MP4 with AAC audio, images are only scaled down to fit 1080 x 1920 and keep their format.
- ```bash
- postiz upload video.mp4 --adjust
- postiz media:status <id> # "processing" until the adjusted file is in place, then "ready"
- ```
- The status is `processing` until the adjusted file replaces the original at the same `path`, usually within seconds. Poll `media:status` and wait until it is `ready` before publishing a post with this `path`: a post published while it is `processing` uses the original, unadjusted file. If the adjustment fails, the original is kept and used for publishing, and the status is `ready` with a `warning`. Without `--adjust` the upload is synchronous and the `path` is ready immediately.
- **Reuse already uploaded media**
- Files already in your media library do not need uploading again. List them (newest first, 18 per page) and reuse a file's `path`:
- ```bash
- postiz media:list
- postiz media:list -s banner # filter by original file name (case-insensitive)
- postiz media:list -p 2 # page number, starting at 1
- ```
- Returns an object with `pages` (the total page count) and `results`, a list of files with `id`, `name`, `originalName`, `path` (the URL to reuse in a post) and `createdAt`.
- **Why this is required:**
- - **TikTok, Instagram, YouTube** only accept URLs from trusted domains
- - **Security:** Platforms verify media sources to prevent abuse
- - **Reliability:** Postiz ensures your media is always accessible
- ---
- ### Clipping
- Turn a long YouTube video into short vertical clips with burned-in captions. The best parts are picked automatically and every clip is saved to your media library. Pass integrations to also get a **draft** post per clip on every channel (nothing is scheduled or published).
- **Start a clipping**
- ```bash
- postiz clipping:create "https://www.youtube.com/watch?v=VIDEO_ID"
- postiz clipping:create "https://www.youtube.com/watch?v=VIDEO_ID" -n 3 -f crop -i "tiktok-id,instagram-id"
- ```
- | Option | Alias | Description |
- |--------|-------|-------------|
- | `--integrations` | `-i` | Comma-separated integration IDs to create a draft post for every clip |
- | `--clips` | `-n` | Maximum number of clips, 1-10 (default: 5) |
- | `--fit` | `-f` | `blur` (default) keeps the whole picture over a blurred copy of itself, `crop` fills the clip and cuts the sides |
- Returns `{"id": "<clipping-id>"}` right away โ clipping takes several minutes.
- **Check the status and get the clips**
- ```bash
- postiz clipping:status <clipping-id>
- ```
- The `status` moves through `analysing`, `transcribing` (only when the video has no usable captions), `picking` and `rendering`, and ends on `completed` or `failed`. When completed, every clip carries its `title`, `content`, hosted video `path` and `thumbnail`. When failed, `error` says why and the clipping minutes are given back.
- **List clippings**
- ```bash
- postiz clipping:list
- postiz clipping:list --page 2
- ```
- Clipping uses the clipping minutes of your subscription: one minute for every minute of the source video. Only one clipping runs at a time per account.
- ---
- ## Platform-Specific Features
- ```bash
- # Get available flairs
- postiz integrations:trigger reddit-id getFlairs -d '{"subreddit":"programming"}'
- # Post with subreddit and flair
- postiz posts:create \
- -c "Content" \
- -s "2024-12-31T12:00:00Z" \
- --settings '{"subreddit":[{"value":{"subreddit":"programming","title":"My Post","type":"text","is_flair_required":true,"flair":{"id":"flair-123","name":"Discussion"}}}]}' \
- -i "reddit-id"
- ```
- ### YouTube
- ```bash
- # Get playlists
- postiz integrations:trigger youtube-id getPlaylists
- # Upload video FIRST (required!)
- VIDEO=$(postiz upload video.mp4)
- VIDEO_URL=$(echo "$VIDEO" | jq -r '.path')
- # Post with uploaded video URL
- postiz posts:create \
- -c "Video description" \
- -s "2024-12-31T12:00:00Z" \
- --settings '{"title":"Video Title","type":"public","tags":[{"value":"tech","label":"Tech"}],"playlistId":"playlist-id"}' \
- -m "$VIDEO_URL" \
- -i "youtube-id"
- ```
- ### TikTok
- ```bash
- # Upload video FIRST (TikTok only accepts verified URLs!)
- VIDEO=$(postiz upload video.mp4)
- VIDEO_URL=$(echo "$VIDEO" | jq -r '.path')
- # Post with uploaded video URL
- postiz posts:create \
- -c "Video caption #fyp" \
- -s "2024-12-31T12:00:00Z" \
- --settings '{"privacy_level":"PUBLIC_TO_EVERYONE","duet":true,"stitch":true,"content_posting_method":"DIRECT_POST"}' \
- -m "$VIDEO_URL" \
- -i "tiktok-id"
- ```
- ```bash
- # Get companies you can post to
- postiz integrations:trigger linkedin-id getCompanies
- # Post as company
- postiz posts:create \
- -c "Company announcement" \
- -s "2024-12-31T12:00:00Z" \
- --settings '{"companyId":"company-123"}' \
- -i "linkedin-id"
- ```
- ### X (Twitter)
- ```bash
- # Create thread
- postiz posts:create \
- -c "Thread 1/3 ๐งต" \
- -c "Thread 2/3" \
- -c "Thread 3/3" \
- -s "2024-12-31T12:00:00Z" \
- -d 2000 \
- -i "twitter-id"
- # With reply settings
- postiz posts:create \
- -c "Tweet content" \
- -s "2024-12-31T12:00:00Z" \
- --settings '{"who_can_reply_post":"everyone"}' \
- -i "twitter-id"
- ```
- ```bash
- # 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 (upload first)
- 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"
- ```
- **See [PROVIDER_SETTINGS.md](./PROVIDER_SETTINGS.md) for all 28+ platforms.**
- ---
- ## Features for AI Agents
- ### Discovery Workflow
- The CLI enables dynamic discovery of integration capabilities:
- 1. **List integrations** - Get available social media accounts
- 2. **Get settings** - Retrieve character limits, required fields, and available tools
- 3. **Trigger tools** - Fetch dynamic data (flairs, playlists, boards, etc.)
- 4. **Create posts** - Use discovered data in posts
- 5. **Analyze** - Get post analytics; if `{"missing": true}` is returned, resolve with `posts:missing` + `posts:connect`
- This allows AI agents to adapt to different platforms without hardcoded knowledge.
- ### JSON Mode
- For complex posts with multiple platforms and settings:
- ```bash
- postiz posts:create --json complex-post.json
- ```
- JSON structure:
- ```json
- {
- "integrations": ["twitter-123", "linkedin-456"],
- "posts": [
- {
- "provider": "twitter",
- "post": [
- {
- "content": "Tweet version",
- "image": ["twitter-image.jpg"]
- }
- ]
- },
- {
- "provider": "linkedin",
- "post": [
- {
- "content": "LinkedIn version with more context...",
- "image": ["linkedin-image.jpg"]
- }
- ],
- "settings": {
- "__type": "linkedin",
- "companyId": "company-123"
- }
- }
- ]
- }
- ```
- ### All Output is JSON
- Every command outputs JSON for easy parsing:
- ```bash
- INTEGRATIONS=$(postiz integrations:list | jq -r '.')
- REDDIT_ID=$(echo "$INTEGRATIONS" | jq -r '.[] | select(.identifier=="reddit") | .id')
- ```
- ### Threading Support
- Comments are automatically converted to threads/replies based on platform:
- - **Twitter/X**: Thread of tweets
- - **Reddit**: Comment replies
- - **LinkedIn**: Comment on post
- - **Instagram**: First comment
- ```bash
- postiz posts:create \
- -c "Main post" \
- -c "Comment 1" \
- -c "Comment 2" \
- -i "integration-id"
- ```
- ---
- ## Common Workflows
- ### Reddit Post with Flair
- ```bash
- #!/bin/bash
- REDDIT_ID=$(postiz integrations:list | jq -r '.[] | select(.identifier=="reddit") | .id')
- FLAIRS=$(postiz integrations:trigger "$REDDIT_ID" getFlairs -d '{"subreddit":"programming"}')
- FLAIR_ID=$(echo "$FLAIRS" | jq -r '.output[0].id')
- 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 Video Upload
- ```bash
- #!/bin/bash
- VIDEO=$(postiz upload video.mp4)
- VIDEO_PATH=$(echo "$VIDEO" | jq -r '.path')
- postiz posts:create \
- -c "Video description..." \
- -s "2024-12-31T12:00:00Z" \
- --settings '{"title":"My Video","type":"public","tags":[{"value":"tech","label":"Tech"}]}' \
- -m "$VIDEO_PATH" \
- -i "youtube-id"
- ```
- ### Multi-Platform Campaign
- ```bash
- #!/bin/bash
- postiz posts:create \
- -c "Same content everywhere" \
- -s "2024-12-31T12:00:00Z" \
- -m "image.jpg" \
- -i "twitter-id,linkedin-id,facebook-id"
- ```
- ### Batch Scheduling
- ```bash
- #!/bin/bash
- 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"
- done
- ```
- ---
- ## Documentation
- **For AI Agents:**
- - **[SKILL.md](./SKILL.md)** - Complete skill reference with patterns and examples
- **Deep-Dive Guides:**
- - **[HOW_TO_RUN.md](./HOW_TO_RUN.md)** - Installation and setup methods
- - **[COMMAND_LINE_GUIDE.md](./COMMAND_LINE_GUIDE.md)** - Complete command syntax reference
- - **[PROVIDER_SETTINGS.md](./PROVIDER_SETTINGS.md)** - All platform settings schemas
- - **[INTEGRATION_TOOLS_WORKFLOW.md](./INTEGRATION_TOOLS_WORKFLOW.md)** - Tools workflow guide
- - **[INTEGRATION_SETTINGS_DISCOVERY.md](./INTEGRATION_SETTINGS_DISCOVERY.md)** - Settings discovery
- - **[SUPPORTED_FILE_TYPES.md](./SUPPORTED_FILE_TYPES.md)** - Media format reference
- - **[PROJECT_STRUCTURE.md](./PROJECT_STRUCTURE.md)** - Code architecture
- - **[PUBLISHING.md](./PUBLISHING.md)** - npm publishing guide
- **Examples:**
- - **[examples/EXAMPLES.md](./examples/EXAMPLES.md)** - Comprehensive examples
- - **[examples/](./examples/)** - Ready-to-use scripts and JSON files
- ---
- ## API Endpoints
- The CLI interacts with these Postiz API endpoints:
- | Endpoint | Method | Purpose |
- |----------|--------|---------|
- | `/public/v1/posts` | POST | Create a post |
- | `/public/v1/posts` | GET | List posts |
- | `/public/v1/posts/:id` | DELETE | Delete a post |
- | `/public/v1/posts/:id/settings` | PUT | Update a post's provider settings (merged; unpublished only) |
- | `/public/v1/posts/:id/missing` | GET | Get missing content from provider |
- | `/public/v1/posts/:id/release-id` | PUT | Update release ID for a post |
- | `/public/v1/integrations` | GET | List integrations (optional `?group=` filter) |
- | `/public/v1/groups` | GET | List groups (customers) |
- | `/public/v1/integration-settings/:id` | GET | Get integration settings |
- | `/public/v1/integration-trigger/:id` | POST | Trigger integration tool |
- | `/public/v1/analytics/:integration` | GET | Get platform analytics |
- | `/public/v1/analytics/post/:postId` | GET | Get post analytics |
- | `/public/v1/upload` | POST | Upload media |
- | `/public/v1/media` | GET | List uploaded media (optional `?page=`, `?search=`) |
- | `/public/v1/media/:id/status` | GET | Status of a media uploaded with `adjust` |
- | `/public/v1/clipping` | POST | Start clipping a YouTube video |
- | `/public/v1/clipping` | GET | List clippings (optional `?page=`) |
- | `/public/v1/clipping/:id` | GET | Get a clipping and its clips |
- ---
- ## Environment Variables
- | Variable | Required | Default | Description |
- |----------|----------|---------|-------------|
- | `POSTIZ_API_KEY` | No* | - | Your Postiz API key |
- | `POSTIZ_API_URL` | No | `https://api.postiz.com` | Custom API endpoint |
- | `POSTIZ_AUTH_SERVER` | No | `https://cli-auth.postiz.com` | Custom auth server URL |
- *Either OAuth2 (via `postiz auth:login`) or `POSTIZ_API_KEY` is required.
- ---
- ## Error Handling
- The CLI provides clear error messages with exit codes:
- - **Exit code 0**: Success
- - **Exit code 1**: Error occurred
- **Common errors:**
- | Error | Solution |
- |-------|----------|
- | `Not authenticated` | Run `postiz auth:login` or set `POSTIZ_API_KEY` |
- | `Integration not found` | Run `integrations:list` to get valid IDs |
- | `startDate/endDate required` | Use ISO 8601 format: `"2024-12-31T12:00:00Z"` |
- | `Invalid settings` | Check `integrations:settings` for required fields |
- | `Tool not found` | Check available tools in `integrations:settings` output |
- | `Upload failed` | Verify file exists and format is supported |
- | `analytics:post` returns `{"missing": true}` | Run `posts:missing <id>` then `posts:connect <id> --release-id "<rid>"` |
- ---
- ## Development
- ### Project Structure
- ```
- src/
- โโโ index.ts # CLI entry point with yargs
- โโโ api.ts # PostizAPI client class
- โโโ config.ts # Configuration (OAuth2 + API key)
- โโโ commands/
- โโโ auth.ts # OAuth2 authentication (login/logout/status)
- โโโ posts.ts # Post management commands
- โโโ integrations.ts # Integration commands
- โโโ analytics.ts # Analytics commands
- โโโ upload.ts # Media upload command
- examples/ # Example scripts and JSON files
- package.json
- tsconfig.json
- tsup.config.ts # Build configuration
- README.md # This file
- SKILL.md # AI agent reference
- ```
- ### Scripts
- ```bash
- pnpm run dev # Watch mode for development
- pnpm run build # Build the CLI
- pnpm run start # Run the built CLI
- ```
- ### Building
- The CLI uses `tsup` for bundling:
- ```bash
- pnpm run build
- ```
- Output in `dist/`:
- - `index.js` - Bundled executable with shebang
- - `index.js.map` - Source map
- ---
- ## Quick Reference
- ```bash
- # Authentication
- postiz auth:login # OAuth2 device flow
- postiz auth:status # Check auth
- postiz auth:logout # Remove credentials
- export POSTIZ_API_KEY=your_key # Or use API key
- # Discovery
- postiz integrations:list # List integrations
- postiz integrations:list --group "<group-id>" # List integrations in a group
- postiz integrations:groups # List groups (customers)
- postiz integrations:settings <id> # Get settings
- postiz integrations:trigger <id> <method> -d '{}' # Fetch 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 posts:status <id> --status draft # Move to draft (stops workflow)
- postiz posts:status <id> --status schedule # Queue draft for publishing
- postiz posts:settings <id> --settings '{}' # Patch a post's settings (merged; DRAFT/QUEUE only)
- postiz posts:attachments <id> -m "<url>,<url>" # Replace a post's attachments (DRAFT/QUEUE only)
- postiz upload <file> # Upload media
- postiz upload <file> --adjust # Upload and adjust to the platforms' limits
- postiz media:status <id> # Check an --adjust upload
- postiz media:list -s <name> # Find already uploaded media to reuse
- # 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
- ```
- ---
- ## Contributing
- See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and the pull request checklist (version bump, changelog entry, docs and release steps).
- ---
- ## License
- AGPL-3.0
- ---
- ## Links
- - **Website:** [postiz.com](https://postiz.com)
- - **API Docs:** [docs.postiz.com](https://docs.postiz.com)
- - **GitHub:** [gitroomhq/postiz-app](https://github.com/gitroomhq/postiz-app)
- - **Issues:** [Report bugs](https://github.com/gitroomhq/postiz-app/issues)
- ---
- ## Supported Platforms
- 28+ platforms including:
- | Platform | Integration Tools | Settings |
- |----------|------------------|----------|
- | Twitter/X | getLists, getCommunities | who_can_reply_post |
- | LinkedIn | getCompanies | companyId, carousel |
- | Reddit | getFlairs, searchSubreddits | subreddit, title, flair |
- | YouTube | getPlaylists, getCategories | title, type, tags, playlistId |
- | TikTok | - | content_posting_method, privacy_level, comment, brand toggles, duet/stitch/video_made_with_ai (video only), autoAddMusic (photo only) |
- | Instagram | - | post_type (post/story) |
- | Facebook | getPages | - |
- | Pinterest | getBoards, getBoardSections | - |
- | Discord | getChannels | - |
- | Slack | getChannels | - |
- | And 18+ more... | | |
- **See [PROVIDER_SETTINGS.md](./PROVIDER_SETTINGS.md) for complete documentation.**
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If itโs helped, pass it on.