div run

Synopsis

div run [flags] <entrypoint>
div run [flags] -- <command...>

Uploads the current directory, starts a run, streams its log, and exits with the run’s exit code.

Arguments

Argument	Description
<entrypoint>	What to run. See Entrypoints.
-- <command...>	Everything after -- is passed to the run unchanged. Use it when your command has its own flags.

Flags

Flag	Description	Default
--gpu <type>	GPU type: b300, h200, h100, l40s or cpu.	h100
--gpus <n>	Number of GPUs.	1
--cpu <n>	Physical CPU cores for the run. See Container size.	1 per GPU
--memory <size>	Memory in whole GiB: 64, 64G or 64GiB. Values below 1 GiB, such as 512M, are rejected.	8 GiB per GPU, 2 GiB for cpu
--max-spend <usd>	Stop the run when it has cost this many dollars. 5, 5.00 and $5 are equivalent.	none
--project <name>	Project the run belongs to.	the directory name
--name <name>	Run name.	generated
--image <ref>	Public container image to run in. See Runtime environment.	pytorch/pytorch:2.14.0-cuda12.6-cudnn9-runtime
--env KEY=value	Environment variable for the run. Repeatable. Values are visible in the dashboard, so use secrets for credentials.
--check <check>	Condition the run’s result must meet, such as metrics.accuracy>=0.8. Repeatable. See Check syntax.
--telemetry <file>	Chart layout for the run’s Telemetry tab. See telemetry.toml.	telemetry.toml in the uploaded directory, if present
--volume <name>	Volume to upload the code to.	<project>-code
--no-upload	Upload nothing and run the command in the image as it is.
-d, --detach	Print the run’s name and exit once the run has started.
--json	Print the run as JSON when it ends. With --detach, print it when it starts.
--token <key>	API key to use.	see Configuration
--api-url <url>	API URL to use.	see Configuration

--gpu h100 and --gpu=h100 are equivalent. There is no --nodes flag: --gpus 32 requests the same hardware as 4 nodes of 8. An unknown flag is an error. div run validates all flags before it uploads anything.

Entrypoints

You write	The run executes
train.py::run	python -u -c 'from train import run; run()'
models/lora.py::train	python -u -c 'from models.lora import train; train()'
train.py	python -u train.py
anything containing a space	your command, unchanged

The command runs in /workspace, which holds a copy of the uploaded directory.

Pricing

--gpu	Per GPU per hour	Included per GPU
b300	$8.30	1 core, 8 GiB
h200	$5.45	1 core, 8 GiB
h100	$4.80	1 core, 8 GiB
l40s	$2.55	1 core, 8 GiB
cpu	$0.30	1 core, 2 GiB

Runs are billed per minute, with a one-minute minimum. --gpus 8 --gpu h100 costs $39.60 an hour.

Container size

Each core above the included amount costs $0.15 an hour. Each GiB above the included amount costs $0.03 an hour. Requesting less than the included amount costs the same as the default.

Limit	Value
Maximum cores	64 (physical, 2 threads each)
Maximum memory	336 GiB

For example, --gpu h100 --cpu 8 --memory 64G costs $4.80 + 7 × $0.15 + 56 × $0.03 = $7.53 an hour.

A run that exceeds its memory is killed. A run that needs more cores than it has runs slower.

Check syntax

A check is <path><operator><value>, for example metrics.accuracy>=0.8.

Part	Allowed values
path	Keys separated by dots. Keys contain letters, digits, _ and -.
operator	>=, <=, >, <, ==, !=
value	A number, true, false or a string. >, <, >= and <= require a number.

After the run exits, each check gets a verdict: passed, failed or unknown. unknown means the result has no value at the path, and it does not count as a pass. Checks do not change the run’s status or exit code. See Report a run’s metrics and check them.

Uploaded files

Inside a git repository, div run uploads the files git ls-files lists: tracked files plus untracked files that are not ignored.

Outside a repository, it uploads everything except .git, node_modules, __pycache__, .venv, venv, tool caches, dist, .next, .DS_Store, *.pyc and files whose names start with .env.

Each run gets its own copy of the code. A directory with no files to upload is an error. To keep large data out of the upload, see Keep data and checkpoints on a volume.

Output

Before the run’s log, div run prints to stderr the files uploaded, and the run’s hardware, hourly rate and how long the spend limit lasts:

14 files, 38.2 KB → very-cool-classifier-code/code/9f31c2ab
run-k4t9  H100  $4.80/h  max spend $5.00 (about 1h 2m)

The run’s stdout and stderr follow unchanged on stdout and stderr. When the run ends, div run prints one line to stderr:

Run status	Last line
succeeded	run-k4t9 finished in 12m 40s and spent $1.05, followed by the check results if the run has checks (· passed 2 of 2 checks)
budget_exceeded	the spend limit reached and the duration
limit_reached	the org’s usage limit reached, the duration and the amount spent
failed	the duration, exit code and amount spent
canceled	the duration and amount spent

Ctrl-C detaches: the run keeps going, and div run prints the commands to follow it (div logs <run> -f) and stop it (div stop <run>).

Exit codes

Code	Meaning
the run’s exit code	The run ended with a non-zero exit code.
0	The run succeeded, or you detached.
1	The run stopped without an exit code (spend limit, usage limit, canceled), or the API rejected the request.
2	Invalid flags or arguments, or no API key.

Examples

div run --gpu h100 train.py::run --max-spend 5.00
div run --gpu h200 --gpus 32 finetune.py::lora --max-spend 1500
div run --gpu h100 --cpu 8 --memory 64G train.py --max-spend 10
div run --detach -- torchrun --nproc-per-node 8 train.py
div run eval.py --check 'metrics.accuracy>=0.8' --check 'metrics.loss<0.6'