Command reference

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

On this page

Account
login
logout
whoami
upgrade
licenses
Endpoints
deploy
ls
status
update
retry
rm
size
Uploads and Hugging Face
hf-token
upload
uploads
API keys
keys
Billing
usage
The coding agent

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.
`-h`, `--help`	Show the help.
`-v`, `--version`	Show the version.

Account

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

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

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

$ 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).

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

$ 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). They are copied into your private storage once, with a progress line, before the endpoint is ready. Read Gated and private repos.

ls

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

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

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

Read Sleep, always-on and priority 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.

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

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

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

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.

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

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.

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

$ 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

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

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

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 and Headless runs.

View as MarkdownUpdated 2026-11-09

Still stuck?

Email support@bitsrun.com with what you tried and any request id you saw. A real person answers.