Skip to main content
IP BotPLATFORM
Docs navigation

CLI (ipbot)

Drive the content pipeline from your terminal, scripts, or CI.

Install

bash
> npx @island-pitch/ip-bot-cli --help     # run on demand
> npm i -g @island-pitch/ip-bot-cli       # or install globally

Authenticate

Humans use Cognito login; agents and CI use an API key.

bash
> # Human (browser PKCE)
> npx @island-pitch/ip-bot-cli auth login
> 
> # Agent / CI
> export IPBOT_APPSYNC_ENDPOINT=https://api.islandpitch.bot/graphql
> export IPBOT_API_KEY=ipbot_live_xxxxxxxxxxxxxxxx
> npx @island-pitch/ip-bot-cli content list --output json --user-id <cognito-sub>

Every command supports --output json for machine consumption. Get keys from Settings → API Keys.

Command groups

ipbot authlogin / logout / whoami / refresh, and agent API keys
ipbot contentcreate, find, get, list, submit, approve, reject, schedule, publish, cancel
ipbot calendarshow, get, and wait for a scheduled publication
ipbot reviewcreate shareable review links, list/revoke shares, add/list comments
ipbot orgcreate orgs, invite/accept, manage members, share accounts, audit
ipbot accountslist connected IG/FB accounts; resolve @handles to IDs
ipbot scheduledebug a schedule by tailing publisher logs
ipbot draftfrom-ticket: turn a Jira ticket into drafts
ipbot systemstatus: publisher / EventBridge / AppSync / OAuth health
ipbot analyticspost: cached metrics for a published post
ipbot campaignsAutoReply campaigns: create, list, get, update, activate/pause/archive, set-steps, set-triggers
ipbot powerslist and run Powers (debits your Winds)
ipbot windsbalance and topup: check or buy Winds

Publish accessibly + the Meta extras

Alt text is a first-class flag — published as Instagram alt_text / Facebook alt_text_custom — alongside the Meta features most tools skip:

bash
> ipbot content create --type social_post --platform instagram \
>   --excerpt "Doors at 8. The crew is ready. 🌊" \
>   --alt-text "Two dancers mid-spin under purple stage lights" \
>   --location-id 213385402 --collaborators dj_kaya
  • --media-alt-texts sets per-carousel-child alt text (paired by index with --media-urls). Alt text is a first-class accessibility field — omit it and alt text is dropped silently. Images only. Heads-up: Instagram crops all carousel children to the first child's aspect ratio.
  • --story publishes as an IG Story instead of a feed post.
  • --cta adds a Facebook call-to-action button (e.g. {"type":"LEARN_MORE",…}).
  • --targeting gates the audience — e.g. 21+ for alcohol/nightlife compliance.
  • ipbot media upload ./photo.jpg turns a local image into a public URL ready for --dest-config; ipbot content reschedule moves a scheduled publication.
  • For agents: stable exit codes — 0 success, 1 unexpected error, 2 operation failed / not found, 3 structured handler failure.

A typical agent flow

bash
> ipbot content create --output json   # → draftId
> ipbot content submit <draftId>
> ipbot content approve <draftId>
> ipbot content schedule <draftId> --at "2026-07-01T15:00:00Z"
> ipbot calendar wait <scheduleId>     # blocks until published

AutoReply campaigns

Always-on Instagram comment/DM automation. Scope triggers by keyword, all-comments, or specific media IDs (--media-ids; omit to trigger on all media — inbound DMs are never media-filtered).

bash
> ipbot campaigns create --name "Reel price funnel" \
>   --trigger-on comments --keywords "price,cost" \
>   --media-ids 17900001234567890 --steps steps.json
> ipbot campaigns activate <campaignId>
  • DM steps triggered by a comment send a private reply — Meta allows exactly one per comment, ever, and only within 7 days of the comment. The engine enforces both (private_reply_already_sent / private_reply_window_expired).
  • Free-form DMs require the user to have messaged the account within the last 24 hours.
  • Rate limits (750 private replies/hr per post/reel, 100 msgs/s) are handled automatically with deferred retries.

Powers & Winds

bash
> ipbot powers list --output json
> ipbot powers run power-image-to-draft --input '{"imageUrl":"https://…"}'
> ipbot winds balance
> ipbot winds topup medium
  • powers/winds require user auth (interactive login or a per-user API key) — they're scoped to you and debit your Winds.
  • Full command reference ships in the CLI README (@island-pitch/ip-bot-cli).
  • The same surface is available to agents via the MCP server.