# PostEverywhere CLI Guide

> Log in, connect all top social platforms, and publish from the terminal with the PostEverywhere CLI (@posteverywhere/cli). Built for developers and AI agents.

**Source:** https://posteverywhere.ai/docs/cli
**Section:** Integrations
**API reference:** https://posteverywhere.ai/docs/api/reference

---

The `@posteverywhere/cli` lets you (or your AI agent) **log in, connect every platform, and publish** entirely from the terminal, no dashboard navigation required.

```bash
npm install -g @posteverywhere/cli      # or: npx @posteverywhere/cli <command>
```

Source: [github.com/posteverywhere/cli](https://github.com/posteverywhere/cli)

## Install the CLI as an agent skill
The CLI ships with a `SKILL.md` that teaches an agent the whole command surface. One command installs it:

```bash
npx skills add posteverywhere/cli
```

That auto-detects your agent (Claude Code, Cursor, Codex and 70+ others). Then just ask:

> *"schedule a post to all my accounts for tomorrow at 9am"*

Claude Code users can instead install it as a plugin, which brings auto-updates:

```bash
claude plugin marketplace add posteverywhere/cli
```

Either way the agent learns to connect accounts, check per-platform limits before composing,
schedule, and read back per-destination results. Every command emits JSON, so it can act on
what just happened rather than guessing.

## Set up the CLI in 90 seconds
```bash
posteverywhere login                 # opens your browser, saves a key to ~/.posteverywhere
posteverywhere connect instagram     # opens the OAuth flow; auto-detects the connected account
posteverywhere accounts              # list connected accounts (+ ids & health)
posteverywhere post -c "Hello 🚀" -a 123,456
```

## How `login` authenticates you
A device-grant flow (RFC 8628, like the GitHub CLI):

1. The CLI calls `POST /v1/auth/device` and prints a short code (e.g. `GUPK-HM3G`) plus a URL.
2. It opens `https://app.posteverywhere.ai/device` in your browser. You confirm the code (you must be signed in).
3. The CLI polls `POST /v1/auth/device/token` until you approve, then receives a scoped API key (`read`, `write`, `ai`) and saves it to `~/.posteverywhere/config.json` (`chmod 600`).

The key is a normal API key: it shows up on the **Developers** page alongside dashboard-generated keys, and you can revoke it there anytime. The plaintext key is shown/saved exactly once and never stored on our servers in plaintext.

## How `connect` links a social account
```bash
posteverywhere connect <platform>
posteverywhere reconnect <accountId>      # refresh an expired account's token
```

- **Browser platforms**: `instagram`, `facebook`, `threads`, `x`, `linkedin`, `tiktok`, `youtube`, `pinterest`. The CLI calls `POST /v1/auth/social-connect/start`, opens the normal OAuth flow in your browser, and **watches for the account** to appear, then resolves automatically. No copy-paste of tokens.
- **Bluesky**: prompts for your handle + an **App Password** (Settings → App Passwords). No browser.
- **Telegram**: prompts for a **bot token** (@BotFather) + your **channel** (add the bot to it as an admin first). No browser.
- **Discord**: prompts for a channel **webhook URL** (Server Settings → Integrations → Webhooks). No browser.

## Every CLI command and what it does
| Command | What it does |
|---|---|
| `login` / `logout` | Device-flow login / remove saved credentials |
| `whoami` | Show the authed account, plan & quota |
| `accounts` | List connected accounts (+ ids & health) |
| `platform-rules [platform]` | Character limits, media constraints & supported features |
| `connect <platform>` | Connect a new account |
| `reconnect <accountId>` | Re-authorize an account whose token expired |
| `account:health <id>` | Detailed health for one account |
| `post -c <text> -a <ids> [-s <iso>] [-m <mediaIds>] [--queue] [--timezone <tz>]` | Publish now (omit `-s`), schedule (`-s` = ISO-8601 UTC), or drop into the next queue slot (`--queue`) |
| `posts [--status x] [--platform y] [--limit n]` | List posts |
| `queue [--preview N]` | Show the next queue slots for your accounts |
| `results <postId>` | Per-platform publish results |
| `retry <postId>` | Retry failed destinations |
| `upload <url>` | Import an image or MP4 video by URL → `media_id` (videos import async, poll until ready) |
| `caption -t <topic> [--platform x] [--tone y]` | AI captions |
| `analytics [--period week\|month\|all]` | Analytics summary |
| `campaigns` | List campaigns |

## Driving the CLI from an AI agent
Every command accepts `--json` (auto-on when output is piped) and emits structured JSON, so Claude, Cursor, and other agents can parse results.

Install the bundled skill with `npx skills add posteverywhere/cli` and the agent learns the
command surface without you explaining it. Two habits are worth encouraging in your own prompts:

- **`accounts` before `post`**: account ids should never be guessed.
- **`platform-rules` before composing for an unfamiliar platform**: the limits range from 300
  characters on Bluesky to 63,206 on Facebook, and TikTok enforces a pixel ceiling server-side.
  One call is cheaper than a rejected publish.

For CI or fully headless agents, skip `login` and set the key directly:

```bash
export POSTEVERYWHERE_API_KEY=pe_live_...   # from the Developers page
posteverywhere accounts --json
```

Prefer MCP? Use the hosted endpoint `https://mcp.posteverywhere.ai/mcp` or `npx -y @posteverywhere/mcp`, see [MCP](/docs/integrations/mcp).

## Fixing common CLI problems
- **"Not logged in"**: run `posteverywhere login`, or set `POSTEVERYWHERE_API_KEY`.
- **`connect` times out**: the browser window must be signed in to the same account your key belongs to. Finish the OAuth there; the CLI resolves within a few seconds.
- **An account "needs reconnect"**: `posteverywhere reconnect <accountId>`.
- **Auth precedence**: `POSTEVERYWHERE_API_KEY` env var wins over the saved `login` key.

**Related:** [the Node.js SDK](/docs/integrations/sdk) · [API keys and the device login flow](/docs/authentication) · [your first API post](/docs/quick-start) · [how AI agents schedule posts with PostEverywhere](/agents) · [the no-code Zapier route](/docs/integrations/zapier) · [a drop-in agent system prompt](/docs/integrations/agent-system-prompt)