Skip to main content
The bellows CLI queues tasks, waits on them, follows up and answers questions from your terminal or from CI. It talks to the Bellows server over HTTP.

​
Requirements

  • Node.js 22 or newer.
  • A Bellows server URL (Bellows Cloud or your own).
  • A personal access token (fat_...) for that server.

​
Install

The CLI is published on npm as @bellows-ai/bellows-cli.
Terminal
bellows --version and bellows help do not read any configuration, so they work before you sign in.

​
Sign in

The CLI has no login command. You give it a server URL and a token.
1

Mint a personal access token

In the web app, open your account page (user menu, Account) and find Personal access tokens. Create a token. It is shown once, so copy it now. A personal token acts as you until you revoke it or your membership ends.
2

Save the URL and token

Terminal
3

Check it works

Terminal
It prints each setting and where the value came from, the server’s version, and who the token acts as.
The CLI refuses a settings file that holds a token and is readable by anyone but you. Run chmod 600 ~/.bellows/settings.json. Never pass the token as a command-line argument.

​
Bellows Cloud or self-hosted

Set url to the base URL of your server. There is no default URL, so a missing one is an error (exit code 2). The URL must be http or https and must not contain credentials.
  • Bellows Cloud: https://bellows.cloud.
  • Self-hosted: your own server’s base URL. A server running with authentication off (AUTH_MODE=none) needs no token. Leave token out.

​
Settings

Settings come from environment variables first, then the settings file. A set variable wins over the file key. A blank value counts as unset. The file must be a JSON object with only these four keys. To read a different file, add --config <path> to any command. That file must exist. With no settings file, the CLI reads the environment alone.

​
Use it in CI

Store the token in your scheduler’s secret store and pass it as FACTORY_TOKEN.
Terminal

​
Token types

​
Next

Command reference

Every command and flag, with examples.

Run tasks

What happens after you create a task.