Command reference

postqueen 2.0.28 has 17 commands. Every one takes -h, --help for its own flags and examples, and -v, --version prints the installed version.

postqueen <command> [options]
postqueen posts:create --help

postqueen auth:login

The CLI opens PostQueen’s sign-in page in your browser. A workspace Admin or Super Admin approves it, and the CLI saves the token and the API address in ~/.postqueen/credentials.json. The token never shows up in the terminal. The CLI then appears under Connections > Approved Apps as PostQueen CLI. Each sign-in adds its own entry, and revoking the entry is what cuts the token off: postqueen auth:logout only deletes the saved login on this computer. The steps it takes are under key and login.

The key

On a machine with no browser, the CLI reads your workspace API key from POSTQUEEN_API_KEY instead. A workspace Admin or Super Admin copies it from Connections > API Keys.

export POSTQUEEN_API_KEY=your_api_key

An OAuth access token that starts with pos_ works in POSTQUEEN_API_KEY too. The CLI also reads two addresses:

Variable	On PostQueen Cloud	On your own server
`POSTQUEEN_API_URL`	Leave it unset. The CLI then calls `https://api.postqueen.ai`	Your backend’s address, the one the web app calls, without `/public/v1`. For example `https://postqueen.example.com/api`
`POSTQUEEN_AUTH_SERVER`	Leave it unset	Only for a device sign-in server you run yourself: see `auth:login` below

A login saved in ~/.postqueen/credentials.json takes priority over both POSTQUEEN_API_KEY and POSTQUEEN_API_URL: the CLI then uses the token and the address in that file, and ignores the variables. postqueen auth:logout removes the file.

Posts

Command	Flags	What it does
`posts:create`	See the table below	Creates a post on one or more channels: scheduled by default, or a draft
`posts:list`	`--startDate`, `--endDate` (ISO 8601), `--customer <id>`	Lists posts between two dates. Default: 30 days back to 30 days ahead
`posts:delete <id>`		Deletes the post and its comments or thread items on that channel, and stops it from going out. Other channels’ posts stay
`posts:status <id>`	`-s, --status draft\|schedule` (required)	Moves a post between draft and scheduled, keeping its date. A draft whose date has already passed publishes at once when you schedule it. Refused for a published or failed post
`posts:settings <id>`	`--settings <json>` (required)	Changes the network settings of a draft or of a scheduled post whose time has not passed. Only the keys you pass change. If you copy settings from `posts:list`, leave out `__type`
`posts:missing <id>`		For a published post whose network ID is missing, lists the channel’s recent posts. TikTok only; other networks answer `[]`
`posts:connect <id>`	`--release-id <id>` (required)	Connects the post to its published copy, so its analytics work

posts:create flags

Flag	Default	What it does
`-c, --content`		The text. Repeat it: the first is the post, each one after it a comment or thread item. Required unless you use `--json`. Text that starts with `-`, such as `-c "-5% off today"`, is taken as text
`-s, --date`		The publish time in ISO 8601, such as `2026-10-01T09:00:00Z`. Required unless you use `--json`. A time that has already passed publishes at once
`-i, --integrations`		Channel IDs from `integrations:list`, separated by commas. Required unless you use `--json`. An empty ID, such as the one after a trailing comma, is refused before anything is sent
`-m, --media`		Media paths from `postqueen upload`, separated by commas, for the `-c` in the same position. Repeat it along with `-c`, with `-m ""` for an item that has no media
`-t, --type`	`schedule`	`schedule` or `draft`
`-d, --delay`	`0`	Minutes to wait between the items of a thread or comments
`--settings`		The network’s settings as a JSON string. The same object goes to every channel in `-i`
`-j, --json`		A file with the whole request body. The other flags are then ignored
`--shortLink`	`true`	Lets PostQueen swap links for short links. PostQueen has no link shortener set up today, so links stay as written either way. `--no-shortLink` keeps them as written

# A scheduled Bluesky post
postqueen posts:create -c "Open on Sunday this week." -s "2026-10-01T09:00:00Z" -i "bluesky-id"

# A Bluesky thread, five minutes between the parts
postqueen posts:create -c "Part one." -c "Part two." -d 5 -s "2026-10-01T09:00:00Z" -i "bluesky-id"

# A WordPress draft with its required settings
postqueen posts:create -c "<p>Every dish now comes in a smaller size.</p>" -t draft \
  -s "2026-10-02T08:00:00Z" --settings '{"title":"Our spring menu","type":"posts"}' -i "wordpress-id"

The --json file format is in posts and channels, and the settings each network needs are in examples by network.

Channels

Command	Flags	What it does
`integrations:list`	`--group <customer-id>`	Lists your connected channels with `id`, `name`, `identifier` (the network), `picture`, `disabled`, `profile` and `customer`
`integrations:groups`		Lists your customers as `id` and `name`
`integrations:settings <id>`		A channel’s `rules`, `maxLength`, `settings` schema and helper `tools`, in an `output` object
`integrations:trigger <id> <method>`	`-d, --data <json>`	Runs one of the channel’s helper tools, such as `postTypes` on WordPress, and returns its `output`

Media and analytics

Command	Flags	What it does
`upload <file>`		Uploads a file from your disk and returns its `id`, `path` and `status`. A video starts as `processing`: see upload media
`analytics:platform <id>`	`-d, --date <days>` (default `7`)	A channel’s numbers per day, with the change over the window
`analytics:post <id>`	`-d, --date <days>` (default `7`)	One published post’s numbers, or `{"missing": true}`

Two letters mean different things in different commands. -s is --date on posts:create and --status on posts:status. -d is minutes (--delay) on posts:create, days (--date) on the analytics commands, and JSON input (--data) on integrations:trigger.

Command	Flags	What it does	Exit code
`auth:status`		Shows which credentials the CLI uses and checks them against the API	`0` when they work. `1` when none are set, when the API refuses them, or when it could not be reached
`auth:login`	`--no-browser`, `--auth-server <url>`	Signs you in through the browser and saves a token. `--no-browser` prints the link without opening it: see below	`0` once you approve. `1` when the sign-in is refused, times out after 10 minutes, or the server offers no browser sign-in
`auth:logout`		Removes a login saved in `~/.postqueen/credentials.json`, which would otherwise take priority over the key. It does not revoke the login in PostQueen	`0`, also when there was nothing to remove

How auth:login signs in

auth:login signs in the way MCP clients such as Claude Code and Cursor do:

It reads the sign-in addresses from <API>/.well-known/oauth-authorization-server/mcp-oauth-dynamic.
It registers itself as PostQueen CLI, with a callback on 127.0.0.1 at a free port.
It opens the approval page with a PKCE challenge, prints the same link, and waits up to 10 minutes.
Your browser returns to the callback. The CLI checks that the reply belongs to its own sign-in, trades the code for a token, and saves the token, the API address and the workspace ID in ~/.postqueen/credentials.json.

<API> is POSTQUEEN_API_URL, or https://api.postqueen.ai when it is unset. Because the browser returns to 127.0.0.1, the link only works in a browser on the same computer as the CLI. A backend without these routes, such as an old self-hosted version, stops it with ❌ <API> does not offer browser sign-in (HTTP 404). Use the API key there. Every way it can fail (the server offers no sign-in, a reply that does not belong to the sign-in, a refused approval, a timeout) prints a line starting with ❌ to stderr and exits 1. With --auth-server <url>, or with POSTQUEEN_AUTH_SERVER set, auth:login starts a device sign-in on that server instead: it asks <url>/device/code for a code, opens your browser, then asks <url>/device/token every few seconds until you approve. PostQueen runs no such server. It is only for one you run yourself, such as the one in the CLI repository’s server/ folder.

What each command prints

Most commands print one status line, then the JSON result. Drop the first line with tail -n +2 before you parse it.

Command	First line
`posts:create`	`✅ Post created successfully!`
`posts:list`	`📋 Posts:`
`posts:status`	`✅ Post <id> status changed to <status>`
`posts:settings`	`✅ Post <id> settings updated`
`posts:connect`	`✅ Post <id> connected to release <release-id>`
`integrations:list`	`🔌 Connected Integrations:`
`integrations:groups`	`👥 Groups (Customers):`
`integrations:settings`	`⚙️ Settings for integration: <id>`
`integrations:trigger`	`🔧 Tool result for <method>:`
`upload`	`✅ File uploaded successfully!`
`analytics:platform`	`📊 Analytics for integration: <id>`
`analytics:post`	`📊 Analytics for post: <id>`

posts:missing prints JSON with no status line. posts:delete prints only ✅ Post <id> deleted successfully!. auth:status and auth:logout print plain text, and auth:login prints one ❌ line on stderr.

When a command fails

A command that fails exits 1 and prints its message to stderr. Only auth:status prints its result on stdout, even when it fails. What you see depends on where the command stopped:

Where it stopped	What you see
The API refused the request, or could not be reached	One line, such as `❌ Failed to create post: Request failed: API Error (400): ...`
A command name is misspelled	`❌ Unknown command: post:create. Run "postqueen --help" for usage.`
A flag name is misspelled	`❌ Unknown argument: startdate. Run "postqueen posts:list --help" for usage.` Nothing is sent
A flag that takes one value was given twice	`❌ --integrations was given more than once, but takes one value. Run "postqueen posts:create --help" for usage.` Only `-c` and `-m` repeat
A required flag or ID is missing, or a value is not one the flag takes	One line with the reason, such as `❌ Either --content or --json is required. Run "postqueen posts:create --help" for usage.`
`-i` has an empty ID, such as `-i "int-1,"`	`❌ Empty integration ID in --integrations "int-1,"`, then two lines on using `-i` and `integrations:list`. Nothing is sent

Flag names are case-sensitive: --startDate and --start-date both work, --startdate is an unknown argument. Text that starts with - is text: -c "-5% off today" and -c "- a smaller size" post as written.

The API route behind each command

The CLI sends your key in the Authorization header exactly as it is, with nothing in front of it, to these routes of the API:

Command	Route
`posts:create`	`POST /public/v1/posts`
`posts:list`	`GET /public/v1/posts`
`posts:delete`	`DELETE /public/v1/posts/{id}`
`posts:status`	`PUT /public/v1/posts/{id}/status`
`posts:settings`	`PUT /public/v1/posts/{id}/settings`
`posts:missing`	`GET /public/v1/posts/{id}/missing`
`posts:connect`	`PUT /public/v1/posts/{id}/release-id`
`integrations:list`, `auth:status`	`GET /public/v1/integrations`
`integrations:groups`	`GET /public/v1/groups`
`integrations:settings`	`GET /public/v1/integration-settings/{id}`
`integrations:trigger`	`POST /public/v1/integration-trigger/{id}`
`upload`	`POST /public/v1/upload`
`analytics:platform`	`GET /public/v1/analytics/{integration}`
`analytics:post`	`GET /public/v1/analytics/post/{postId}`

auth:login calls none of these. It calls the sign-in routes above, or only the server you give it with --auth-server. A workspace can run posts:create 30 times an hour, shared with every other script and app that uses its API, and a run the API refuses with 400 during validation, such as a missing setting, does not count. upload has its own allowance of 300 an hour. One posts:create can carry many channels, so list several IDs in -i rather than running it once per channel. The limits are on limits and errors.

Scripts and scheduled jobs

Give the job the key

A scheduled job does not read your shell profile, so an export in ~/.zshrc never reaches it. Set POSTQUEEN_API_KEY in the job’s own environment. Without it the command stops with ❌ Error: No authentication found. on stderr, so send stderr to your log too (2>&1).

Stop early on a bad key

auth:status exits 1 when no key is set or the API refuses it, so it works as the first line of the job:

postqueen auth:status > /dev/null || exit 1

Parse only the JSON

Drop the status line with tail -n +2, and let set -euo pipefail stop the script when a command fails.

release-post.sh

#!/usr/bin/env bash
set -euo pipefail

postqueen integrations:list > /dev/null || exit 1

IMG=$(postqueen upload ./release.png | tail -n +2 | jq -r '.path')
DATE=$(date -u -d "+1 hour" +"%Y-%m-%dT%H:%M:%SZ")   # on macOS: date -u -v+1H +"%Y-%m-%dT%H:%M:%SZ"

postqueen posts:create \
  -c "Version $(git describe --tags) is live." \
  -m "$IMG" \
  -s "$DATE" \
  -i "bluesky-id"

crontab

POSTQUEEN_API_KEY=your_api_key
0 9 * * 1 /opt/scripts/release-post.sh >> /var/log/postqueen.log 2>&1

Start here

Assistants and bots

Coding agents

Editors and more

MCP reference

CLI reference

Troubleshooting

The key

Posts

posts:create flags

Channels

Media and analytics

How auth:login signs in

What each command prints

When a command fails

The API route behind each command

Scripts and scheduled jobs

Next steps

Posts and channels

Troubleshooting agents

​Sign in

​The key

​Posts

​posts:create flags

​Channels

​Media and analytics

​Key and login

​How auth:login signs in

​What each command prints

​When a command fails

​The API route behind each command

​Scripts and scheduled jobs

​Next steps

Posts and channels

Troubleshooting agents

Sign in

The key

Posts

posts:create flags

Channels

Media and analytics

Key and login

How auth:login signs in

What each command prints

When a command fails

The API route behind each command

Scripts and scheduled jobs

Next steps