# Command reference

> Every bitsrun command with its options and an example, for deploying models, managing endpoints, keys and uploads, and checking usage.

Source: https://bitsrun.com/docs/cli/commands/
Updated: 2026-11-09

Run `bitsrun --help` for the same list in your terminal. Every command refers to an endpoint by its **name** (when the name is unique) or its **id**. Put names with spaces in quotes, like `"Support chat"`.

Options that work with every command:

| Option | What it does |
|---|---|
| `--json` | Print the API's JSON instead of text, for scripts. See [Scripts and CI](https://bitsrun.com/docs/cli/automation/). |
| `-h`, `--help` | Show the help. |
| `-v`, `--version` | Show the version. |

## Account

### login

Sign in through your browser. See [Install and sign in](https://bitsrun.com/docs/cli/#sign-in).

| Option | What it does |
|---|---|
| `--no-browser` | Print a link and ask for the code instead of opening a browser (also the default over SSH). |

```text
$ bitsrun login
Opening your browser to sign in. If it does not open, visit:

  https://bitsrun.com/cli/?...

Waiting for you to allow access (Ctrl+C to stop)...
Signed in as MacBook Pro. This session lasts until 2027-02-07.
Next: bitsrun deploy qwen3:8b
```

### logout

Sign out this computer. Its session stops working at once.

```text
$ bitsrun logout
Signed out. This computer no longer has access to your account.
```

### whoami

Show your plan, balance, endpoint count and model storage. `bitsrun account` does the same.

```text
$ bitsrun whoami
Account    01k8y4000d3m00000000000001
Plan       Pro
Balance    $37.42
Endpoints  3 of 10
Storage    0.0 GB of 200.0 GB free (then $0.05 per GB a month)
```

When your balance is $0 or less, it also says that endpoints answer with a payment-required error and links to the billing page.

### upgrade

Update bitsrun to the latest version (installs from the install script only; npm installs update with `npm install -g bitsrun@latest`).

```text
$ bitsrun upgrade
Updating bitsrun 0.5.35 to 0.5.36...
Updated to 0.5.36.
```

### licenses

Show the open source licenses of the libraries bitsrun includes.

## Endpoints

### deploy

Create a private endpoint for a model. It sleeps until the first request, and you pay only while it is awake.

`<model>` can be:

- an Ollama name: `qwen3:8b`
- a Hugging Face repo: `hf:Qwen/Qwen3-8B`, a GGUF repo with an optional quant like `hf:Qwen/Qwen3-8B-GGUF:Q8_0`, or any huggingface.co link, including a link to one `.gguf` file
- one of your uploads: `upload:<id>`
- a local `.gguf` file or a safetensors model folder, like `./my-model.gguf` or `./my-model` (uploaded first)

| Option | What it does |
|---|---|
| `--name <name>` | Display name. Defaults to the model. |
| `--gpu <l4\|l40s\|4xl4>` | GPU size. Defaults to the smallest one that fits. |
| `--idle <time>` | Sleep after this long without requests: from 60 seconds to 1 hour, like `120`, `300s`, `5m` or `1h`. Default 2 minutes. |
| `--key` | Also create an API key that only works with this endpoint. |

```text
$ bitsrun deploy qwen3:8b --name "Support chat" --key
Deployed qwen3:8b on 1x L4 (24 GB). It sleeps until the first request and you pay only while it runs.
The first request after it sleeps waits for a GPU: seconds on a warm host, about 2 to 3 minutes when a new host starts (never billed). For no cold starts, use: bitsrun update "Support chat" --always-on on

Name     Support chat
Id       01k8y4000d3m00000000000011
Model    qwen3:8b
Type     chat
Context  40,960 tokens
GPU      1x L4 (24 GB)
State    sleeping
Idle     sleeps after 2 minutes without requests
URL      https://01k8y4000d3m00000000000011.endpoint.bitsrun.com/v1
Created  2026-11-09

API key (shown once, save it now): brk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Try it:
curl https://01k8y4000d3m00000000000011.endpoint.bitsrun.com/v1/chat/completions \
  -H "Authorization: Bearer $BITSRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen3:8b", "messages": [{"role": "user", "content": "Hello"}]}'
```

Gated or private Hugging Face repos need your token first (see [hf-token](#hf-token)). They are copied into your private storage once, with a progress line, before the endpoint is ready. Read [Gated and private repos](https://bitsrun.com/docs/models/gated-repos/).

### ls

List your endpoints. `bitsrun list` and `bitsrun endpoints` do the same.

```text
$ bitsrun ls
NAME          STATE     GPU  IDLE  MODEL                                    ID
Code helper   sleeping  l4   600s  Qwen/Qwen2.5-Coder-7B-Instruct           01k8y4000d3m00000000000013
Docs search   sleeping  l4   120s  Snowflake/snowflake-arctic-embed-l-v2.0  01k8y4000d3m00000000000012
Support chat  sleeping  l4   300s  Qwen/Qwen3-8B-FP8                        01k8y4000d3m00000000000011
```

### status

Show one endpoint in full. `bitsrun show` does the same.

```bash
bitsrun status "Docs search"
```

The output is the same table `deploy` prints: model, type, context, GPU, state, idle time, URL and creation date.

### update

Change an endpoint's settings. Give at least one option.

| Option | What it does |
|---|---|
| `--name <name>` | Rename it. |
| `--idle <time>` | Change how long it waits before sleeping (60 s to 1 h). |
| `--always-on on\|off` | Keep one replica running: no cold starts, billed per second at the always-on rate while it is on. Turning it on needs at least one day of credit. |
| `--priority on\|off` | Cold starts launch on a dedicated GPU at once instead of waiting for a lower-cost one, at 1.7 times the rate, from the next start. |

```text
$ bitsrun update "Code helper" --idle 5m
Updated Code helper.
```

Read [Sleep, always-on and priority](https://bitsrun.com/docs/endpoints/sleep-and-always-on/) to choose between them.

### retry

Restart copying an endpoint's model after the copy failed or stalled, then wait for it like `deploy`.

```bash
bitsrun retry "Support chat"
```

### rm

Delete an endpoint. Its URL stops working and API keys limited to it stop working everywhere. This cannot be undone. `bitsrun delete` and `bitsrun remove` do the same.

| Option | What it does |
|---|---|
| `--yes`, `-y` | Delete without asking. Required when no one is at the terminal to type the name. |

```text
$ bitsrun rm "Code helper"
Delete Code helper? Its URL stops working and this cannot be undone. Type the name to confirm: Code helper
Deleted Code helper. API keys limited to it no longer work anywhere.
```

### size

Check which GPU a model needs before you deploy it. Nothing is created and nothing is billed.

| Option | What it does |
|---|---|
| `--gpu <l4\|l40s\|4xl4>` | Check a specific GPU size instead of the smallest that fits. |

```text
$ bitsrun size qwen3:8b
qwen3:8b needs 5.2 GB of weights and runs on 1x L4 (24 GB) with llama.cpp, up to 40,960 tokens of context.
```

More in [Model sizer and GPUs](https://bitsrun.com/docs/models/model-sizer/).

## Uploads and Hugging Face

### hf-token

The Hugging Face token BitsRun uses to read gated and private repos you deploy. It is checked with Hugging Face, stored encrypted and never shown again. It is never taken as an argument, so it stays out of your shell history.

| Form | What it does |
|---|---|
| `bitsrun hf-token` or `hf-token show` | Show whose token it is and its last four characters. |
| `bitsrun hf-token set` | Add or replace it. Paste it at the hidden prompt, or pipe it in. |
| `bitsrun hf-token rm` | Remove it. Models you already copied stay in your storage. |

```bash
echo "$HF_TOKEN" | bitsrun hf-token set
```

```text
Saved the Hugging Face token of demo-user, ending in a1b2. We store it encrypted and use it only to read and copy the repos you deploy.
```

### upload

Upload a `.gguf` file or a safetensors model folder to deploy later. Uploads count toward your plan's storage: free up to your plan's amount, then $0.05 per GB a month.

```text
$ bitsrun upload ./support-tuned.Q4_K_M.gguf
Uploading 4.9 GB: 100%
Uploaded support-tuned.Q4_K_M.gguf (4.9 GB). Deploy it with: bitsrun deploy upload:01k8y4000d3m00000000000051
```

Large files go up in parts, four at a time, and a part that fails is retried. See [Upload your own model](https://bitsrun.com/docs/models/uploads/).

### uploads

| Form | What it does |
|---|---|
| `bitsrun uploads` or `uploads ls` | List your uploads, their size, status and the name to deploy them by. |
| `bitsrun uploads rm <upload>` | Delete an upload that no endpoint uses, by id or file name. Add `--yes` to skip the question. |

```text
$ bitsrun uploads
NAME                       FORMAT  SIZE    STATUS  CREATED     DEPLOY AS
support-tuned.Q4_K_M.gguf  gguf    4.9 GB  ready   2026-11-02  upload:01k8y4000d3m00000000000051
```

## API keys

### keys

| Form | What it does |
|---|---|
| `bitsrun keys` or `keys ls` | List your API keys. Only the first characters of each are shown. |
| `bitsrun keys create <name>` | Create a key. Name it after where it will be used. Add `--endpoint <endpoint>` to limit it to one endpoint. |
| `bitsrun keys revoke <key>` | Revoke a key by id or name. Apps using it stop working within seconds. Add `--yes` to skip the question. |

```text
$ bitsrun keys
NAME            PREFIX         WORKS WITH     CREATED     ID
Website search  brk_d3m0cd...  Docs search    2026-10-11  01k8y4000d3m00000000000022
Production app  brk_d3m0ab...  all endpoints  2026-10-03  01k8y4000d3m00000000000021
```

```text
$ bitsrun keys create "Staging server" --endpoint "Support chat"
Created Staging server. This is the only time it is shown, so save it now:

  brk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Read [API keys](https://bitsrun.com/docs/api/api-keys/) for how to store and rotate them.

## Billing

### usage

Running time and cost per endpoint for a period. Without dates it shows this month.

| Option | What it does |
|---|---|
| `--from YYYY-MM-DD` | First day of the period. |
| `--to YYYY-MM-DD` | Last day of the period. |

```text
$ bitsrun usage --from 2026-11-01 --to 2026-11-09
Usage from 2026-11-01 to 2026-11-09: $10.05

ENDPOINT      RUNNING      COST
Support chat  300 minutes  $4.75
Code helper   240 minutes  $3.80
Docs search   94 min 40 s  $1.50
```

Running time counts only the seconds an endpoint was awake. Start-up and sleep are never billed. See [How billing works](https://bitsrun.com/docs/billing/).

## The coding agent

`bitsrun` with no command, in a terminal, opens the coding agent. Its options (`-p`, `--continue`, `--resume`, `--mode`, `--remote` and more) are on [bitsrun coding agent](https://bitsrun.com/docs/agent/) and [Headless runs](https://bitsrun.com/docs/agent/headless/).