Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .nextchanges/air/help-revamp.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
* Reorganize `databricks air` help: subcommands are grouped by task, `air run` has examples, and YAML fields are listed under headings, with pool fields marked optional and `command`, `compute.num_accelerators`, and `compute.accelerator_type` correctly marked required. ([#7512](https://github.com/databricks/cli/pull/7512))
113 changes: 72 additions & 41 deletions acceptance/air/config-help/output.txt
Original file line number Diff line number Diff line change
Expand Up @@ -2,29 +2,35 @@
=== command help

>>> [CLI] air run --help
Submit a training workload to Databricks serverless GPU compute.
Submit a workload to Databricks serverless GPU compute.

The workload is described by a YAML config file (see --file).
The workload is described by a YAML file (see --file). To look up a YAML
field, pass its path to -h as a separate argument:

To look up a config field, pass its path to -h:

databricks air run -h config
databricks air run -h config.compute
databricks air run -h config.compute.accelerator_type

The path must be a separate argument: cobra reserves -h as a boolean, so
-h=config.compute and -hconfig.compute are not accepted.
databricks air run -h config all fields
databricks air run -h config.compute one section
databricks air run -h config.compute.accelerator_type one field

Usage:
databricks air run [flags]

Examples:
# Submit and stream logs until the run finishes
databricks air run -f workload.yaml --watch

# Validate the config against the workspace without submitting
databricks air run -f workload.yaml --dry-run

# Try a different GPU without editing the file
databricks air run -f workload.yaml --override compute.accelerator_type=GPU_1xH100

Flags:
--dry-run Validate the config against the workspace without submitting a run
-f, --file string Path to the workload YAML config
-h, --help help for run
--idempotency-key string Return the existing run if this key was already used
--override stringArray Override a YAML field, e.g. compute.num_accelerators=8 (repeatable)
--watch Stream logs until the run completes
--override stringArray Override a YAML field, e.g. compute.num_accelerators=8 (repeatable)
--dry-run Validate the config against the workspace without submitting a run
--idempotency-key string Return the existing run if this key was already used
-h, --help help for run

Global Flags:
--debug enable debug logging
Expand All @@ -36,40 +42,51 @@ Global Flags:

>>> [CLI] air run -h config
config
The run YAML schema. Pass a field path for details, e.g. config.compute.accelerator_type.

AI coding agents can use the databricks-ai-runtime skill to write workload
YAML, submit runs, and monitor progress.
Workload YAML schema. For details on a field, pass its path to -h, for example:

Install the skill locally for your coding agent:
databricks air run -h config.compute.accelerator_type

@caroline-db caroline-db Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this would be a better example here since this help only lists top level fields, it's slightly unclear where accelerator_type is coming from

Suggested change
databricks air run -h config.compute.accelerator_type
databricks air run -h config.compute


databricks aitools install --skills-only --skills databricks-ai-runtime
Comment thread
stevenchen-db marked this conversation as resolved.
Resolved
Minimal example:
experiment_name: my-run
compute:
num_accelerators: 1
accelerator_type: GPU_1xA10
code_source:
root_path: .
command: python "$CODE_SOURCE_PATH/train.py"

Follow the prompts to choose your coding agent and installation scope.
Use --scope project to install into the current project.
See: https://github.com/databricks/databricks-agent-skills/tree/main/skills/databricks-ai-runtime

Fields:
Workload:
experiment_name (required) Name of the experiment.
compute (required) Which accelerators to run on and how many.
command (required unless containers is set) Shell command that starts the workload.
environment Python dependencies, runtime version, or a Unity Catalog image for a single-command run.
command Shell command that starts the workload.
containers Rank-partitioned containers for heterogeneous workloads.
env_variables Plain environment variables, as NAME: value.
secrets Environment variables sourced from secrets, as NAME: scope/key.
code_source Local code to upload and make available to the run.
parameters Free-form values passed through to the workload.

Execution:
max_retries How many times to retry a failed run.
timeout_minutes Wall-clock limit for the run in minutes.
idempotency_token Reuse token: a repeat submission with the same token returns the existing run instead of starting another.
parameters Free-form values passed through to the workload.

MLflow tracking:
mlflow_run_name Name for the MLflow run.
mlflow_experiment_directory Workspace directory holding the MLflow experiment.
mlflow_artifact_location DBFS location where MLflow artifacts are written.

Access and cost attribution:
permissions Who may view or manage the run, as a list of principal plus level grants.
usage_policy_name Usage policy to bill the run to, by name.
usage_policy_id Usage policy to bill the run to, by id.
usage_policy_name Usage policy to attribute the run's usage to, by name.
usage_policy_id Usage policy to attribute the run's usage to, by id.

Use "-h config.<field>" for details on a field.
For details on a field, run "databricks air run -h config.<field>".

Let a coding agent write this YAML for you with the databricks-ai-runtime skill:
databricks aitools install --skills-only --skills databricks-ai-runtime
(add --scope project to install into the current project)
https://github.com/databricks/databricks-agent-skills/tree/main/skills/databricks-ai-runtime

=== nested object lists its fields

Expand All @@ -83,12 +100,14 @@ config.compute
GPU_1xRTX6000 - 1 accelerator per node

Fields:
num_accelerators Total number of GPUs to allocate.
accelerator_type Which accelerator to run on, e.g. GPU_1xA10.
num_accelerators (required) Total number of GPUs to allocate.
accelerator_type (required) Which accelerator to run on, e.g. GPU_1xA10.

Provisioned capacity (optional):
pool_id GPU pool to run on, by id.
priority_class Scheduling priority within the pool: BEST_EFFORT (lowest, preemptable) or NORMAL.

Use "-h config.compute.<field>" for details on a field.
For details on a field, run "databricks air run -h config.compute.<field>".

=== new submission fields are documented

Expand All @@ -101,7 +120,7 @@ config.mlflow_artifact_location

>>> [CLI] air run -h config.compute.pool_id
config.compute.pool_id
GPU pool to run on, by id. A GPU pool is a pre-provisioned accelerator reservation; contact your Databricks account team to provision one. Must be 1-255 characters. List available pools with 'air pools list'.
GPU pool to run on, by id. A GPU pool is a pre-provisioned accelerator reservation; contact your Databricks account team to provision one. Must be 1-255 characters. List available pools with 'databricks air pools list'.

Type: string
Required: no
Expand All @@ -122,7 +141,11 @@ config.environment.dependencies

>>> [CLI] air run -h config.environment.version
config.environment.version
Client image version to pin (default: 6). See environment version release notes: https://docs.databricks.com/aws/en/release-notes/serverless/environment-version/
Managed environment to start from, e.g. 6 for the Standard environment or databricks_ai_v6 for the Databricks AI environment (default: 6). Standard includes CUDA but, from version 5, not PyTorch; add it with dependencies. The Databricks AI environment adds PyTorch, Transformers, and other ML libraries. See Docs below for supported versions and package lists.

Docs:
AWS: https://docs.databricks.com/aws/en/machine-learning/ai-runtime/develop-workloads/environment
Azure: https://learn.microsoft.com/azure/databricks/machine-learning/ai-runtime/develop-workloads/environment

Type: string or int
Required: no
Expand All @@ -131,15 +154,19 @@ config.environment.version

>>> [CLI] air run -h config.compute.accelerator_type
config.compute.accelerator_type
Which accelerator to run on, e.g. GPU_1xA10. See https://docs.databricks.com/aws/en/machine-learning/ai-runtime/cli/yaml-config#reference for the current list of supported GPU types. Matched case-sensitively.
Which accelerator to run on, e.g. GPU_1xA10. Matched case-sensitively.

Supported accelerator types:
GPU_1xH100 - 1 accelerator per node
GPU_8xH100 - 8 accelerators per node
GPU_1xRTX6000 - 1 accelerator per node

Docs:
AWS: https://docs.databricks.com/aws/en/machine-learning/ai-runtime/connecting/cli/yaml-config#accelerator-types
Azure: https://learn.microsoft.com/azure/databricks/machine-learning/ai-runtime/connecting/cli/yaml-config#accelerator-types

Type: string
Required: no
Required: yes

=== code source fields

Expand All @@ -148,12 +175,12 @@ config.code_source
Local code to upload and make available to the run.

Fields:
root_path Root of the code source to archive.
root_path (required when code_source is set) Root of the code source to archive.
remote_volume Volume to upload the archive to.
git Pin the snapshot to a specific git revision.
include_paths Restrict the archive to these paths, relative to root_path and without "..".

Use "-h config.code_source.<field>" for details on a field.
For details on a field, run "databricks air run -h config.code_source.<field>".

=== union field

Expand All @@ -177,10 +204,14 @@ config.code_source.root_path

>>> [CLI] air run -h compute.num_accelerators
config.compute.num_accelerators
Total number of GPUs to allocate. Must be a positive multiple of the accelerator type's per-node GPU count. See https://docs.databricks.com/aws/en/machine-learning/ai-runtime/cli/yaml-config#reference for supported GPU types.
Total number of GPUs to allocate. Must be a positive multiple of the accelerator type's per-node GPU count. See Docs below for GPUs per node.

Docs:
AWS: https://docs.databricks.com/aws/en/machine-learning/ai-runtime/connecting/cli/yaml-config#accelerator-types
Azure: https://learn.microsoft.com/azure/databricks/machine-learning/ai-runtime/connecting/cli/yaml-config#accelerator-types

Type: int
Required: no
Required: yes

=== unknown field suggests the near match

Expand Down
50 changes: 34 additions & 16 deletions acceptance/air/help/output.txt
Original file line number Diff line number Diff line change
Expand Up @@ -2,22 +2,30 @@
=== help

>>> [CLI] air --help
Run and manage AI Runtime training workloads on Databricks serverless GPU compute.
Run GPU workloads on Databricks serverless compute.

These commands are under active development.
Describe a workload in a YAML file and submit it with "databricks air run".
Follow a run with "databricks air logs" and "databricks air get", or see your
active runs with "databricks air list".

Usage:
databricks air [command]

Available Commands:
Run workloads:
run Submit a workload from a YAML config

Manage runs:
cancel Cancel one or more runs
convert-to-dabs Convert an AIR run YAML into a Databricks Asset Bundle
get Show status, configuration, and timing details for a specified run
images Manage container images for AI Runtime
list List active runs for the current user
logs Stream or fetch logs for a run
pools View provisioned GPU pools
run Submit a training workload from a YAML config
get Show a run's status, configuration, and timing
list List your active runs
logs Stream or fetch a run's logs

Package and deploy:
convert-to-dabs Convert a workload YAML into a Databricks Asset Bundle
images Push container images for custom environments

Provisioned capacity:
pools View GPU pools provisioned for your workspace

Flags:
-h, --help help for air
Expand All @@ -30,6 +38,12 @@ Global Flags:

Use "databricks air [command] --help" for more information about a command.

Learn more:
YAML fields and example databricks air run -h config
Quickstart (AWS) https://docs.databricks.com/aws/en/machine-learning/ai-runtime/quickstart
Quickstart (Azure) https://learn.microsoft.com/azure/databricks/machine-learning/ai-runtime/quickstart
Coding agent skill databricks aitools install --skills-only --skills databricks-ai-runtime

=== list help

>>> [CLI] air list --help
Expand Down Expand Up @@ -70,9 +84,9 @@ Global Flags:
=== get help

>>> [CLI] air get --help
Show status, configuration, and timing details for a specified run.
Show a run's status, configuration, and timing.

JOB_RUN_ID is the job run ID returned by "air run".
JOB_RUN_ID is the job run ID returned by "databricks air run".

Usage:
databricks air get JOB_RUN_ID [flags]
Expand All @@ -89,14 +103,18 @@ Global Flags:
=== pools help

>>> [CLI] air pools --help
View provisioned GPU pools
View GPU pools provisioned for your workspace.

A GPU pool is dedicated accelerator capacity that your Databricks account team
provisions. Pools are optional: a run uses one only when its YAML sets
compute.pool_id.

Usage:
databricks air pools [flags]
databricks air pools [command]

Available Commands:
get Show a GPU pool, including its accelerator usage (POOL_ID may be omitted when the workspace has exactly one pool)
get Show a GPU pool and its accelerator usage
list List the GPU pools available to the current workspace

Flags:
Expand All @@ -113,7 +131,7 @@ Use "databricks air pools [command] --help" for more information about a command
=== images help

>>> [CLI] air images --help
Manage container images for AI Runtime
Push container images for custom environments

Usage:
databricks air images [flags]
Expand Down Expand Up @@ -173,7 +191,7 @@ Global Flags:
Stream logs from an active run until it completes, or fetch logs from a
completed run.

JOB_RUN_ID is the job run ID returned by "air run".
JOB_RUN_ID is the job run ID returned by "databricks air run".

Usage:
databricks air logs JOB_RUN_ID [flags]
Expand Down
2 changes: 1 addition & 1 deletion acceptance/help/output.txt
Original file line number Diff line number Diff line change
Expand Up @@ -181,7 +181,7 @@ Domains
domains *Beta* Manage domains for organizing and discovering data assets.

Developer Tools
air Run and manage AI Runtime training workloads
air Run and manage AI Runtime workloads on serverless GPU compute
bundle Declarative Automation Bundles let you express data/AI/analytics projects as code.
sandbox *Beta* Manage Databricks Sandbox environments
sync Synchronize a local directory to a workspace directory
Expand Down
Loading
Loading