> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bellows.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Install and sign in

> Install the bellows CLI, point it at your Bellows server with a personal token, and check that it works.

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`.

```bash Terminal theme={null}
npm install -g @bellows-ai/bellows-cli
bellows --version
```

`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**

```bash Terminal theme={null}
mkdir -p ~/.bellows
cat > ~/.bellows/settings.json <<'JSON'
{
  "url": "https://bellows.cloud",
  "token": "fat_..."
}
JSON
chmod 600 ~/.bellows/settings.json
```

**3. Check it works**

```bash Terminal theme={null}
bellows auth status
```

It prints each setting and where the value came from, the server's version, and who the token acts as.

> [!WARNING]
>
> 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.

| Environment variable | File key | Default | Meaning |
| - | - | - | - |
| `FACTORY_URL` | `url` | none (required) | The server's base URL. |
| `FACTORY_TOKEN` | `token` | none | Personal access token (`fat_...`). |
| `FACTORY_REQUEST_TIMEOUT_S` | `requestTimeoutS` | `30` | Deadline for one request, 1 to 3600 seconds. |
| `FACTORY_READ_RETRIES` | `readRetries` | `3` | Retries of a failed read or keyed write, 0 to 10. `0` turns retries off. Writes without an idempotency key are never retried. |

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`.

```bash Terminal theme={null}
export FACTORY_URL="https://bellows.cloud"
export FACTORY_TOKEN="$BELLOWS_TOKEN"   # from your secret store
bellows auth status
```

## Token types

| Token | Prefix | What it can do |
| - | - | - |
| Personal access token | `fat_` | Acts as you. Can create tasks and do everything the commands below do. |
| Organization access token | `oat_` | Read-only. It cannot queue a task. Admins mint it for automation that should outlive any member. |

## Next

> [card] [Command reference](https://docs.bellows.cloud/cli/commands.md)
>
> Every command and flag, with examples.

> [card] [Run tasks](https://docs.bellows.cloud/guides/run-tasks.md)
>
> What happens after you create a task.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.