CLI

Use the PostMCP CLI for terminal, CI, cron, and agent workflows. Every command accepts --json so callers can parse stdout without scraping prose.

Set these environment variables for authenticated commands:

export POSTMCP_API_BASE_URL=https://api.postmcp.dev
export POSTMCP_API_KEY=pmcp_key_...
export POSTMCP_WORKSPACE_ID=wrk_...

POSTMCP_API_BASE_URL=https://api.postmcp.dev is the production API endpoint. Override it only for local development, staging, or preview environments.

Install And Auth

postmcp auth login --json
postmcp auth token --name automation --scopes posts.read,posts.schedule,usage.read --json
postmcp auth revoke --api-key-id key_123 --json
postmcp mcp install --client claude --json
postmcp openclaw install --json

After creating an automation token, keep POSTMCP_API_KEY, POSTMCP_WORKSPACE_ID, and POSTMCP_API_BASE_URL in the environment used by CI, cron, MCP clients, or local agents.

Accounts

export POSTMCP_BLUESKY_IDENTIFIER=postmcp.example.com
export POSTMCP_BLUESKY_APP_PASSWORD=bsky-app-password
postmcp accounts connect --platform bluesky --json
postmcp accounts connect --platform bluesky --redirect-uri https://app.postmcp.dev/accounts/oauth/callback --json
postmcp accounts list --json
postmcp accounts status --account acct_123 --json

For Bluesky, prefer the environment-variable form so the app password is not printed in terminal history. --identifier and --app-password are also available for local shells where history is disabled.

Agents

postmcp agents create --name drafter-bot --scopes posts.draft,media.upload --mode draft --owner-user-id usr_123 --json
postmcp agents list --json
postmcp agents claim pmcp_claim_123 --json
postmcp agents revoke agt_123 --json
postmcp agents rotate-key agt_123 --json

Posts

Post write commands use the same automation flags:

postmcp post create --text "Hello" --to bluesky:acct_123 --dry-run --idempotency-key idem_123 --wait --webhook-url https://example.com/postmcp --json
postmcp post schedule --text "Launch note" --to linkedin:acct_456 --schedule 2026-05-15T14:00:00.000Z --idempotency-key idem_schedule_123 --json
postmcp post draft --text "Draft for review" --to x:acct_789 --json
postmcp post batch --file posts.json --dry-run --idempotency-key batch_123 --json
postmcp post list --date 2026-05-15 --timezone America/Sao_Paulo --platform bluesky --account acct_123 --json
postmcp post status --post-group-id pg_123 --json
postmcp post delete --post-group-id pg_123 --json
postmcp post retry --post-group-id pg_123 --json

Use --sandbox when you need the full scheduling and worker flow without live platform quota or real social posts:

postmcp post create --text "CI smoke test" --to linkedin:acct_sandbox --sandbox --json

Batch files are JSON arrays. Per-item fields can include text, targets, platforms, scheduled_at, media_ids, dry_run, draft, sandbox, wait, webhook_url, auto_fix, and per-target sandbox_behavior.

Media

postmcp media upload --filename launch.png --mime-type image/png --content-base64 iVBORw0KGgo= --sandbox --json

Logs And Usage

postmcp logs --actor-type agent --actor-id agt_123 --json
postmcp logs --format csv
postmcp usage --period-start 2026-05-01T00:00:00.000Z --spend-cap-cents 500 --json
postmcp cost --posts 1000 --x-text 20 --x-url 5 --accounts 3 --json

Common Flags

--json              Print structured JSON output.
--dry-run           Validate and preview supported post writes without creating live posts.
--idempotency-key   Prevent duplicate supported post writes during retries.
--wait              Ask PostMCP to wait for available post status before returning.
--webhook-url       Send post lifecycle events to an agent-controlled endpoint.
--workspace         Override POSTMCP_WORKSPACE_ID.
--account           Filter by or target a connected account.
--platform          Filter by or start OAuth for a platform.
--identifier        Bluesky identifier for app-password account connection.
--app-password      Bluesky app password for account connection.
--sandbox           Run supported writes through sandbox infrastructure.