This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Command Line Interface

The W&B Command Line Interface (CLI) provides powerful tools for managing experiments, hyperparameter sweeps, artifacts, and more directly from your terminal. The CLI is essential for automating workflows, running sweeps, and managing W&B resources programmatically.

Installation and Setup

Install W&B

Install the W&B Python package, which provides both the Python SDK and the CLI tools:

pip install wandb

This single installation gives you:

  • The wandb command-line tool for terminal use
  • The wandb Python library for import wandb in scripts
  • The wb command as a shorthand alias for wandb

Authenticate

Login to your W&B account:

wandb login

You’ll be prompted to paste your API key from https://wandb.ai/authorize.

Basic Usage

wandb [OPTIONS] COMMAND [ARGS]...

Options

Option Description
--version Show the version and exit. (default: False)

Commands

Command Description
agent Run the W&B agent
artifact Commands for interacting with artifacts
beta Beta versions of wandb CLI commands.
controller Run the W&B local sweep controller
disabled Disable W&B.
docker Run your code in a docker container.
docker-run Wrap docker run and adds WANDB_API_KEY and WANDB_DOCKER environment variables.
enabled Enable W&B.
init Configure a directory with Weights & Biases
job Commands for managing and viewing W&B jobs
local Start a local W&B container (deprecated, see wandb server –help)
login Login to Weights & Biases
off No description available
offline Disable W&B sync
on No description available
online Enable W&B sync
projects List projects
pull Pull files from Weights & Biases
restore Restore code, config and docker state for a run.
server Commands for operating a local W&B server
status Show configuration settings
sweep Initialize a hyperparameter sweep.
sync Upload an offline training directory to W&B
verify Checks and verifies local instance of W&B.

W&B CLI Example: Running a Hyperparameter Sweep

One of the most popular uses of the W&B CLI is managing hyperparameter sweeps. Here’s a complete example:

1. Create a training script (train.py):

import wandb
import random
import time

# Initialize W&B run
wandb.init()

# Access sweep parameters from sweep.yaml
config = wandb.config

print(f"Training with: lr={config.learning_rate}, batch_size={config.batch_size}, epochs={config.epochs}")

# Training loop
for epoch in range(config.epochs):
    # Simulate training metrics
    train_loss = random.uniform(0.1, 2.0) * (0.95 ** epoch)
    val_loss = train_loss + random.uniform(-0.05, 0.15)
    accuracy = min(0.99, 0.5 + (epoch * 0.05) + random.uniform(-0.02, 0.02))
    
    # Log metrics to W&B
    wandb.log({
        "epoch": epoch,
        "train_loss": train_loss,
        "validation_loss": val_loss,  # Sweep optimizes this
        "accuracy": accuracy
    })
    
    # Small delay to simulate training time
    time.sleep(0.5)
    
    print(f"Epoch {epoch}: train_loss={train_loss:.3f}, val_loss={val_loss:.3f}, acc={accuracy:.3f}")

# Log final results
wandb.log({
    "final_validation_loss": val_loss,
    "final_accuracy": accuracy
})

2. Create a sweep configuration file (sweep.yaml):

The sweep configuration defines which script to run and what parameters to try. The W&B agent will automatically inject these parameter values into your script via wandb.config:

program: train.py
method: bayes
metric:
  name: validation_loss
  goal: minimize
parameters:
  learning_rate:
    distribution: log_uniform_values
    min: 0.0001
    max: 0.1
  batch_size:
    values: [16, 32, 64]
  epochs:
    value: 10

3. Initialize the sweep:

wandb sweep sweep.yaml
# Output: Created sweep with ID: abc123
# Run sweep agent with: wandb agent entity/project/abc123

4. Start sweep agents to run experiments:

# Run a single agent
wandb agent entity/project/abc123

# Or run multiple agents in parallel (in different terminals)
wandb agent --count 10 entity/project/abc123

The CLI will automatically manage the hyperparameter search, running your training script with different configurations to find the optimal parameters.

1 - wandb agent

Run the W&B agent

Usage

wandb agent SWEEP_ID [OPTIONS]

Arguments

Argument Description Required
SWEEP_ID No description available Yes

Options

Option Description
--project, -p The name of the project where W&B runs created from the sweep are sent to. If the project is not specified, the run is sent to a project labeled ‘Uncategorized’.
--entity, -e The username or team name where you want to send W&B runs created by the sweep to. Ensure that the entity you specify already exists. If you don’t specify an entity, the run will be sent to your default entity, which is usually your username.
--count The max number of runs for this agent.

2 - wandb artifact

Commands for interacting with artifacts

Usage

wandb artifact COMMAND [ARGS]...

Commands

Command Description
cache Commands for interacting with the artifact cache
get Download an artifact from wandb
ls List all artifacts in a wandb project
put Upload an artifact to wandb

2.1 - wandb artifact cache

Commands for interacting with the artifact cache

Usage

wandb artifact cache COMMAND [ARGS]...

Commands

Command Description
cleanup Clean up less frequently used files from the artifacts cache

2.1.1 - wandb artifact cache cleanup

Clean up less frequently used files from the artifacts cache

Usage

wandb cleanup TARGET_SIZE [OPTIONS]

Arguments

Argument Description Required
TARGET_SIZE No description available Yes

Options

Option Description
--remove-temp Remove temp files (default: False)

2.2 - wandb artifact get

Download an artifact from wandb

Usage

wandb get PATH [OPTIONS]

Arguments

Argument Description Required
PATH No description available Yes

Options

Option Description
--root The directory you want to download the artifact to
--type The type of artifact you are downloading

2.3 - wandb artifact ls

List all artifacts in a wandb project

Usage

wandb ls PATH [OPTIONS]

Arguments

Argument Description Required
PATH No description available Yes

Options

Option Description
--type, -t The type of artifacts to list

2.4 - wandb artifact put

Upload an artifact to wandb

Usage

wandb put PATH [OPTIONS]

Arguments

Argument Description Required
PATH No description available Yes

Options

Option Description
--name, -n The name of the artifact to push: project/artifact_name
--description, -d A description of this artifact
--type, -t The type of the artifact (default: dataset)
--alias, -a An alias to apply to this artifact (default: [’latest’])
--id The run you want to upload to.
--resume Resume the last run from your current directory.
--skip_cache Skip caching while uploading artifact files. (default: False)
--policy Set the storage policy while uploading artifact files. (default: mutable)

3 - wandb beta

Beta versions of wandb CLI commands. Requires wandb-core.

Usage

wandb beta COMMAND [ARGS]...

Commands

Command Description
sync Upload a training run to W&B

3.1 - wandb beta sync

Upload a training run to W&B

Usage

wandb sync WANDB_DIR [OPTIONS]

Arguments

Argument Description Required
WANDB_DIR No description available Yes

Options

Option Description
--id The run you want to upload to.
--project, -p The project you want to upload to.
--entity, -e The entity to scope to.
--skip-console Skip console logs (default: False)
--append Append run (default: False)
--include, -i Glob to include. Can be used multiple times.
--exclude, -e Glob to exclude. Can be used multiple times.
--mark-synced Mark runs as synced (default: True)
--skip-synced Skip synced runs (default: True)
--dry-run Perform a dry run without uploading anything. (default: False)

4 - wandb controller

Run the W&B local sweep controller

Usage

wandb controller SWEEP_ID [OPTIONS]

Arguments

Argument Description Required
SWEEP_ID No description available Yes

Options

Option Description
--verbose Display verbose output (default: False)

5 - wandb disabled

Disable W&B.

Usage

wandb disabled [OPTIONS]

Options

Option Description
--service Disable W&B service (default: True)

6 - wandb docker

Run your code in a docker container.

W&B docker lets you run your code in a docker image ensuring wandb is configured. It adds the WANDB_DOCKER and WANDB_API_KEY environment variables to your container and mounts the current directory in /app by default. You can pass additional args which will be added to docker run before the image name is declared, we’ll choose a default image for you if one isn’t passed:

sh wandb docker -v /mnt/dataset:/app/data wandb docker gcr.io/kubeflow-images-public/tensorflow-1.12.0-notebook-cpu:v0.4.0 --jupyter wandb docker wandb/deepo:keras-gpu --no-tty --cmd "python train.py --epochs=5"

By default, we override the entrypoint to check for the existence of wandb and install it if not present. If you pass the –jupyter flag we will ensure jupyter is installed and start jupyter lab on port 8888. If we detect nvidia-docker on your system we will use the nvidia runtime. If you just want wandb to set environment variable to an existing docker run command, see the wandb docker-run command.

Usage

wandb docker [DOCKER_RUN_ARGS] [DOCKER_IMAGE] [OPTIONS]

Arguments

Argument Description Required
DOCKER_RUN_ARGS No description available No
DOCKER_IMAGE No description available No

Options

Option Description
--nvidia Use the nvidia runtime, defaults to nvidia if nvidia-docker is present (default: False)
--digest Output the image digest and exit (default: False)
--jupyter Run jupyter lab in the container (default: False)
--dir Which directory to mount the code in the container (default: /app)
--no-dir Don’t mount the current directory (default: False)
--shell The shell to start the container with (default: /bin/bash)
--port The host port to bind jupyter on (default: 8888)
--cmd The command to run in the container
--no-tty Run the command without a tty (default: False)

7 - wandb docker-run

Wrap docker run and adds WANDB_API_KEY and WANDB_DOCKER environment variables.

This will also set the runtime to nvidia if the nvidia-docker executable is present on the system and –runtime wasn’t set.

See docker run --help for more details.

Usage

wandb docker-run [DOCKER_RUN_ARGS]

Arguments

Argument Description Required
DOCKER_RUN_ARGS No description available No

8 - wandb enabled

Enable W&B.

Usage

wandb enabled [OPTIONS]

Options

Option Description
--service Enable W&B service (default: True)

9 - wandb init

Configure a directory with Weights & Biases

Usage

wandb init [OPTIONS]

Options

Option Description
--project, -p The project to use.
--entity, -e The entity to scope the project to.
--reset Reset settings (default: False)
--mode, -m Can be “online”, “offline” or “disabled”. Defaults to online.

10 - wandb job

Commands for managing and viewing W&B jobs

Usage

wandb job COMMAND [ARGS]...

Commands

Command Description
create Create a job from a source, without a wandb run.
describe Describe a launch job.
list List jobs in a project

10.1 - wandb job create

Create a job from a source, without a wandb run.

Jobs can be of three types, git, code, or image.

git: A git source, with an entrypoint either in the path or provided explicitly pointing to the main python executable. code: A code path, containing a requirements.txt file. image: A docker image.

Usage

wandb create JOB_TYPE PATH [OPTIONS]

Arguments

Argument Description Required
JOB_TYPE No description available Yes
PATH No description available Yes

Options

Option Description
--project, -p The project you want to list jobs from.
--entity, -e The entity the jobs belong to
--name, -n Name for the job
--description, -d Description for the job
--alias, -a Alias for the job
--entry-point, -E Entrypoint to the script, including an executable and an entrypoint file. Required for code or repo jobs. If –build-context is provided, paths in the entrypoint command will be relative to the build context.
--git-hash, -g Commit reference to use as the source for git jobs
--runtime, -r Python runtime to execute the job
--build-context, -b Path to the build context from the root of the job source code. If provided, this is used as the base path for the Dockerfile and entrypoint.
--base-image, -B Base image to use for the job. Incompatible with image jobs.
--dockerfile, -D Path to the Dockerfile for the job. If –build-context is provided, the Dockerfile path will be relative to the build context.
--service, -s Service configurations in format serviceName=policy. Valid policies: always, never
--schema Path to the schema file for the job.

10.2 - wandb job describe

Describe a launch job. Provide the launch job in the form of: entity/project/job-name:alias-or-version

Usage

wandb describe JOB

Arguments

Argument Description Required
JOB No description available Yes

10.3 - wandb job list

List jobs in a project

Usage

wandb list [OPTIONS]

Options

Option Description
--project, -p The project you want to list jobs from.
--entity, -e The entity the jobs belong to (default: models)

11 - wandb launch

Launch or queue a W&B Job. See https://wandb.me/launch

Usage

wandb launch [OPTIONS]

Options

Option Description
--uri, -u Local path or git repo uri to launch. If provided this command will create a job from the specified uri.
--job, -j Name of the job to launch. If passed in, launch does not require a uri.
--entry-point, -E Entry point within project. [default: main]. If the entry point is not found, attempts to run the project file with the specified name as a script, using ‘python’ to run .py files and the default shell (specified by environment variable $SHELL) to run .sh files. If passed in, will override the entrypoint value passed in using a config file.
--git-version, -g Version of the project to run, as a Git commit reference for Git projects.
--build-context Path to the build context within the source code. Defaults to the root of the source code. Compatible only with -u.
--job-name, -J Name for the job created if the -u,–uri flag is passed in.
--name Name of the run under which to launch the run. If not specified, a random run name will be used to launch run. If passed in, will override the name passed in using a config file.
--entity, -e Name of the target entity which the new run will be sent to. Defaults to using the entity set by local wandb/settings folder. If passed in, will override the entity value passed in using a config file.
--project, -p Name of the target project which the new run will be sent to. Defaults to using the project name given by the source uri or for github runs, the git repo name. If passed in, will override the project value passed in using a config file.
--resource, -r Execution resource to use for run. Supported values: ’local-process’, ’local-container’, ‘kubernetes’, ‘sagemaker’, ‘gcp-vertex’. This is now a required parameter if pushing to a queue with no resource configuration. If passed in, will override the resource value passed in using a config file.
--docker-image, -d Specific docker image you’d like to use. In the form name:tag. If passed in, will override the docker image value passed in using a config file.
--base-image, -B Docker image to run job code in. Incompatible with –docker-image.
--config, -c Path to JSON file (must end in ‘.json’) or JSON string which will be passed as a launch config. Dictation how the launched run will be configured.
--set-var, -v Set template variable values for queues with allow listing enabled, as key-value pairs e.g. --set-var key1=value1 --set-var key2=value2
--queue, -q Name of run queue to push to. If none, launches single run directly. If supplied without an argument (--queue), defaults to queue ‘default’. Else, if name supplied, specified run queue must exist under the project and entity supplied.
--async Flag to run the job asynchronously. Defaults to false, i.e. unless –async is set, wandb launch will wait for the job to finish. This option is incompatible with –queue; asynchronous options when running with an agent should be set on wandb launch-agent. (default: False)
--resource-args, -R Path to JSON file (must end in ‘.json’) or JSON string which will be passed as resource args to the compute resource. The exact content which should be provided is different for each execution backend. See documentation for layout of this file.
--build, -b Flag to build an associated job and push to queue as an image job. (default: False)
--repository, -rg Name of a remote repository. Will be used to push a built image to.
--project-queue, -pq Name of the project containing the queue to push to. If none, defaults to entity level queues.
--dockerfile, -D Path to the Dockerfile used to build the job, relative to the job’s root
--priority, -P When –queue is passed, set the priority of the job. Launch jobs with higher priority are served first. The order, from highest to lowest priority, is: critical, high, medium, low

12 - wandb launch-agent

Run a W&B launch agent.

Usage

wandb launch-agent [OPTIONS]

Options

Option Description
--queue, -q The name of a queue for the agent to watch. Multiple -q flags supported.
--entity, -e The entity to use. Defaults to current logged-in user
--log-file, -l Destination for internal agent logs. Use - for stdout. By default all agents logs will go to debug.log in your wandb/ subdirectory or WANDB_DIR if set.
--max-jobs, -j The maximum number of launch jobs this agent can run in parallel. Defaults to 1. Set to -1 for no upper limit
--config, -c path to the agent config yaml to use
--url, -u a wandb client registration URL, this is generated in the UI
--verbose, -v Display verbose output (default: 0)

13 - wandb launch-sweep

Run a W&B launch sweep (Experimental).

Usage

wandb launch-sweep [CONFIG] [OPTIONS]

Arguments

Argument Description Required
CONFIG No description available No

Options

Option Description
--queue, -q The name of a queue to push the sweep to
--project, -p Name of the project which the agent will watch. If passed in, will override the project value passed in using a config file
--entity, -e The entity to use. Defaults to current logged-in user
--resume_id, -r Resume a launch sweep by passing an 8-char sweep id. Queue required
--prior_run, -R ID of an existing run to add to this sweep

14 - wandb local

Start a local W&B container (deprecated, see wandb server –help)

Usage

wandb local [OPTIONS]

Options

Option Description
--port, -p The host port to bind W&B local on (default: 8080)
--env, -e Env vars to pass to wandb/local (default: [])
--daemon Run or don’t run in daemon mode (default: True)
--upgrade Upgrade to the most recent version (default: False)
--edge Run the bleeding edge (default: False)

15 - wandb login

Login to Weights & Biases

Usage

wandb login [KEY] [OPTIONS]

Arguments

Argument Description Required
KEY No description available No

Options

Option Description
--cloud Login to the cloud instead of local (default: False)
--host, --base-url Login to a specific instance of W&B
--relogin Force relogin if already logged in.
--anonymously Log in anonymously (default: False)
--verify Verify login credentials (default: False)

16 - wandb off

Usage

wandb off

17 - wandb offline

Disable W&B sync

Usage

wandb offline

18 - wandb on

Usage

wandb on

19 - wandb online

Enable W&B sync

Usage

wandb online

20 - wandb projects

List projects

Usage

wandb projects [OPTIONS]

Options

Option Description
--entity, -e The entity to scope the listing to.

21 - wandb pull

Pull files from Weights & Biases

Usage

wandb pull RUN [OPTIONS]

Arguments

Argument Description Required
RUN No description available Yes

Options

Option Description
--project, -p The project you want to download.
--entity, -e The entity to scope the listing to. (default: models)

22 - wandb restore

Restore code, config and docker state for a run. Retrieves code from latest commit if code was not saved with wandb.save() or wandb.init(save_code=True).

Usage

wandb restore RUN [OPTIONS]

Arguments

Argument Description Required
RUN No description available Yes

Options

Option Description
--no-git Don’t restore git state (default: False)
--branch Whether to create a branch or checkout detached (default: True)
--project, -p The project you wish to upload to.
--entity, -e The entity to scope the listing to.

23 - wandb scheduler

Run a W&B launch sweep scheduler (Experimental)

Usage

wandb scheduler SWEEP_ID

Arguments

Argument Description Required
SWEEP_ID No description available Yes

24 - wandb server

Commands for operating a local W&B server

Usage

wandb server COMMAND [ARGS]...

Commands

Command Description
start Start a local W&B server
stop Stop a local W&B server

24.1 - wandb server start

Start a local W&B server

Usage

wandb start [OPTIONS]

Options

Option Description
--port, -p The host port to bind W&B server on (default: 8080)
--env, -e Env vars to pass to wandb/local (default: [])
--daemon Run or don’t run in daemon mode (default: True)
--upgrade Upgrade to the most recent version (default: False)
--edge Run the bleeding edge (default: False)

24.2 - wandb server stop

Stop a local W&B server

Usage

wandb stop

25 - wandb status

Show configuration settings

Usage

wandb status [OPTIONS]

Options

Option Description
--settings Show the current settings (default: True)

26 - wandb sweep

Initialize a hyperparameter sweep. Search for hyperparameters that optimizes a cost function of a machine learning model by testing various combinations.

Usage

wandb sweep CONFIG_YAML_OR_SWEEP_ID [OPTIONS]

Arguments

Argument Description Required
CONFIG_YAML_OR_SWEEP_ID No description available Yes

Options

Option Description
--project, -p The name of the project where W&B runs created from the sweep are sent to. If the project is not specified, the run is sent to a project labeled Uncategorized.
--entity, -e The username or team name where you want to send W&B runs created by the sweep to. Ensure that the entity you specify already exists. If you don’t specify an entity, the run will be sent to your default entity, which is usually your username.
--controller Run local controller (default: False)
--verbose Display verbose output (default: False)
--name The name of the sweep. The sweep ID is used if no name is specified.
--program Set sweep program
--settings Set sweep settings
--update Update pending sweep
--stop Finish a sweep to stop running new runs and let currently running runs finish. (default: False)
--cancel Cancel a sweep to kill all running runs and stop running new runs. (default: False)
--pause Pause a sweep to temporarily stop running new runs. (default: False)
--resume Resume a sweep to continue running new runs. (default: False)
--prior_run, -R ID of an existing run to add to this sweep

27 - wandb sync

Upload an offline training directory to W&B

Usage

wandb sync [PATH] [OPTIONS]

Arguments

Argument Description Required
PATH No description available No

Options

Option Description
--view View runs (default: False)
--verbose Verbose (default: False)
--id The run you want to upload to.
--project, -p The project you want to upload to.
--entity, -e The entity to scope to.
--job_type Specifies the type of run for grouping related runs together.
--sync-tensorboard Stream tfevent files to wandb.
--include-globs Comma separated list of globs to include.
--exclude-globs Comma separated list of globs to exclude.
--include-online Include online runs
--include-offline Include offline runs
--include-synced Include synced runs
--mark-synced Mark runs as synced (default: True)
--sync-all Sync all runs (default: False)
--clean Delete synced runs (default: False)
--clean-old-hours Delete runs created before this many hours. To be used alongside –clean flag. (default: 24)
--clean-force Clean without confirmation prompt. (default: False)
--ignore No description available
--show Number of runs to show (default: 5)
--append Append run (default: False)
--skip-console Skip console logs (default: False)
--replace-tags Replace tags in the format ‘old_tag1=new_tag1,old_tag2=new_tag2’

28 - wandb verify

Checks and verifies local instance of W&B. W&B checks for:

Checks that the host is not api.wandb.ai (host check).

Verifies if the user is logged in correctly using the provided API key (login check).

Checks that requests are made over HTTPS (secure requests).

Validates the CORS (Cross-Origin Resource Sharing) configuration of the object store (CORS configuration).

Logs metrics, saves, and downloads files to check if runs are correctly recorded and accessible (run check).

Saves and downloads artifacts to verify that the artifact storage and retrieval system is working as expected (artifact check).

Tests the GraphQL endpoint by uploading a file to ensure it can handle signed URL uploads (GraphQL PUT check).

Checks the ability to send large payloads through the proxy (large payload check).

Verifies that the installed version of the W&B package is up-to-date and compatible with the server (W&B version check).

Creates and executes a sweep to ensure that sweep functionality is working correctly (sweeps check).

Usage

wandb verify [OPTIONS]

Options

Option Description
--host Test a specific instance of W&B