Skip to content
Back to search

postiz-agent

MarketplaceWorks with Claude CodeGitHub

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gitroomhq-postiz-agent/badge.svg)](/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.

  1. {
  2. "name": "postiz-agent",
  3. "owner": {
  4. "name": "Nevo David",
  5. "email": "nevo@postiz.com"
  6. },
  7. "metadata": {
  8. "description": "Postiz social media automation skill for scheduling posts across 28+ platforms",
  9. "version": "1.0.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "postiz",
  14. "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",
  15. "source": "./",
  16. "strict": false,
  17. "skills": [
  18. "./"
  19. ]
  20. }
  21. ]
  22. }
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.

  1. <p align="center">
  2. <img src="assets/logo.svg" alt="Postiz" width="96" />
  3. </p>
  4. <p align="center">
  5. <strong>Schedule posts with agents to:</strong><br />
  6. <a href="https://postiz.com/chatgpt">ChatGPT</a> ยท
  7. <a href="https://postiz.com/claude">Claude</a> ยท
  8. <a href="https://postiz.com/claude-cowork">Claude Cowork</a> ยท
  9. <a href="https://postiz.com/claude-code">Claude Code</a> ยท
  10. <a href="https://postiz.com/codex">Codex</a> ยท
  11. <a href="https://postiz.com/cursor">Cursor</a> ยท
  12. <a href="https://postiz.com/openclaw">OpenClaw</a> ยท
  13. <a href="https://postiz.com/hermes">Hermes Agent</a> ยท
  14. <a href="https://postiz.com/grok-bot">Grok Bot</a> ยท
  15. <a href="https://postiz.com/grok-build">Grok Build</a> ยท
  16. <a href="https://postiz.com/muse">Muse</a> ยท
  17. <a href="https://postiz.com/perplexity-computer">Perplexity Computer</a> ยท
  18. <a href="https://postiz.com/nanoclaw">nanoclaw</a> ยท
  19. <a href="https://postiz.com/paperclip">Paperclip</a> ยท
  20. <a href="https://postiz.com/mcp">MCP Server</a> ยท
  21. <a href="https://postiz.com/agent">AI Agents CLI</a>
  22. </p>
  23. ## Install as a skill
  24. ```bash
  25. npx skills add gitroomhq/postiz-agent
  26. ```
  27. ### Claude Code plugin
  28. ```bash
  29. /plugin marketplace add gitroomhq/postiz-agent
  30. /plugin install postiz@postiz-agent
  31. ```
  32. ### Grok Build plugin
  33. 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.
  34. 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.
  35. ### Cursor plugin
  36. This repo ships a [Cursor plugin](https://cursor.com/docs/reference/plugins) manifest at `.cursor-plugin/plugin.json`.
  37. - **From the marketplace / Customize panel:** open **Customize** in the Cursor sidebar, find **postiz**, and select **Install** (project or user scope).
  38. - **Local install (development):**
  39. ```bash
  40. git clone https://github.com/gitroomhq/postiz-agent.git
  41. ln -s "$(pwd)/postiz-agent" ~/.cursor/plugins/local/postiz
  42. ```
  43. then restart Cursor or run **Developer: Reload Window**.
  44. 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.
  45. ### Gemini CLI extension
  46. 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/).
  47. ```bash
  48. gemini extensions install https://github.com/gitroomhq/postiz-agent
  49. ```
  50. 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.
  51. ### Qwen Code
  52. Qwen Code installs Claude Code marketplaces directly, so no separate manifest is needed:
  53. ```bash
  54. qwen extensions install gitroomhq/postiz-agent:postiz
  55. ```
  56. ### DeepSeek Harness plugin
  57. 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.
  58. ```bash
  59. dsh plugin --profile web add "github:gitroomhq/postiz-agent#path:/plugins/dsh-postiz"
  60. export POSTIZ_API_KEY=your-api-key # Postiz โ†’ Settings โ†’ Developers โ†’ Public API
  61. dsh web
  62. ```
  63. 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.
  64. # Postiz CLI
  65. **Social media automation CLI for AI agents** - Schedule posts across 28+ platforms programmatically.
  66. 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.
  67. ---
  68. ## Installation
  69. ### From npm (Recommended)
  70. ```bash
  71. npm install -g postiz
  72. # or
  73. pnpm install -g postiz
  74. ```
  75. ---
  76. ## Authentication
  77. ### Option 1: OAuth2 (Recommended)
  78. Authenticate using the device flow โ€” no client ID or secret needed:
  79. ```bash
  80. postiz auth:login
  81. ```
  82. This will:
  83. 1. Display a one-time code in your terminal
  84. 2. Open your browser to authorize
  85. 3. Automatically save credentials to `~/.postiz/credentials.json`
  86. ```bash
  87. # Check current auth status (verifies credentials are still valid)
  88. postiz auth:status
  89. # Remove stored credentials
  90. postiz auth:logout
  91. ```
  92. #### Self-Hosting the Auth Server
  93. 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).
  94. ### Option 2: API Key
  95. ```bash
  96. export POSTIZ_API_KEY=your_api_key_here
  97. ```
  98. **Optional:** Custom API endpoint
  99. ```bash
  100. export POSTIZ_API_URL=https://your-custom-api.com
  101. ```
  102. > **Note:** OAuth2 credentials take priority over the API key when both are present.
  103. ---
  104. ## Commands
  105. ### Discovery & Settings
  106. **List all connected integrations**
  107. ```bash
  108. postiz integrations:list
  109. postiz integrations:list --group "customer-id"
  110. ```
  111. Returns integration IDs, provider names, and metadata. Use `--group` to return only the channels assigned to a specific group (customer).
  112. **List all groups (customers)**
  113. ```bash
  114. postiz integrations:groups
  115. ```
  116. Returns all groups (customers) for your organization as `{id, name}`. Use a group's `id` with `integrations:list --group` to filter channels.
  117. **Get integration settings schema**
  118. ```bash
  119. postiz integrations:settings <integration-id>
  120. ```
  121. Returns character limits, required settings, and available tools for fetching dynamic data.
  122. **Trigger integration tools**
  123. ```bash
  124. postiz integrations:trigger <integration-id> <method-name>
  125. postiz integrations:trigger <integration-id> <method-name> -d '{"key":"value"}'
  126. ```
  127. Fetch dynamic data like Reddit flairs, YouTube playlists, LinkedIn companies, etc.
  128. **Examples:**
  129. ```bash
  130. # Get Reddit flairs
  131. postiz integrations:trigger reddit-123 getFlairs -d '{"subreddit":"programming"}'
  132. # Get YouTube playlists
  133. postiz integrations:trigger youtube-456 getPlaylists
  134. # Get LinkedIn companies
  135. postiz integrations:trigger linkedin-789 getCompanies
  136. # Find a LinkedIn company page to tag, by its exact vanity name
  137. postiz integrations:trigger linkedin-789 mention -d '{"query":"microsoft"}'
  138. ```
  139. ---
  140. ### Creating Posts
  141. **Simple scheduled post**
  142. ```bash
  143. postiz posts:create -c "Content" -s "2024-12-31T12:00:00Z" -i "integration-id"
  144. ```
  145. **Draft post**
  146. ```bash
  147. postiz posts:create -c "Content" -s "2024-12-31T12:00:00Z" -t draft -i "integration-id"
  148. ```
  149. **Post with media**
  150. ```bash
  151. postiz posts:create -c "Content" -m "img1.jpg,img2.jpg" -s "2024-12-31T12:00:00Z" -i "integration-id"
  152. ```
  153. **Post with comments** (each comment can have its own media)
  154. ```bash
  155. postiz posts:create \
  156. -c "Main post" -m "main.jpg" \
  157. -c "First comment" -m "comment1.jpg" \
  158. -c "Second comment" -m "comment2.jpg,comment3.jpg" \
  159. -s "2024-12-31T12:00:00Z" \
  160. -i "integration-id"
  161. ```
  162. **Multi-platform post**
  163. ```bash
  164. postiz posts:create -c "Content" -s "2024-12-31T12:00:00Z" -i "twitter-id,linkedin-id,facebook-id"
  165. ```
  166. **Platform-specific settings**
  167. ```bash
  168. postiz posts:create \
  169. -c "Content" \
  170. -s "2024-12-31T12:00:00Z" \
  171. --settings '{"subreddit":[{"value":{"subreddit":"programming","title":"Post Title","type":"text"}}]}' \
  172. -i "reddit-id"
  173. ```
  174. **Complex post from JSON file**
  175. ```bash
  176. postiz posts:create --json post.json
  177. ```
  178. **Options:**
  179. - `-c, --content` - Post/comment content (use multiple times for posts with comments)
  180. - `-s, --date` - Schedule date in ISO 8601 format (REQUIRED)
  181. - `-t, --type` - Post type: "schedule" or "draft" (default: "schedule")
  182. - `-m, --media` - Comma-separated media URLs for corresponding `-c`
  183. - `--alt` - Comma-separated alt texts for the media of the corresponding `-m`, same order (use `--json` with `image[].alt` for alt texts containing commas)
  184. - `-i, --integrations` - Comma-separated integration IDs (required)
  185. - `-d, --delay` - Delay between comments in minutes (default: 0)
  186. - `--settings` - Platform-specific settings as JSON string
  187. - `-j, --json` - Path to JSON file with full post structure
  188. - `--shortLink` - Use short links (default: true)
  189. ---
  190. ### Managing Posts
  191. **List posts**
  192. ```bash
  193. postiz posts:list
  194. postiz posts:list --startDate "2024-01-01T00:00:00Z" --endDate "2024-12-31T23:59:59Z"
  195. postiz posts:list --customer "customer-id"
  196. ```
  197. 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).
  198. **Delete post**
  199. ```bash
  200. postiz posts:delete <post-id>
  201. ```
  202. **Change post status (draft โ†” schedule)**
  203. ```bash
  204. postiz posts:status <post-id> --status draft
  205. postiz posts:status <post-id> --status schedule
  206. ```
  207. 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.
  208. **Replace a post's attachments**
  209. ```bash
  210. postiz posts:attachments <post-id> -m "https://uploads.postiz.com/a.png,https://uploads.postiz.com/b.png"
  211. postiz posts:attachments <post-id> -m "https://uploads.postiz.com/a.png" --alt "A red bicycle"
  212. postiz posts:attachments <post-id> -m ""
  213. ```
  214. 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.
  215. **Update a post's provider-specific settings**
  216. ```bash
  217. postiz posts:settings <post-id> --settings '{"content_posting_method":"DIRECT_POST"}'
  218. postiz posts:settings <post-id> --settings '{"subreddit":[{"value":{"subreddit":"/r/selfhosted","title":"My title","type":"self","is_flair_required":true}}]}'
  219. ```
  220. 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.
  221. ---
  222. ### Analytics
  223. **Get platform analytics**
  224. ```bash
  225. postiz analytics:platform <integration-id>
  226. postiz analytics:platform <integration-id> -d 30
  227. ```
  228. 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).
  229. **Get post analytics**
  230. ```bash
  231. postiz analytics:post <post-id>
  232. postiz analytics:post <post-id> -d 30
  233. ```
  234. Returns metrics like likes, comments, shares, and impressions for a specific published post.
  235. **โš ๏ธ 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:
  236. ```bash
  237. # 1. List available content from the provider
  238. postiz posts:missing <post-id>
  239. # 2. Connect the correct content to the post
  240. postiz posts:connect <post-id> --release-id "7321456789012345678"
  241. # 3. Analytics will now work
  242. postiz analytics:post <post-id>
  243. ```
  244. ---
  245. ### Connecting Missing Posts
  246. 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.
  247. **List available content from the provider**
  248. ```bash
  249. postiz posts:missing <post-id>
  250. ```
  251. 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.
  252. **Connect a post to its published content**
  253. ```bash
  254. postiz posts:connect <post-id> --release-id "<content-id>"
  255. ```
  256. ---
  257. ### Media Upload
  258. **Upload file and get URL**
  259. ```bash
  260. postiz upload <file-path>
  261. ```
  262. **โš ๏ธ IMPORTANT: Upload Files Before Posting**
  263. 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.
  264. **Workflow:**
  265. 1. Upload your file using `postiz upload`
  266. 2. Extract the returned URL
  267. 3. Use that URL in your post's `-m` parameter
  268. **Supported formats:**
  269. - **Images:** PNG, JPG, JPEG, GIF
  270. - **Videos:** MP4
  271. **Example:**
  272. ```bash
  273. # 1. Upload the file first
  274. RESULT=$(postiz upload video.mp4)
  275. PATH=$(echo "$RESULT" | jq -r '.path')
  276. # 2. Use the Postiz URL in your post
  277. postiz posts:create -c "Check out my video!" -s "2024-12-31T12:00:00Z" -m "$PATH" -i "tiktok-id"
  278. ```
  279. **Adjust media to the platforms' limits**
  280. 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.
  281. ```bash
  282. postiz upload video.mp4 --adjust
  283. postiz media:status <id> # "processing" until the adjusted file is in place, then "ready"
  284. ```
  285. 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.
  286. **Reuse already uploaded media**
  287. Files already in your media library do not need uploading again. List them (newest first, 18 per page) and reuse a file's `path`:
  288. ```bash
  289. postiz media:list
  290. postiz media:list -s banner # filter by original file name (case-insensitive)
  291. postiz media:list -p 2 # page number, starting at 1
  292. ```
  293. 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`.
  294. **Why this is required:**
  295. - **TikTok, Instagram, YouTube** only accept URLs from trusted domains
  296. - **Security:** Platforms verify media sources to prevent abuse
  297. - **Reliability:** Postiz ensures your media is always accessible
  298. ---
  299. ### Clipping
  300. 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).
  301. **Start a clipping**
  302. ```bash
  303. postiz clipping:create "https://www.youtube.com/watch?v=VIDEO_ID"
  304. postiz clipping:create "https://www.youtube.com/watch?v=VIDEO_ID" -n 3 -f crop -i "tiktok-id,instagram-id"
  305. ```
  306. | Option | Alias | Description |
  307. |--------|-------|-------------|
  308. | `--integrations` | `-i` | Comma-separated integration IDs to create a draft post for every clip |
  309. | `--clips` | `-n` | Maximum number of clips, 1-10 (default: 5) |
  310. | `--fit` | `-f` | `blur` (default) keeps the whole picture over a blurred copy of itself, `crop` fills the clip and cuts the sides |
  311. Returns `{"id": "<clipping-id>"}` right away โ€” clipping takes several minutes.
  312. **Check the status and get the clips**
  313. ```bash
  314. postiz clipping:status <clipping-id>
  315. ```
  316. 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.
  317. **List clippings**
  318. ```bash
  319. postiz clipping:list
  320. postiz clipping:list --page 2
  321. ```
  322. 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.
  323. ---
  324. ## Platform-Specific Features
  325. ### Reddit
  326. ```bash
  327. # Get available flairs
  328. postiz integrations:trigger reddit-id getFlairs -d '{"subreddit":"programming"}'
  329. # Post with subreddit and flair
  330. postiz posts:create \
  331. -c "Content" \
  332. -s "2024-12-31T12:00:00Z" \
  333. --settings '{"subreddit":[{"value":{"subreddit":"programming","title":"My Post","type":"text","is_flair_required":true,"flair":{"id":"flair-123","name":"Discussion"}}}]}' \
  334. -i "reddit-id"
  335. ```
  336. ### YouTube
  337. ```bash
  338. # Get playlists
  339. postiz integrations:trigger youtube-id getPlaylists
  340. # Upload video FIRST (required!)
  341. VIDEO=$(postiz upload video.mp4)
  342. VIDEO_URL=$(echo "$VIDEO" | jq -r '.path')
  343. # Post with uploaded video URL
  344. postiz posts:create \
  345. -c "Video description" \
  346. -s "2024-12-31T12:00:00Z" \
  347. --settings '{"title":"Video Title","type":"public","tags":[{"value":"tech","label":"Tech"}],"playlistId":"playlist-id"}' \
  348. -m "$VIDEO_URL" \
  349. -i "youtube-id"
  350. ```
  351. ### TikTok
  352. ```bash
  353. # Upload video FIRST (TikTok only accepts verified URLs!)
  354. VIDEO=$(postiz upload video.mp4)
  355. VIDEO_URL=$(echo "$VIDEO" | jq -r '.path')
  356. # Post with uploaded video URL
  357. postiz posts:create \
  358. -c "Video caption #fyp" \
  359. -s "2024-12-31T12:00:00Z" \
  360. --settings '{"privacy_level":"PUBLIC_TO_EVERYONE","duet":true,"stitch":true,"content_posting_method":"DIRECT_POST"}' \
  361. -m "$VIDEO_URL" \
  362. -i "tiktok-id"
  363. ```
  364. ### LinkedIn
  365. ```bash
  366. # Get companies you can post to
  367. postiz integrations:trigger linkedin-id getCompanies
  368. # Post as company
  369. postiz posts:create \
  370. -c "Company announcement" \
  371. -s "2024-12-31T12:00:00Z" \
  372. --settings '{"companyId":"company-123"}' \
  373. -i "linkedin-id"
  374. ```
  375. ### X (Twitter)
  376. ```bash
  377. # Create thread
  378. postiz posts:create \
  379. -c "Thread 1/3 ๐Ÿงต" \
  380. -c "Thread 2/3" \
  381. -c "Thread 3/3" \
  382. -s "2024-12-31T12:00:00Z" \
  383. -d 2000 \
  384. -i "twitter-id"
  385. # With reply settings
  386. postiz posts:create \
  387. -c "Tweet content" \
  388. -s "2024-12-31T12:00:00Z" \
  389. --settings '{"who_can_reply_post":"everyone"}' \
  390. -i "twitter-id"
  391. ```
  392. ### Instagram
  393. ```bash
  394. # Upload image FIRST (Instagram requires verified URLs!)
  395. IMAGE=$(postiz upload image.jpg)
  396. IMAGE_URL=$(echo "$IMAGE" | jq -r '.path')
  397. # Regular post
  398. postiz posts:create \
  399. -c "Caption #hashtag" \
  400. -s "2024-12-31T12:00:00Z" \
  401. --settings '{"post_type":"post"}' \
  402. -m "$IMAGE_URL" \
  403. -i "instagram-id"
  404. # Story (upload first)
  405. STORY=$(postiz upload story.jpg)
  406. STORY_URL=$(echo "$STORY" | jq -r '.path')
  407. postiz posts:create \
  408. -c "" \
  409. -s "2024-12-31T12:00:00Z" \
  410. --settings '{"post_type":"story"}' \
  411. -m "$STORY_URL" \
  412. -i "instagram-id"
  413. ```
  414. **See [PROVIDER_SETTINGS.md](./PROVIDER_SETTINGS.md) for all 28+ platforms.**
  415. ---
  416. ## Features for AI Agents
  417. ### Discovery Workflow
  418. The CLI enables dynamic discovery of integration capabilities:
  419. 1. **List integrations** - Get available social media accounts
  420. 2. **Get settings** - Retrieve character limits, required fields, and available tools
  421. 3. **Trigger tools** - Fetch dynamic data (flairs, playlists, boards, etc.)
  422. 4. **Create posts** - Use discovered data in posts
  423. 5. **Analyze** - Get post analytics; if `{"missing": true}` is returned, resolve with `posts:missing` + `posts:connect`
  424. This allows AI agents to adapt to different platforms without hardcoded knowledge.
  425. ### JSON Mode
  426. For complex posts with multiple platforms and settings:
  427. ```bash
  428. postiz posts:create --json complex-post.json
  429. ```
  430. JSON structure:
  431. ```json
  432. {
  433. "integrations": ["twitter-123", "linkedin-456"],
  434. "posts": [
  435. {
  436. "provider": "twitter",
  437. "post": [
  438. {
  439. "content": "Tweet version",
  440. "image": ["twitter-image.jpg"]
  441. }
  442. ]
  443. },
  444. {
  445. "provider": "linkedin",
  446. "post": [
  447. {
  448. "content": "LinkedIn version with more context...",
  449. "image": ["linkedin-image.jpg"]
  450. }
  451. ],
  452. "settings": {
  453. "__type": "linkedin",
  454. "companyId": "company-123"
  455. }
  456. }
  457. ]
  458. }
  459. ```
  460. ### All Output is JSON
  461. Every command outputs JSON for easy parsing:
  462. ```bash
  463. INTEGRATIONS=$(postiz integrations:list | jq -r '.')
  464. REDDIT_ID=$(echo "$INTEGRATIONS" | jq -r '.[] | select(.identifier=="reddit") | .id')
  465. ```
  466. ### Threading Support
  467. Comments are automatically converted to threads/replies based on platform:
  468. - **Twitter/X**: Thread of tweets
  469. - **Reddit**: Comment replies
  470. - **LinkedIn**: Comment on post
  471. - **Instagram**: First comment
  472. ```bash
  473. postiz posts:create \
  474. -c "Main post" \
  475. -c "Comment 1" \
  476. -c "Comment 2" \
  477. -i "integration-id"
  478. ```
  479. ---
  480. ## Common Workflows
  481. ### Reddit Post with Flair
  482. ```bash
  483. #!/bin/bash
  484. REDDIT_ID=$(postiz integrations:list | jq -r '.[] | select(.identifier=="reddit") | .id')
  485. FLAIRS=$(postiz integrations:trigger "$REDDIT_ID" getFlairs -d '{"subreddit":"programming"}')
  486. FLAIR_ID=$(echo "$FLAIRS" | jq -r '.output[0].id')
  487. postiz posts:create \
  488. -c "My post content" \
  489. -s "2024-12-31T12:00:00Z" \
  490. --settings "{\"subreddit\":[{\"value\":{\"subreddit\":\"programming\",\"title\":\"Post Title\",\"type\":\"text\",\"is_flair_required\":true,\"flair\":{\"id\":\"$FLAIR_ID\",\"name\":\"Discussion\"}}}]}" \
  491. -i "$REDDIT_ID"
  492. ```
  493. ### YouTube Video Upload
  494. ```bash
  495. #!/bin/bash
  496. VIDEO=$(postiz upload video.mp4)
  497. VIDEO_PATH=$(echo "$VIDEO" | jq -r '.path')
  498. postiz posts:create \
  499. -c "Video description..." \
  500. -s "2024-12-31T12:00:00Z" \
  501. --settings '{"title":"My Video","type":"public","tags":[{"value":"tech","label":"Tech"}]}' \
  502. -m "$VIDEO_PATH" \
  503. -i "youtube-id"
  504. ```
  505. ### Multi-Platform Campaign
  506. ```bash
  507. #!/bin/bash
  508. postiz posts:create \
  509. -c "Same content everywhere" \
  510. -s "2024-12-31T12:00:00Z" \
  511. -m "image.jpg" \
  512. -i "twitter-id,linkedin-id,facebook-id"
  513. ```
  514. ### Batch Scheduling
  515. ```bash
  516. #!/bin/bash
  517. DATES=("2024-02-14T09:00:00Z" "2024-02-15T09:00:00Z" "2024-02-16T09:00:00Z")
  518. CONTENT=("Monday motivation ๐Ÿ’ช" "Tuesday tips ๐Ÿ’ก" "Wednesday wisdom ๐Ÿง ")
  519. for i in "${!DATES[@]}"; do
  520. postiz posts:create \
  521. -c "${CONTENT[$i]}" \
  522. -s "${DATES[$i]}" \
  523. -i "twitter-id"
  524. done
  525. ```
  526. ---
  527. ## Documentation
  528. **For AI Agents:**
  529. - **[SKILL.md](./SKILL.md)** - Complete skill reference with patterns and examples
  530. **Deep-Dive Guides:**
  531. - **[HOW_TO_RUN.md](./HOW_TO_RUN.md)** - Installation and setup methods
  532. - **[COMMAND_LINE_GUIDE.md](./COMMAND_LINE_GUIDE.md)** - Complete command syntax reference
  533. - **[PROVIDER_SETTINGS.md](./PROVIDER_SETTINGS.md)** - All platform settings schemas
  534. - **[INTEGRATION_TOOLS_WORKFLOW.md](./INTEGRATION_TOOLS_WORKFLOW.md)** - Tools workflow guide
  535. - **[INTEGRATION_SETTINGS_DISCOVERY.md](./INTEGRATION_SETTINGS_DISCOVERY.md)** - Settings discovery
  536. - **[SUPPORTED_FILE_TYPES.md](./SUPPORTED_FILE_TYPES.md)** - Media format reference
  537. - **[PROJECT_STRUCTURE.md](./PROJECT_STRUCTURE.md)** - Code architecture
  538. - **[PUBLISHING.md](./PUBLISHING.md)** - npm publishing guide
  539. **Examples:**
  540. - **[examples/EXAMPLES.md](./examples/EXAMPLES.md)** - Comprehensive examples
  541. - **[examples/](./examples/)** - Ready-to-use scripts and JSON files
  542. ---
  543. ## API Endpoints
  544. The CLI interacts with these Postiz API endpoints:
  545. | Endpoint | Method | Purpose |
  546. |----------|--------|---------|
  547. | `/public/v1/posts` | POST | Create a post |
  548. | `/public/v1/posts` | GET | List posts |
  549. | `/public/v1/posts/:id` | DELETE | Delete a post |
  550. | `/public/v1/posts/:id/settings` | PUT | Update a post's provider settings (merged; unpublished only) |
  551. | `/public/v1/posts/:id/missing` | GET | Get missing content from provider |
  552. | `/public/v1/posts/:id/release-id` | PUT | Update release ID for a post |
  553. | `/public/v1/integrations` | GET | List integrations (optional `?group=` filter) |
  554. | `/public/v1/groups` | GET | List groups (customers) |
  555. | `/public/v1/integration-settings/:id` | GET | Get integration settings |
  556. | `/public/v1/integration-trigger/:id` | POST | Trigger integration tool |
  557. | `/public/v1/analytics/:integration` | GET | Get platform analytics |
  558. | `/public/v1/analytics/post/:postId` | GET | Get post analytics |
  559. | `/public/v1/upload` | POST | Upload media |
  560. | `/public/v1/media` | GET | List uploaded media (optional `?page=`, `?search=`) |
  561. | `/public/v1/media/:id/status` | GET | Status of a media uploaded with `adjust` |
  562. | `/public/v1/clipping` | POST | Start clipping a YouTube video |
  563. | `/public/v1/clipping` | GET | List clippings (optional `?page=`) |
  564. | `/public/v1/clipping/:id` | GET | Get a clipping and its clips |
  565. ---
  566. ## Environment Variables
  567. | Variable | Required | Default | Description |
  568. |----------|----------|---------|-------------|
  569. | `POSTIZ_API_KEY` | No* | - | Your Postiz API key |
  570. | `POSTIZ_API_URL` | No | `https://api.postiz.com` | Custom API endpoint |
  571. | `POSTIZ_AUTH_SERVER` | No | `https://cli-auth.postiz.com` | Custom auth server URL |
  572. *Either OAuth2 (via `postiz auth:login`) or `POSTIZ_API_KEY` is required.
  573. ---
  574. ## Error Handling
  575. The CLI provides clear error messages with exit codes:
  576. - **Exit code 0**: Success
  577. - **Exit code 1**: Error occurred
  578. **Common errors:**
  579. | Error | Solution |
  580. |-------|----------|
  581. | `Not authenticated` | Run `postiz auth:login` or set `POSTIZ_API_KEY` |
  582. | `Integration not found` | Run `integrations:list` to get valid IDs |
  583. | `startDate/endDate required` | Use ISO 8601 format: `"2024-12-31T12:00:00Z"` |
  584. | `Invalid settings` | Check `integrations:settings` for required fields |
  585. | `Tool not found` | Check available tools in `integrations:settings` output |
  586. | `Upload failed` | Verify file exists and format is supported |
  587. | `analytics:post` returns `{"missing": true}` | Run `posts:missing <id>` then `posts:connect <id> --release-id "<rid>"` |
  588. ---
  589. ## Development
  590. ### Project Structure
  591. ```
  592. src/
  593. โ”œโ”€โ”€ index.ts # CLI entry point with yargs
  594. โ”œโ”€โ”€ api.ts # PostizAPI client class
  595. โ”œโ”€โ”€ config.ts # Configuration (OAuth2 + API key)
  596. โ””โ”€โ”€ commands/
  597. โ”œโ”€โ”€ auth.ts # OAuth2 authentication (login/logout/status)
  598. โ”œโ”€โ”€ posts.ts # Post management commands
  599. โ”œโ”€โ”€ integrations.ts # Integration commands
  600. โ”œโ”€โ”€ analytics.ts # Analytics commands
  601. โ””โ”€โ”€ upload.ts # Media upload command
  602. examples/ # Example scripts and JSON files
  603. package.json
  604. tsconfig.json
  605. tsup.config.ts # Build configuration
  606. README.md # This file
  607. SKILL.md # AI agent reference
  608. ```
  609. ### Scripts
  610. ```bash
  611. pnpm run dev # Watch mode for development
  612. pnpm run build # Build the CLI
  613. pnpm run start # Run the built CLI
  614. ```
  615. ### Building
  616. The CLI uses `tsup` for bundling:
  617. ```bash
  618. pnpm run build
  619. ```
  620. Output in `dist/`:
  621. - `index.js` - Bundled executable with shebang
  622. - `index.js.map` - Source map
  623. ---
  624. ## Quick Reference
  625. ```bash
  626. # Authentication
  627. postiz auth:login # OAuth2 device flow
  628. postiz auth:status # Check auth
  629. postiz auth:logout # Remove credentials
  630. export POSTIZ_API_KEY=your_key # Or use API key
  631. # Discovery
  632. postiz integrations:list # List integrations
  633. postiz integrations:list --group "<group-id>" # List integrations in a group
  634. postiz integrations:groups # List groups (customers)
  635. postiz integrations:settings <id> # Get settings
  636. postiz integrations:trigger <id> <method> -d '{}' # Fetch data
  637. # Posting (date is required)
  638. postiz posts:create -c "text" -s "2024-12-31T12:00:00Z" -i "id" # Simple
  639. postiz posts:create -c "text" -s "2024-12-31T12:00:00Z" -t draft -i "id" # Draft
  640. postiz posts:create -c "text" -m "img.jpg" -s "2024-12-31T12:00:00Z" -i "id" # With media
  641. postiz posts:create -c "main" -c "comment" -s "2024-12-31T12:00:00Z" -i "id" # With comment
  642. postiz posts:create -c "text" -s "2024-12-31T12:00:00Z" --settings '{}' -i "id" # Platform-specific
  643. postiz posts:create --json file.json # Complex
  644. # Management
  645. postiz posts:list # List posts
  646. postiz posts:delete <id> # Delete post
  647. postiz posts:status <id> --status draft # Move to draft (stops workflow)
  648. postiz posts:status <id> --status schedule # Queue draft for publishing
  649. postiz posts:settings <id> --settings '{}' # Patch a post's settings (merged; DRAFT/QUEUE only)
  650. postiz posts:attachments <id> -m "<url>,<url>" # Replace a post's attachments (DRAFT/QUEUE only)
  651. postiz upload <file> # Upload media
  652. postiz upload <file> --adjust # Upload and adjust to the platforms' limits
  653. postiz media:status <id> # Check an --adjust upload
  654. postiz media:list -s <name> # Find already uploaded media to reuse
  655. # Analytics
  656. postiz analytics:platform <id> # Platform analytics (7 days)
  657. postiz analytics:platform <id> -d 30 # Platform analytics (30 days)
  658. postiz analytics:post <id> # Post analytics (7 days)
  659. postiz analytics:post <id> -d 30 # Post analytics (30 days)
  660. # If analytics:post returns {"missing": true}, resolve it:
  661. postiz posts:missing <id> # List provider content
  662. postiz posts:connect <id> --release-id "<rid>" # Connect content to post
  663. # Help
  664. postiz --help # Show help
  665. postiz posts:create --help # Command help
  666. ```
  667. ---
  668. ## Contributing
  669. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and the pull request checklist (version bump, changelog entry, docs and release steps).
  670. ---
  671. ## License
  672. AGPL-3.0
  673. ---
  674. ## Links
  675. - **Website:** [postiz.com](https://postiz.com)
  676. - **API Docs:** [docs.postiz.com](https://docs.postiz.com)
  677. - **GitHub:** [gitroomhq/postiz-app](https://github.com/gitroomhq/postiz-app)
  678. - **Issues:** [Report bugs](https://github.com/gitroomhq/postiz-app/issues)
  679. ---
  680. ## Supported Platforms
  681. 28+ platforms including:
  682. | Platform | Integration Tools | Settings |
  683. |----------|------------------|----------|
  684. | Twitter/X | getLists, getCommunities | who_can_reply_post |
  685. | LinkedIn | getCompanies | companyId, carousel |
  686. | Reddit | getFlairs, searchSubreddits | subreddit, title, flair |
  687. | YouTube | getPlaylists, getCategories | title, type, tags, playlistId |
  688. | TikTok | - | content_posting_method, privacy_level, comment, brand toggles, duet/stitch/video_made_with_ai (video only), autoAddMusic (photo only) |
  689. | Instagram | - | post_type (post/story) |
  690. | Facebook | getPages | - |
  691. | Pinterest | getBoards, getBoardSections | - |
  692. | Discord | getChannels | - |
  693. | Slack | getChannels | - |
  694. | And 18+ more... | | |
  695. **See [PROVIDER_SETTINGS.md](./PROVIDER_SETTINGS.md) for complete documentation.**

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If itโ€™s helped, pass it on.