Developer docs · CLI

BeyondBeings from your terminal

bb is the BeyondBeings command-line tool. Generate editorial graphics and carousels, brainstorm ideas, and write headlines — then pipe the results into your own scripts and CI.

It shares one core and one API key with the MCP server.

Install Connect an agent instead

Install & log in

Requires Node.js 18.17+. Run it with npx (no install) or install globally for a bb command on your PATH.

Run without installing

npx -y --package=@beyondbeings/mcp bb --help

Or install globally

npm install -g @beyondbeings/mcp
bb --help

Then save your key (get one at Settings → API Keys):

bb login --key bb_live_your_key_here
# verifies the key and saves it to ~/.beyondbeings/config.json (mode 0600)

First generation

bb generate "a 1500-year-old company that still operates today" \
  --aspect 4:5 --mode editorial -o test.jpg

# ✓ THIS COMPANY IS 1500 YEARS OLD
#   url: https://.../generated-images/....jpg
# test.jpg   ← saved file path (stdout)

Command reference

Create

bb generate <prompt>

Generate one graphic. BeyondBeings writes the full image prompt + title for you. Downloads the image and prints the path; the permanent URL is shown too.

bash

bb generate "neon city skyline at dusk" \
  --aspect 16:9 --title "THE CITY THAT NEVER SLEEPS" -o thumb.jpg

bb carousel

Generate a multi-slide carousel. Repeat --slide for each slide; all share one carousel id.

bash

bb carousel --topic "5 ancient companies still running" \
  -s "hook: the oldest company on earth" \
  -s "Kongo Gumi, founded 578 AD" \
  -s "follow for more" --aspect 4:5 -o ./out

bb recomposite <id>

Re-bake a graphic's headline (text/color/font/position) without re-running the model.

bash

bb recomposite gen_abc123 --text "A BOLDER HEADLINE" --fill white

Think & write

bb chat <message>

Ask the BeyondBeings strategist for ideas, carousel plans, captions, or refinements — house voice, live web grounding.

bash

bb chat "Give me 5 carousel ideas about AI in healthcare" --mode editorial

bb ideas

Print today's trending content ideas.

bash

bb ideas

bb headlines <text>

Generate 3 headline alternatives for a headline (or a topic with --topic).

bash

bb headlines "This Company Is 1500 Years Old" --mode editorial

Account & discovery

bb quota

Show today's remaining generation budget.

bash

bb quota

bb history

List your recent generations.

bash

bb history --limit 10

bb models

List image models (filter with --availability free|paid).

bash

bb models --availability free

bb modes

List modes, aspect ratios, and industries.

bash

bb modes

Account setup

bb login

Save and verify your API key (opens the key page if you don't pass --key).

bash

bb login --key bb_live_your_key_here

bb keys

Open the web page to create/revoke keys.

bash

bb keys

bb logout

Remove the saved key.

bash

bb logout

bb mcp

Run the stdio MCP server (same as the beyondbeings-mcp binary).

bash

bb mcp

Common flags & config

--aspect 16:9 | 1:1 | 4:5

Output shape (default 4:5).

--mode general | editorial

Voice + style. Editorial stays factually faithful.

--model <slug>

Pick an image model (see bb models). Paid tiers.

--title <text> / --include-title

Composite a headline onto the image.

--ref <file>

Attach a reference image (repeatable; paid/signed-in).

-o, --out <path>

Where to save the image.

--json

Print the raw JSON response (great for scripts).

-k --api-key / -u --url

Override the key or API host per command.

Config is resolved in order:

Key: --api-key → BEYONDBEINGS_API_KEY → ~/.beyondbeings/config.json
Host: BEYONDBEINGS_API_URL → config → https://beyondbeings.com

Scripting & CI

Human status goes to stderr; machine output (JSON, saved paths) goes to stdout — so piping and --json stay clean. Set the key via env in CI rather than bb login.

Generate in CI and grab the URL

export BEYONDBEINGS_API_KEY="bb_live_..."   # from your secrets store

# Get the permanent URL as JSON and extract it with jq
URL=$(bb generate "weekly product update banner" --aspect 16:9 --json \
  | jq -r '.imageUrl')

echo "Posting $URL ..."
# ...then hand $URL to your Slack/Discord webhook step

Brainstorm → generate, end to end

# 1) ask the strategist for an idea (prints prose you can read/parse)
bb chat "one punchy idea about ocean exploration, with a headline" --json

# 2) generate it
bb generate "a lone submersible descending into the deep, bioluminescent life" \
  --title "THE DEEPEST PLACE HUMANS HAVE EVER REACHED" --aspect 4:5 -o deep.jpg

FAQ

Questions? Email info@beyondbeings.com.

Where do I get an API key?

Create a free account, then open Settings → API Keys (beyondbeings.com/my-profile?tab=api-keys) and click Create key. The key starts with bb_live_ and is shown once.

Does the CLI show the image in my terminal?

Terminals can't render images. bb downloads the image to a file (use -o) and prints both the saved path and a permanent public URL. Use --json to get just the URL.

How long does a generation take?

Usually 30–120 seconds for a single graphic; carousels run each slide in turn. The CLI shows an elapsed-time spinner while it works.

Can I use it without logging in?

bb ideas, bb headlines, bb models, and bb modes work without a key. Everything that generates or reads your account needs one.

Ship graphics from the command line

Grab a key and run your first bb generate in under a minute.

Get your API key