air command group

Preview

This feature is in Public Preview.

The air command group within the Databricks CLI submits and manages AI Runtime training workloads. For requirements and usage guidance, see Use the Databricks CLI with AI Runtime. To submit your first workload, see Databricks CLI quickstart for AI Runtime.

For the complete command and configuration reference, use the CLI help:

Bash

databricks air --help                  # All commands
databricks air <command> --help        # Flags for a specific command
databricks air run -h config           # YAML config reference
databricks air run -h config.compute   # Per-field help for a YAML section

The CLI help reflects the exact version you have installed. Configuration help is generated from the validation schema, so use it to check field types, requirements, and constraints.

Commands

Command	Purpose
databricks air run	Submit a training workload from a YAML config. Supports -f (--file), --watch, --dry-run, repeatable --override flags, and --idempotency-key.
databricks air get <run-id>	Show status, configuration, and timing details for a specified run.
databricks air list	List active runs for the current user. Use --all-status to include completed runs, --all-users to include other users, and --limit to set the result count (default 20). Repeat --filter KEY=VALUE to filter by accelerator_type, experiment, num_accelerators, or user.
databricks air logs <run-id>	Stream logs from an active run or fetch logs from a completed run. Use --node to select a node, --retry to select an attempt, and --download-to to download complete logs.
databricks air cancel <run-id> [<run-id> ...]	Cancel one or more runs. Use --all to cancel your active runs. --all prompts for confirmation unless you pass --yes.
databricks air convert-to-dabs <yaml-path>	Convert workload YAML to Declarative Automation Bundles locally, without contacting the workspace. Use --output-dir to select the bundle directory and --force to overwrite generated files.

Command	Purpose
databricks air run	Submit a training workload from a YAML config. Supports -f (--file), --watch, --dry-run, repeatable --override flags, and --idempotency-key.
databricks air get <run-id>	Show status, configuration, and timing details for a specified run.
databricks air list	List active runs for the current user. Use --all-status to include completed runs, --all-users to include other users, and --limit to set the result count (default 20). Repeat --filter KEY=VALUE to filter by accelerator_type, experiment, num_accelerators, or user.
databricks air logs <run-id>	Stream logs from an active run or fetch logs from a completed run. Use --node to select a node, --retry to select an attempt, and --download-to to download complete logs.
databricks air cancel <run-id> [<run-id> ...]	Cancel one or more runs. Use --all to cancel your active runs. --all prompts for confirmation unless you pass --yes.
databricks air convert-to-dabs <yaml-path>	Convert workload YAML to Declarative Automation Bundles locally, without contacting the workspace. Use --output-dir to select the bundle directory and --force to overwrite generated files.

databricks air run -f train.yaml --dry-run validates the YAML schema and overrides locally without submitting a workload or requiring authentication. It does not check whether local code paths or Git revisions exist, or validate workspace permissions or GPU availability.

For logs, use either --tail to select a line count or --minutes to select a time window. These flags are mutually exclusive and cannot be combined with --download-to.

Global flags

Flag	Purpose
-p, --profile	Use the named Databricks CLI authentication profile instead of the default.
--debug	Enable debug logging.
-o, --output	Select the output format: text or json. The default is text.
-t, --target	Select the bundle target, if applicable.

Flag	Purpose
-p, --profile	Use the named Databricks CLI authentication profile instead of the default.
--debug	Enable debug logging.
-o, --output	Select the output format: text or json. The default is text.
-t, --target	Select the bundle target, if applicable.

Use -h or --help on a command to show its help. To show YAML field help, use databricks air run -h config.<section>.

Differences from the legacy Python CLI

The Databricks CLI and the legacy Python-based air CLI use different command names and flags. Update scripts using the following mappings:

Python CLI	Databricks CLI
air run -f train.yaml	databricks air run -f train.yaml
air run -f train.yaml --override A=X B=Y	databricks air run -f train.yaml --override A=X --override B=Y
air get run <run-id>	databricks air get <run-id>
air list runs	databricks air list --all-status
air list runs --active	databricks air list
air -h config	databricks air run -h config
air logs <run-id>	databricks air logs <run-id>
air cancel <run-id>	databricks air cancel <run-id>

Python CLI	Databricks CLI
air run -f train.yaml	databricks air run -f train.yaml
air run -f train.yaml --override A=X B=Y	databricks air run -f train.yaml --override A=X --override B=Y
air get run <run-id>	databricks air get <run-id>
air list runs	databricks air list --all-status
air list runs --active	databricks air list
air -h config	databricks air run -h config
air logs <run-id>	databricks air logs <run-id>
air cancel <run-id>	databricks air cancel <run-id>

Additional resources

• Databricks CLI quickstart for AI Runtime
• Workload YAML reference
• Track runs with MLflow and the Jobs run page