CLI Manual

FireBreath CLI is the terminal client for FireBreath. It talks to the cloud app over HTTPS with API keys, so users can manage social accounts, posts, inbox, media, and analytics without running MCP.

Quick Start

Create an API key in FireBreath from Settings -> API Keys, then install and authenticate the CLI.

npm install -g firebreath-cli
firebreath auth set-key fb_your_api_key
firebreath whoami

If you are using the repo package before npm publication, install it locally instead.

npm install -g ./packages/cli

If you want to keep the CLI private while testing, build a tarball and install that instead of publishing to npm.

npm run cli:pack-dev
npm install -g ./artifacts/cli/firebreath-cli-<version>.tgz

How It Works

Cloud Client

The CLI defaults to https://firebreath.app and uses your FireBreath API key for every request.

Separate From MCP

CLI and MCP access can be toggled independently per user, so teams can allow one without the other.

Script Friendly

Use --json for machine-readable output in shell scripts, CI jobs, and AI workflows.

Configuration

Saved config defaults to `~/.config/firebreath/config.json` on macOS and Linux.

firebreath auth set-key fb_your_api_key --base-url https://staging.firebreath.app
firebreath auth status
firebreath --base-url https://firebreath.app whoami
firebreath --config ~/.config/firebreath/work.json whoami

Environment variables override saved config when present.

export FIREBREATH_API_KEY=fb_your_api_key
export FIREBREATH_BASE_URL=https://firebreath.app
export FIREBREATH_CONFIG=~/.config/firebreath/config.json

Command Reference

Creative Studio is the canonical runtime surface for CLI project work, firebreath studio ... is the canonical command family, XHS Note is the first available profile, new projects open directly in the freeform workspace, there is no mode picker in the create flow, legacy structured projects remain readable only when reopened, and the package and get commands keep the queue handoff and save/resume context explicit for operators. firebreath carousel ... and firebreath xhs ... remain explicit compatibility aliases.

Auth

Save your API key, inspect config, and verify identity.

firebreath auth set-key <apiKey> [--base-url <url>]
firebreath auth status
firebreath auth clear
firebreath whoami

Accounts

List, inspect, target, refresh, and sync connected social accounts.

firebreath providers list
firebreath accounts list
firebreath accounts get <integrationId>
firebreath accounts select-target <integrationId> --id <targetId> --name <targetName>
firebreath accounts refresh <integrationId>
firebreath accounts sync <integrationId>
firebreath accounts sync-all

Posts

Full post lifecycle with tags, date filtering, history, evergreen, and bulk import.

firebreath posts list [--state <state>] [--tags <t1,t2>] [--from <iso>] [--to <iso>]
firebreath posts get <postId>
firebreath posts create --content <text> --integration <id> [--tag <tag> ...]
firebreath posts update <postId> [--content <text>] [--tag <tag> ...]
firebreath posts publish <postId>
firebreath posts schedule <postId> --scheduled-at <iso>
firebreath posts retry <postId>
firebreath posts approve <postId>
firebreath posts revoke <postId>
firebreath posts delete <postId>
firebreath posts history <postId>
firebreath posts evergreen <postId> [--enable] [--disable] [--interval <days>]
firebreath posts group <groupId>
firebreath posts bulk-import --file <csv-or-json>

Inbox

List, sync, reply to, count, and bulk-manage inbox engagement items.

firebreath inbox list [--platform <provider>]
firebreath inbox sync [--integration <id>]
firebreath inbox reply <itemId> --text <text>
firebreath inbox count
firebreath inbox bulk-mark --action <mark_read|archive> [--ids <id1,id2>]

Media

Upload, manage, and batch-organize media assets.

firebreath media list
firebreath media get <mediaId>
firebreath media upload-file <path>
firebreath media upload-url <url>
firebreath media update <mediaId> [--notes <text>] [--alt-text <text>]
firebreath media delete <mediaId>
firebreath media batches list
firebreath media batches create <name> --media-id <id>
firebreath media batches delete <batchId>

Analytics

Overview, per-post, per-channel, tag-based analytics, best times, and export.

firebreath analytics overview
firebreath analytics post <postId>
firebreath analytics channel <integrationId> [--from <iso>] [--to <iso>]
firebreath analytics tag <tag> [--from <iso>] [--to <iso>] [--integration <id>]
firebreath analytics insights <integrationId> [--days <n>]
firebreath analytics refresh [--integration <id>]
firebreath analytics best-times [--integration <id>]
firebreath analytics export [--from <iso>] [--to <iso>] [--format <csv|pdf>]

AI

Generate platform-optimized captions and repurpose long-form content.

firebreath ai generate --prompt <text> --platform <p> [--tone <tone>]
firebreath ai repurpose --content <text> --platform <p> [--url <url>]

Hashtags

AI hashtag suggestions and saved collection management.

firebreath hashtags suggest --content <text> [--platform <p>]
firebreath hashtags list
firebreath hashtags create --name <name> --tags <t1,t2>
firebreath hashtags delete <collectionId>

Brand Voices

Create and manage brand voice profiles for consistent AI-generated content.

firebreath brand-voices list
firebreath brand-voices create --name <name> [--tone <tone>] [--default]
firebreath brand-voices update <id> [--name <name>] [--tone <tone>]
firebreath brand-voices delete <id>

Creative Studio

Canonical project workflow for Creative Studio. XHS Note is the first supported profile.

firebreath studio list [--profile xhs-note]
firebreath studio create [--profile xhs-note] --name <name>
firebreath studio get <projectId>
firebreath studio update <projectId> --version <n> [--name <name>]
firebreath studio generate outline <projectId> --brief <text>
firebreath studio generate copy <projectId> [--brief <text>]
firebreath studio review <projectId> --action <submit|approve|request-changes>
firebreath studio package <projectId> --integration <id>
firebreath carousel ...   # compatibility alias
firebreath xhs ...   # compatibility alias

Common Workflows

Create and publish a post

firebreath posts create \
  --content "Launching our spring campaign today." \
  --integration int_123 \
  --media ./promo-video.mp4

firebreath posts publish post_123

Tag and filter posts

firebreath posts create \
  --content "Weekly fitness tips." \
  --integration int_123 \
  --tag fitness --tag weekly-tips

firebreath posts list --tags fitness,weekly-tips --from 2026-03-01
firebreath analytics tag fitness --from 2026-03-01

AI-assisted content

firebreath ai generate \
  --prompt "Announce our spring fitness program" \
  --platform instagram --platform facebook \
  --tone professional

firebreath hashtags suggest --content "Spring fitness program" --platform instagram

Work the social inbox

firebreath inbox sync --integration int_123
firebreath inbox list --platform youtube --read false
firebreath inbox reply inbox_123 --text "Thanks for the comment"
firebreath inbox count
firebreath inbox bulk-mark --action mark_read --platform youtube

Evergreen and analytics

firebreath posts evergreen post_123 --enable --interval 30
firebreath analytics export --from 2026-03-01 --format csv --json
firebreath analytics best-times --integration int_123

Creative Studio project flow

firebreath studio list --profile xhs-note
firebreath studio create --profile xhs-note --name "Spring Rehab Tips"
firebreath studio generate outline proj_123 --brief "Hook, proof, CTA"
firebreath studio review proj_123 --action submit
firebreath studio package proj_123 --integration int_123
firebreath studio get proj_123 --json
# Inspect the queue handoff and resume context for the active XHS Note project

# Compatibility aliases
firebreath carousel list --profile xhs-note
firebreath xhs list

Advanced Input

For advanced write flows, use a raw JSON body instead of friendly flags.

firebreath posts create --body @payload.json --json
firebreath posts update post_123 --body '{"content":"Updated from raw JSON"}'

Media references in post commands can be FireBreath media URLs, FireBreath media IDs, or local file paths.

Troubleshooting

401 Unauthorized

  • Make sure the API key starts with fb_.
  • Run firebreath auth status.
  • Confirm the API key still exists in FireBreath.

403 Forbidden

  • Check whether CLI access is disabled for your user.
  • Make sure the API key belongs to the correct workspace.

404 Not Found

  • Verify the post, media, inbox item, or Account ID (integration ID).
  • Remember that IDs are workspace-scoped.

Provider Errors

  • Reconnect expired social accounts from FireBreath.
  • Check the provider guide under /docs/platforms.

Related Docs

API & MCP ReferenceFAQSocial Inbox
Was this page helpful?