Reference
forge CLI
The command line tool, every command, and how it finds your key.
Install
curl -fsSL https://get.useblackforge.com | sh # macOS and Linux
forge versionOne static binary in ~/.forge/bin. It reads the key from BF_KEY, or from ~/.forge/config after forge login.
Commands
| Command | Does |
|---|---|
forge login | Save a key for this machine |
forge forges | Free GPUs and waits per plan |
forge run | Start a job. Everything after -- is the command |
forge ls | Your team's recent jobs |
forge watch ID | Live heat for a job's GPUs |
forge logs ID [-f] | Print or follow logs |
forge stop ID | Stop a job |
forge shell / notebook | Start an interactive session |
forge cp SRC DST | Copy to and from /shared |
forge bank | Hour bank balance |
forge usage [--month] | Billed GPU hours and cost |
forge run flags
| Flag | Same as API field |
|---|---|
--image | image |
--gpus | gpus |
--plan | plan, default strike |
--limit | limit, default 1h |
--env KEY=VALUE | env, repeatable |
--port 8000 | ports, repeatable |
--resume | resume, Ember only |
--tag key=value | tags, repeatable |
--detach | Return at once instead of following the stages |
A job file
For runs you repeat, put the flags in a file and pass it with -f.
# train.forge.toml
image = "ghcr.io/yourlab/train:latest"
command = ["torchrun", "--nproc-per-node=8", "train.py"]
gpus = 8
plan = "bank"
limit = "2d"
[env]
WANDB_PROJECT = "tide-7b"forge run -f train.forge.tomlExit codes
forge run without --detach exits with your container's exit code, so it works in CI. It exits 75 if the job was preempted and 70 for a hardware result.