gitroomhq/postiz-agent: the Postiz CLI wrapped as an agent skill

What postiz-agent actually solves for an agent host

An agent that can write a post still cannot publish it. Publishing needs an authenticated session per platform, media upload handling, and a scheduler that fires at a chosen time. gitroomhq/postiz-agent exists to close that gap: it is the Postiz CLI plus the packaging that makes an agent host aware of it. The README describes the CLI as a "Social media automation CLI for AI agents" that schedules posts across 28+ platforms, naming Twitter/X, LinkedIn, Reddit, YouTube, TikTok, Instagram and Facebook. The audience is narrow and specific: developers running Claude Code, Cursor, Gemini CLI, Grok Build, Qwen Code or DeepSeek Harness who want the agent to end a session by scheduling something rather than printing text. If you post by hand, or you already drive the Postiz API from your own code, the skill layer adds nothing you need.

Skills, plugins and MCP: three ways the repository hooks into a host

The repository is not one integration. It ships several manifests side by side. There is a .claude-plugin directory, a .cursor-plugin directory with plugin.json, a .grok-plugin directory holding plugin.json and marketplace.json, a gemini-extension.json at the root, and a DeepSeek Harness bundle under plugins/dsh-postiz. The skill itself lives in skills/ and SKILL.md is copied into it by the sync-skill script in package.json.

The important split is which hosts get an MCP server. The README states that the Grok plugin bundles the hosted Postiz MCP server at https://mcp.postiz.com/mcp-oauth-dynamic through the mcpServers field, and that the Gemini CLI extension installs the same server. The Claude Code and Cursor plugins are described as skill and CLI only, with no MCP server registered. That difference decides your setup work: on Grok Build and Gemini CLI you sign in through a browser, while on Claude Code and Cursor the skill shells out to the postiz binary, which must be installed and authenticated first. The README is explicit that the CLI handles media uploads and is required for image or video posts. Text-only posting through the skill may work without it; the README does not say so, and I would not assume it.

Installing the postiz CLI and scheduling your first post

The CLI is the foundation, so install it before any plugin. It is published on npm as postiz and requires Node 18 or newer according to the engines field.

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

Authenticate with the device flow. The README says this prints a one-time code, opens a browser, and writes credentials to ~/.postiz/credentials.json.

postiz auth:login
postiz auth:status

If you prefer a key, the README gives POSTIZ_API_KEY as the environment variable, and notes that OAuth2 credentials take priority over the API key when both are present. A custom endpoint goes in POSTIZ_API_URL.

export POSTIZ_API_KEY=your_api_key_here

Now find the channel you want to post to. integrations:list returns integration IDs, provider names and metadata, and --group filters to one customer.

postiz integrations:list
postiz integrations:groups

With an integration ID in hand, schedule something. The README's simple example takes content, a start time and one or more integration IDs.

postiz posts:create -c "Content" -s "2024-12-31T12:00:00Z" -i "integration-id"

Add -t draft to hold the post rather than schedule it, -m with a comma-separated list for media, and repeat -c to attach comments, each of which can carry its own -m. Passing several IDs to -i fans the same content out to multiple platforms. For anything platform-specific, --settings takes a JSON object; the README shows a Reddit subreddit example. Check integrations:settings for the character limits and required fields before writing that JSON, and integrations:trigger for dynamic values such as Reddit flairs or YouTube playlists.

Where the design gets thin

The licence metadata is the first thing to check. The repository is reported as NOASSERTION, while package.json states AGPL-3.0. Those two disagree, and the file that would settle it, LICENSE, is only listed in the repository tree. Anyone embedding the CLI in a network service needs to read that file rather than trust either label.

The second gap is the README itself. It documents auth:login, auth:status and auth:logout, but says nothing about rollback or undoing a scheduled post, nothing about rate limits per provider, and nothing about what happens when a scheduled time is in the past. The truncated command list means the full set of subcommands is not visible here; the repository has a CHANGELOG.md and a QUICK_START.md, and those are the places to look. The documentation is also split across many files (FEATURES.md, PROVIDER_SETTINGS.md, INTEGRATION_SETTINGS_DISCOVERY.md, INTEGRATION_TOOLS_WORKFLOW.md), which is a lot of surface to keep current for a package at version 2.0.18.

Third, the whole thing assumes reachability. The default auth flow talks to cli-auth.postiz.com, and the MCP server is hosted at mcp.postiz.com. Self-hosting the OAuth2 device flow server is possible through server/SERVER.md, and a self-hosted Postiz instance can override baseUrl on the postiz row, but neither path is the default. If your network blocks those hosts, the skill is inert.

postiz-agent versus driving the Postiz API yourself

The obvious alternative is to skip the agent packaging and call the Postiz API directly from your own code. The difference is where the abstraction sits. With the API, you own authentication, retries, media upload and scheduling logic, and you get a dependency you can read end to end. With postiz-agent, the agent host owns the invocation: the model decides to call the skill, the skill calls the CLI, and the CLI calls the API. You get less code and less control. The CLI is a three-dependency package (yargs, node-fetch, @types/pg), so it is not a heavy thing to wrap, but it is still a binary in the loop between the model's intent and the published post.

A second alternative is a workflow tool such as n8n, which the related search phrases suggest people already associate with Postiz. The approaches differ in trigger. A workflow runs on a schedule you configure in a canvas; an agent skill runs when the model decides to use it during a conversation. If your posting is deterministic and calendar-driven, a workflow is the better fit. If it is a side effect of a conversation, the skill is.

Maintenance and upgrade cost

The last push was on 2026-09-11, the same day as the v2.0.18 release, and the two prior releases landed on 2026-09-01. The repository is not archived. That is a fast release cadence, and it is also the cost: six host integrations (Claude Code, Cursor, Gemini CLI, Grok Build, Qwen Code, DeepSeek Harness) each have their own manifest format, and every host can change its plugin or extension schema independently. The sync-skill script copying SKILL.md into skills/postiz/SKILL.md shows the duplication is managed by hand. Upgrading the npm package is trivial; keeping six manifests valid is not, and that work falls on the maintainers, not on you, unless a host breaks and the fix lags. Pin the CLI version in CI and read CHANGELOG.md before moving.

Editorial conclusion

Adopt postiz-agent if you already run an agent host it supports and you want scheduled posting to be one more tool the agent can call: the skill files, the plugin manifests and the hosted MCP server are all in the repository, and the CLI underneath is a plain npm package. Do not adopt it if you have no Postiz account, if you need a posting engine you can read and modify freely, or if you expect the skill to work without the CLI. Before trusting it, install postiz globally, run postiz auth:login and postiz auth:status to confirm the credential file at ~/.postiz/credentials.json, then run postiz integrations:list and check that the integration IDs you intend to target actually appear.

Frequently asked questions

Official sources

1. gitroomhq/postiz-agent on GitHub
2. Issues
3. Project website
4. README
5. Releases