Postiz CLI and MCP: A Review-First Social Scheduling Workflow

Independent field note, September 2026: I use managed Postiz to schedule and monitor LazyingArt posts. This workflow was tested with Postiz CLI 2.0.15; the official source has moved since then, so re-check every command against your installed version. This is not a sponsored article, contains no referral link, and does not imply that a scheduled item was actually published or earned revenue.

The useful automation boundary is not “let an agent post everywhere.” It is:

let software prepare, schedule, and observe; require a person to approve the exact destination, copy, media, and irreversible action.

That distinction matters because every platform has different fields and rules, a successful scheduler response may still lack a verifiable public release, and engagement is not the same as a lead or a sale.

1. Decide whether Postiz fits

Postiz is a reasonable fit when you manage several channels, need a reviewable calendar, want platform-specific settings, or need a CLI/API/MCP surface for a controlled workflow. It may be unnecessary when you publish rarely to one channel. Self-hosting is not automatically cheaper once backups, upgrades, databases, storage, OAuth applications, provider secrets, monitoring, and incident response are counted.

Need Practical route
A maintained scheduler with less infrastructure work Managed Postiz
Full infrastructure control and willingness to operate the stack Official open-source Postiz deployment
One occasional post on one platform Use the platform directly
Automated replies or unsolicited engagement Do not use this workflow

The official repository is open source, but the current Docker Compose stack is more than one container. It includes Postiz, PostgreSQL, Redis, and a Temporal stack with its own PostgreSQL, Elasticsearch, admin tools, and UI. Review the current deployment files instead of copying an old compose fragment.

2. Install and authenticate without leaking credentials

The package requires Node.js 18 or newer. Install the CLI from npm and verify the exact version you are running:

npm install -g postiz
postiz --version
postiz auth:login
postiz auth:status

The OAuth device flow stores credentials under ~/.postiz/credentials.json. Keep that file, API keys, OAuth tokens, integration IDs, organization identifiers, and raw command output out of Git, screenshots, issue reports, and agent transcripts. In my current CLI, auth:status displays a token prefix and organization identifier; treat even that abbreviated output as private.

If both OAuth credentials and POSTIZ_API_KEY exist, the CLI gives OAuth priority. For testing, use a separate Postiz account or organization containing no production integrations. A separate shell or browser profile alone is not an authorization boundary.

3. Discover each provider’s live contract

Do not hard-code a provider schema from an old example. First list the connected integrations, select the intended one privately, and fetch its current settings:

postiz integrations:list

INTEGRATION_ID="replace-with-the-reviewed-private-id"
postiz integrations:settings "$INTEGRATION_ID"

The settings response describes character limits, required fields, provider-specific options, and dynamic tools. For example, a Reddit destination may require a subreddit, title, post type, and flair selected through a provider tool. In CLI 2.0.15 testing, some irrelevant settings were ignored rather than rejected. Treat that as observed behavior, not an API guarantee; always follow the live schema and rules.

Keep integration IDs in an ignored local configuration file or a short-lived shell variable. Public campaign files should contain stable labels such as x or instagram, not account identifiers.

4. Create a draft before a schedule

posts:create is a state-changing command even when the result is only a draft. Review the destination, ISO 8601 time, timezone, content, and settings before running it:

postiz posts:create \
  -c "Platform-specific copy reviewed by a person" \
  -s "YYYY-MM-DDTHH:MM:SSZ" \
  -t draft \
  -i "$INTEGRATION_ID"

Then inspect the stored draft and any available UI preview in the visible Postiz calendar. Only promote it to the queue after those are correct:

POST_ID="replace-with-the-reviewed-private-post-id"

# Starts the publishing workflow at the draft's stored date.
postiz posts:status "$POST_ID" --status schedule

# Before provider publication, withdraw it and terminate the running workflow.
postiz posts:status "$POST_ID" --status draft

Withdrawal is not a rollback after a provider has published. Do not use one identical block of text merely because the CLI accepts several integration IDs: X, Instagram, Reddit, LinkedIn, and video platforms have different reader expectations as well as different technical limits.

For a first test, use a reversible draft with no external link. Never test with a paid campaign, a private customer document, or a message that would be harmful if published accidentally.

5. Upload media before attaching it

Media fields expect a URL returned by Postiz’s upload path, not an arbitrary local filename or third-party URL. Upload first, check the response, and pass only the returned path:

UPLOAD_JSON="$(postiz upload ./reviewed-cover.png)"
MEDIA_URL="$(printf '%s' "$UPLOAD_JSON" | jq -er '.path | strings | select(length > 0)')"

postiz posts:create \
  -c "Reviewed caption" \
  -m "$MEDIA_URL" \
  -s "YYYY-MM-DDTHH:MM:SSZ" \
  -t draft \
  -i "$INTEGRATION_ID"

Before scheduling, verify the local file’s dimensions, type, duration when applicable, rights, and absence of private metadata. For TikTok, YouTube, Instagram, and other media-heavy providers, fetch the integration settings immediately before use; publishing mode and required disclosures can change the result.

6. Separate scheduler state from public proof

A queue entry is not a public post. A provider ID is not necessarily a usable public URL. A click is not a lead, and a pending commission is not income.

Use a bounded date range to inspect scheduler state:

postiz posts:list \
  --startDate "YYYY-MM-DDT00:00:00Z" \
  --endDate "YYYY-MM-DDT23:59:59Z"

For a supposedly published item, open the exact release URL in a visible browser and confirm the account, content, media, timestamp, and destination. If post analytics returns {"missing": true}, do not reconnect the first result automatically:

postiz posts:missing "$POST_ID"

# Only after visually identifying the exact provider item:
postiz posts:connect "$POST_ID" --release-id "$REVIEWED_RELEASE_ID"
postiz analytics:post "$POST_ID" -d 30

An ambiguous publish result is a reason to inspect, not to retry. Retrying can create duplicates. Keep Postiz post, integration, and release IDs only in a private access-controlled record. Use a content hash or idempotency record to detect duplicates; never expose those IDs in public logs. My monitor raises a review alert instead of replying or resubmitting.

7. Treat MCP credentials as write-capable and add review gates

Postiz also exposes an official MCP endpoint. The documented surface currently has 11 tools. It can list integrations and posts, inspect schemas, run provider helpers, modify settings on unpublished posts, create drafts or scheduled/immediate posts, and generate media. It currently cannot read or reply to comments.

Prefer a client that can send the credential in an Authorization: Bearer ... header to https://api.postiz.com/mcp. Putting an API key in the URL is also documented, but URLs are more likely to appear in browser history, proxy logs, screenshots, and diagnostics. Store the secret in the client’s private credential mechanism and rotate it if exposed.

The MCP credential is write-capable, and a prompt is behavioral guidance rather than access control. Use client-side tool approval or a test organization without production integrations. An agent instruction should be explicit:

Before any write call, return the intended account name, UTC time, HTML
content, attachment URLs, provider settings, and unresolved fields.

After explicit approval, call schedulePostTool once with type=draft only.
Do not use type=schedule or type=now, generate media, shorten links, or
modify an existing post.

Unlike CLI -c text, MCP post content must be HTML: wrap each line in <p> and use only the tags permitted by the current tool reference. MCP makes Postiz actions easier to call; it does not remove platform rules, consent requirements, or the need to verify public delivery.

8. Managed versus self-hosted

Choose managed Postiz when your scarce resource is operational attention. Choose self-hosting when you genuinely need infrastructure control and can maintain the full dependency set, storage, TLS/reverse proxy, backups, upgrades, OAuth credentials, and provider callbacks.

For self-hosting, start from the current official Docker Compose repository and migration notes. Pin a reviewed release instead of assuming latest is reproducible, replace every example secret, keep databases and upload storage private, and test MCP streaming through the reverse proxy. A self-hosted deployment still depends on the external platforms’ APIs and policies.

9. A repeatable review-first checklist

  1. Verify authentication without sharing its output.
  2. List integrations and privately select the exact destination.
  3. Fetch that integration’s live settings and tools.
  4. Write provider-specific copy and verify links.
  5. Upload and inspect every media asset before attaching it.
  6. Create a draft with an explicit UTC timestamp.
  7. Review the stored draft and any available UI preview.
  8. Schedule or publish once.
  9. Verify the exact public release before recording delivery.
  10. Treat replies as review alerts, analytics as signals, and only received money as revenue.

This loop is slower than blind cross-posting, but it is fast enough for a small brand and much easier to audit.

Commercial and affiliate boundary

This article currently uses only ordinary, untracked links and earns no Postiz affiliate commission. You can visit the plain Postiz website or the open-source repository without referral tracking.

If a tracked link is added later, it must follow a useful standalone guide, appear beside a clear disclosure, preserve an equally visible plain destination, and remain disabled until the application, exact program terms, attribution, reversals, payout route, and issued URL are privately verified. No affiliate link belongs in an automated community reply.

Primary sources

Leave a Reply