Skip to content
BrainyShorts Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

CLI

The brainy command wraps the REST API for shell scripts, cron jobs, and coding agents.

brainy is a thin client for the REST API. Every command accepts --json for machine-readable output.

The package is brainy-shorts on npm and needs Node 18 or newer. Every command maps to one REST endpoint, so anything the CLI can’t do is still available through the REST API or the MCP server.

Configure

npm install -g brainy-shorts
brainy config --api-key ba_sk_...

For unattended runners, prefer environment variables:

export BRAINY_API_KEY="ba_sk_..."
export BRAINY_API_URL="https://www.brainyshorts.com"   # optional, this is the default

The key comes from the flag, then BRAINY_API_KEY, then ~/.brainy/config.json. The host comes from BRAINY_API_URL, then the config file, then https://www.brainyshorts.com. Requests go to <host>/api/cli/... with Authorization: Bearer <key>.

Accounts

brainy accounts --json

Posts

post create makes a draft unless you pass --publish or a schedule. Every post needs media, so -m is required (except with --from-json). The CLI has no upload command: pass a URL you already have, or upload through the REST API first. TikTok only pulls from storage.brainyshorts.com.

# Draft
brainy post create -c "caption" -p tiktok -a <account-id> \
  -m "https://storage.brainyshorts.com/video.mp4"

# Scheduled
brainy post create -c "caption" -p tiktok -a <account-id> \
  -m "https://storage.brainyshorts.com/video.mp4" \
  -s "2026-10-01T10:00:00Z"

# Publish now
brainy post create -c "caption" -p tiktok -a <account-id> \
  -m "https://storage.brainyshorts.com/video.mp4" --publish

# Pick the cover: a frame (TikTok, Instagram Reels) and an image (Instagram Reels, YouTube)
brainy post create -c "caption" -i <account-id-1>,<account-id-2> \
  -m "https://storage.brainyshorts.com/video.mp4" \
  --cover-ms 1500 --cover-url "https://storage.brainyshorts.com/cover.jpg" --publish

# Several accounts at once
brainy post create -c "caption" -i <account-id-1>,<account-id-2> \
  -m "https://storage.brainyshorts.com/video.mp4"

# A photo carousel: a JSON array or a comma-separated list
brainy post create -c "caption" -p instagram -a <account-id> \
  -m '["https://storage.brainyshorts.com/1.png","https://storage.brainyshorts.com/2.png"]'

# From a JSON file
brainy post create --from-json post.json

brainy post list -s scheduled -p tiktok --json
brainy post update <id> -c "new caption"
brainy post update <id> -s "2026-10-02T10:00:00Z"
brainy post update <id> --unschedule
brainy post reschedule <id> "2026-10-01T14:00:00Z"
brainy post delete <delivery-id>

post list prints one row per platform delivery: id is the delivery id and post_id is the parent post. post update accepts either. Every still-scheduled delivery under the parent is updated together. post delete takes a delivery id only.

A post.json file is the same body as POST /posts:

{
  "title": "Launch teaser",
  "caption": "Post caption text",
  "media_type": "video",
  "media_urls": ["https://storage.brainyshorts.com/video.mp4"],
  "targets": [
    { "social_account_id": "<tiktok-account-id>", "platform": "tiktok" },
    { "social_account_id": "<instagram-account-id>", "platform": "instagram" }
  ],
  "action": "schedule",
  "scheduled_at": "2026-10-01T10:00:00Z"
}

media_urls must be a JSON array, not a comma-separated string. Leave out action for a draft (a file with scheduled_at is scheduled). YouTube targets publish now or on a schedule from an MP4 uploaded to Brainy Shorts (reserve the upload, PUT the file, complete it, then use its public_url), up to 200 MiB. They upload as public unless settings.privacy_status is private or unlisted.

Bulk scheduling

brainy post bulk --from-json batch.json --json
brainy post bulk-status <batch-id> --offset 0 --limit 100 --json
brainy post bulk-update --from-json updates.json --json

See Bulk scheduling for the batch format and idempotency rules.

Schedules

brainy schedule list -p youtube
brainy schedule cancel <id>      # reverts the post to a draft

Analytics

brainy analytics overview --json
brainy analytics overview -a <account-id>
brainy analytics overview -p x
brainy analytics post <post-id>

Totals cover only the posts returned (at most --limit, max 100), not the whole account. <post-id> is the post_id shown by analytics overview, which is not the id of a scheduled post. See Analytics.

Runner commands

For scheduled runs:

brainy automations list --json
brainy agent claim --json
brainy agent renew <run-id> --claim-token <token> --lease-seconds 900 --json
brainy agent complete <run-id> --claim-token <token> --caption "..." --media "https://..." --json
brainy agent complete <run-id> --claim-token <token> --caption "..." --slides ./slides.json --json
brainy agent complete <run-id> --from-json ./result.json --json
brainy agent skip <run-id> --claim-token <token> --code NO_QUALIFYING_STORY --reason "..." --json
brainy agent fail <run-id> --claim-token <token> --error "Source image download failed" --json

Was this page helpful?