Introduction - PostQueen Documentation

The PostQueen CLI puts her one command away in your terminal. Schedule a post to 30+ networks, upload the image that goes with it or pull last week’s numbers, from a shell script, a CI job or an AI agent. Underneath it is the same Public API the SDK and the n8n node run on. The data commands print JSON, so anything that can run a shell command can run your social media.

Installation

npm
pnpm

npm install -g postqueen

pnpm install -g postqueen

Verify the installation:

postqueen --help

Give your AI agent the skill

If an AI assistant will be driving the CLI for you, install the PostQueen skill first. It hands the agent her full command set and the patterns behind it, so it gets the flags right the first time instead of guessing at them:

npx skills add GkhanKINAY/postqueen-agent

Prefer to wire it up by hand? Load the SKILL.md file directly from github.com/GkhanKINAY/postqueen-agent.

Authentication

One key and the CLI is talking to your account. Getting it takes a minute:

Open app.postqueen.ai
Go to Settings > Developers > Public API
Click Reveal and copy your key

Then export it:

export POSTQUEEN_API_KEY=your_api_key_here

Add this to your shell profile (~/.bashrc, ~/.zshrc, etc.) so it persists across sessions.

Keep the key secret: it grants full access to your account, and you can revoke or rotate it any time from the same screen.

Custom API URL (self-hosted)

If you run a self-hosted PostQueen instance, point the CLI at your backend URL, the same value as NEXT_PUBLIC_BACKEND_URL. The CLI appends /public/v1/... to whatever you set, and most single-domain setups serve the backend under /api:

export POSTQUEEN_API_URL=https://postqueen.example.com/api

Running your own auth server? There is an OAuth2 device flow for that instead, and every command works the same either way. Setup guide: Authentication.

Your first post

# 1. List your connected social media accounts
postqueen integrations:list

# 2. Create a scheduled post (-s is the schedule date, required)
postqueen posts:create \
  -c "Hello from the PostQueen CLI!" \
  -s "2026-08-01T09:00:00Z" \
  -i "your-integration-id"

# 3. List your scheduled posts
postqueen posts:list

Repeat -c to turn a post into a thread; each extra -c becomes a reply or comment on the platforms that support it. The -d flag sets the delay between those comments in minutes (default: 0):

# A three-part thread with 5 minutes between replies
postqueen posts:create \
  -c "Thread 1/3" \
  -c "Thread 2/3" \
  -c "Thread 3/3" \
  -d 5 \
  -s "2026-08-01T09:00:00Z" \
  -i "your-integration-id"

What she can do from a shell

Command	Description
`integrations:list`	List connected channels; `--group` filters by group (customer) ID
`integrations:groups`	List all groups (customers)
`integrations:settings <id>`	Get the settings schema for an integration
`integrations:trigger <id> <method>`	Trigger a dynamic tool on an integration; `-d` passes JSON data
`posts:create`	Create a post. Key flags: `-c` content (repeat for a thread), `-s` schedule date (required, ISO 8601), `-i` integration IDs, `-m` media URLs (upload first), `-t` `schedule` or `draft`, `-d` delay between comments in minutes, `--shortLink` (default `true`), `--json` campaign file
`posts:list`	List posts; `--startDate` and `--endDate` narrow the range
`posts:delete <id>`	Delete a post by ID
`posts:status <id>`	Switch a post between draft and schedule with `--status`
`posts:missing <id>`	List available content from the provider for a post with a missing release ID
`posts:connect <id>`	Connect a post to its published content with `--release-id`
`analytics:platform <id>`	Get analytics for a channel; `-d` sets days to look back (default 7)
`analytics:post <id>`	Get analytics for a specific post; `-d` sets days to look back (default 7)
`upload <file>`	Upload a media file and get back the URL to pass to `-m`
`auth:login`	OAuth2 device flow (requires a self-hosted auth server, see Authentication)
`auth:status`	Show current authentication status
`auth:logout`	Remove stored credentials

Full flag-by-flag details: Command Reference.

The data commands print a one-line header and then JSON, which makes the CLI easy to use in scripts and automation pipelines. Drop the header with tail -n +2 before piping into jq.

Anything you can type here, an agent can run for you at six in the morning while you sleep. Why she works so well with agents: Why agents love her.

Next steps

Get your key in place

Where the key lives, and the self-hosted URL shape that trips people up.

Schedule a post

Channels, threads and drafts, in one command.

Every flag

The full reference, including which commands print plain text.

What it cannot do

Thirteen of the API’s twenty-two endpoints, and where the other nine live.

​Installation

​Give your AI agent the skill

​Authentication

​Custom API URL (self-hosted)

​Your first post

​What she can do from a shell

​Next steps

Get your key in place

Schedule a post

Every flag

What it cannot do

Installation

Give your AI agent the skill

Authentication

Custom API URL (self-hosted)

Your first post

What she can do from a shell

Next steps