posterly CLI

Command line access to the posterly API.

Quick start

Run the CLI without installing anything globally:

npx @posterly/cli@latest auth:login
npx @posterly/cli@latest doctor --pretty
npx @posterly/cli@latest whoami --pretty

npx downloads and runs the CLI for that command. It does not leave a permanent posterly binary on your shell PATH, so keep using npx @posterly/cli@latest for each command unless you install the CLI globally.

Optional global install:

npm i -g @posterly/cli@latest
posterly auth:login
posterly doctor --pretty
posterly whoami --pretty

If global install fails with EACCES: permission denied, mkdir '/usr/local/lib/node_modules/@posterly', your npm global folder is not writable by your user. Use the npx commands above, or fix your npm setup with a user-owned Node install such as nvm.

Running npm i @posterly/cli without -g installs the package into the current folder. In that case posterly will only be available as ./node_modules/.bin/posterly from that folder, not as a global terminal command.

Examples

posterly auth:login
posterly auth:key
posterly doctor --pretty
posterly whoami --pretty
posterly accounts:list --pretty
posterly accounts:disconnect 123 --confirm --pretty
posterly platforms:schema --platform instagram --pretty
posterly oauth:clients --pretty
posterly oauth:create-client --client-name "Agency approval app" --redirect-uri https://agency.example.com/oauth/callback --scopes accounts:read,posts:read,posts:write --pretty
posterly oauth:update-client poc_abc123 --client-name "Agency approval app v2" --confirm --pretty
posterly version
posterly ai:captions --platforms instagram,linkedin --brief "Announcing our summer sale" --tone playful --count 3 --pretty
posterly ai:captions --platforms twitter --mode adapt --source-caption "Long LinkedIn post text" --source-platform linkedin --pretty
posterly ai:image "A minimal flat-lay of a desk with coffee" --aspect-ratio 1:1 --style photographic --pretty
posterly ai:video-options --pretty
posterly ai:video-function google_veo estimate_cost --params '{"duration_seconds":8,"resolution":"720p","output":"vertical"}' --pretty
posterly posts:create --account-id 123 --caption "Launching soon" --scheduled-at 2026-06-01T09:00:00Z
posterly posts:status 123 --status paused --confirm --pretty
posterly posts:missing 123 --pretty
posterly posts:release-id 123 --release-id launch-2026-05-16 --group-id campaign-42 --pretty
posterly posts:delete 123 --confirm --pretty
posterly posts:delete-group campaign-42 --confirm --pretty
posterly webhooks:delete wh_123 --confirm --pretty
posterly gbp:reviews --account-id 123 --unanswered --pretty
posterly gbp:review-link 123 --pretty
posterly gbp:audit 123 --pretty
posterly gbp:media --account-id 123 --pretty
posterly gbp:add-media --account-id 123 --source-url https://cdn.example.com/front.jpg --category COVER --confirm --pretty
posterly gbp:delete-media --account-id 123 --media-name accounts/123/locations/456/media/abc --confirm --pretty
posterly gbp:suggest-reply --account-id 123 --star-rating 5 --review-text "Great service" --pretty
posterly gbp:reply --account-id 123 --review-name accounts/123/locations/456/reviews/abc --comment "Thanks Alex. Glad we could help." --confirm --pretty

The CLI outputs JSON by default so it can be piped into jq or other tools. Use --pretty for formatted output. --human is accepted as an alias for --pretty for older examples.

Use posterly doctor --pretty to check Node version, the configured API origin, whether an API key is present, whether the key works against /api/v1/whoami, and whether a newer @posterly/cli package is published. Add --no-npm to skip the npm registry check in locked-down environments.

Authentication:

• Prefer posterly auth:login for browser-based OAuth.
• Use posterly auth:key with no argument to paste an API key into a hidden prompt.
• For non-interactive setup, pipe the key on stdin: printf '%s\n' "$POSTERLY_API_KEY" | posterly auth:key.
• POSTERLY_API_KEY can be used directly without saving local config.

--api-key is still supported for automation, but avoid passing live keys as command-line arguments in interactive shells because argv can be stored in shell history or exposed through local process listings.

Set --url or POSTERLY_URL to point at a non-production posterly deployment. The CLI refuses to send API keys to non-local http:// URLs by default. Use https://, http://localhost for local development, or --allow-insecure-url only for a trusted private development endpoint.