Skip to content

[air] Reorganize databricks air help around the run lifecycle - #7512

Merged
stevenchen-db merged 12 commits into
mainfrom
schen/air-help-revamp
Nov 12, 2026
Merged

stevenchen-db merged 12 commits into
mainfrom
schen/air-help-revamp

Conversation

@stevenchen-db

@stevenchen-db stevenchen-db commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Changes

Reorganize the databricks air help pages around the run lifecycle:

  • air -h: subcommands are grouped under Run workloads, Manage runs, Package and deploy, and Provisioned capacity instead of one A→Z list. Adds a two-line intro and a "Learn more" footer (YAML fields and example, AWS/Azure quickstart, agent skill). Drops "under active development" (air: remove stale Public Preview label from CLI help #7502 already removed the "Public Preview" label).
  • air run -h: adds Examples (--watch, --dry-run, --override) and lists flags most-used first.
  • air run -h config: adds a minimal YAML example and lists fields by purpose under Workload / Execution / MLflow tracking / Access and cost attribution, using a new group struct tag. Required fields come first in each group and are marked inline. The agent-skill instructions move below the field list, and the air -h footer also points to the skill.
  • air run -h config.compute: pool_id and priority_class move under "Provisioned capacity (optional)".
  • Required markers now match validation: command shows "(required unless containers is set)", compute.num_accelerators / compute.accelerator_type are marked required (they previously showed Required: no), and conditional requirements show inline, e.g. code_source.root_path "(required when code_source is set)".
  • environment.version help gives examples of both forms (6, databricks_ai_v6), says what the Standard and Databricks AI environments contain, and links the AI Runtime environment page (which lists supported versions) instead of the general serverless release notes.
  • Field help lists docs links for both AWS and Azure in a "Docs:" section (new docs struct tag with the path both clouds share) instead of AWS-only inline links. Applies to environment.version, compute.num_accelerators, and compute.accelerator_type.
  • Field-help hints are full commands (databricks air run -h config.compute.accelerator_type) instead of bare paths.
  • Wording pass on short descriptions ("workload", not "training workload"; "AI Runtime", not "AIR"; YAML_PATH; shorter pools get), help text names full commands (databricks air run, not air run), and usage-policy help says "attribute the run's usage to" instead of "bill the run to", matching the usage-policy docs.

Before / after

Taken from the acceptance golden files; the GPU list in config.compute comes from the test stub. Global Flags are unchanged and omitted.

databricks air -h

Before

Run and manage AI Runtime training workloads on Databricks serverless GPU compute.

These commands are under active development.

Usage:
  databricks air [command]

Available Commands:
  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

Flags:
  -h, --help   help for air

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

After

Run GPU workloads on Databricks serverless compute.

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]

Run workloads:
  run             Submit a workload from a YAML config

Manage runs:
  cancel          Cancel one or more runs
  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

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
databricks air run -h

Before

Submit a training workload to Databricks serverless GPU compute.

The workload is described by a YAML config file (see --file).

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.

Usage:
  databricks air run [flags]

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

After

Submit a workload to Databricks serverless GPU compute.

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:

  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:
  -f, --file string              Path to the workload YAML config
      --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
databricks air run -h config

Before

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.

  Install the skill locally for your coding agent:

    databricks aitools install --skills-only --skills databricks-ai-runtime

  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:
    experiment_name              (required) Name of the experiment.
    compute                      (required) Which accelerators to run on and how many.
    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.
    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_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.
    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.

Use "-h config.<field>" for details on a field.

After

config
  Workload YAML schema. For details on a field, pass its path to -h, for example:

    databricks air run -h config.compute.accelerator_type

  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"

  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.
    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.

  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 attribute the run's usage to, by name.
    usage_policy_id              Usage policy to attribute the run's usage to, by id.

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
databricks air run -h config.compute

Before

config.compute
  Which accelerators to run on and how many.

  Supported accelerator types:
    GPU_1xH100 - 1 accelerator per node
    GPU_8xH100 - 8 accelerators per node
    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.
    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.

After

config.compute
  Which accelerators to run on and how many.

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

  Fields:
    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.

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

Before

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/

  Type:     string or int
  Required: no

After

config.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

Why

New users read pools and pool_id as prerequisites because they sit next to run and accelerator_type. The top-level help also listed commands A→Z, so run came last, and the YAML field list was one flat list.

Tests

  • New unit tests for command grouping, the footer appearing only on air -h, config field headings and order, required-first ordering, the inline required markers, and the per-cloud Docs section (plus a check that no field help inlines a docs link).
  • Regenerated acceptance/air/help, acceptance/air/config-help, and acceptance/help outputs.
  • ./task fmt, ./task checks, ./task lint pass.
  • Checked environment.version values with real runs: 4, 5, 6, databricks_ai_v5, and databricks_ai_v6 run; 1-3 fail at runtime ("client image version must be between 4 and 6"), and 7 and databricks_ai_v7 are rejected at submit.
  • Checked the Required markers against a real workspace: omitting each required field fails --dry-run with the matching error, a run with only experiment_name, compute, and command succeeds, and both YAML examples shown in the help run successfully.

This pull request and its description were written by Isaac.

@stevenchen-db
stevenchen-db requested review from a team as code owners November 11, 2026 20:47
@github-actions github-actions Bot added the AIR Databricks AI Runtime CLI label Nov 11, 2026
@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Commit: 0415eb22c | Workflow run

Regression test report

Selected 3 changed tests (limit=20, 0 not selected)

3 tests: regression=3 unreleased=0 coverage=0 failing=0
test branch main (a0a6430) latest (v1.26.0)
TestAccept/air/config-help ✅ ❌ ❌
TestAccept/air/help ✅ ❌ ❌
TestAccept/help ✅ ❌ ❌
TestAccept/air/config-help: branch ✅ | main (a0a6430) ❌ | latest (v1.26.0) ❌

main (a0a6430):

acceptance_test.go:1345: Diff:
        --- air/config-help/output.txt
        +++ /tmp/TestAcceptairconfig-help273443382/002/output.txt
        @@ -2,35 +2,29 @@
         === command help
         
         >>> [CLI] air run --help
        -Submit a workload to Databricks serverless GPU compute.
        +Submit a training workload to Databricks serverless GPU compute.
         
        -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:
        +The workload is described by a YAML config file (see --file).
         
        -  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
        +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.
        +
         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:
        -  -f, --file string              Path to the workload YAML config
        -      --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
        +  -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
         
         Global Flags:
               --debug            enable debug logging
        @@ -42,52 +27,41 @@
         
         >>> [CLI] air run -h config
         config
        -  Workload YAML schema. For details on a field, pass its path to -h, for example:
        +  The run YAML schema. Pass a field path for details, e.g. config.compute.accelerator_type.
         
        -    databricks air run -h config.compute.accelerator_type
        +  AI coding agents can use the databricks-ai-runtime skill to write workload
        +  YAML, submit runs, and monitor progress.
         
        -  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"
        +  Install the skill locally for your coding agent:
         
        -  Workload:
        +    databricks aitools install --skills-only --skills databricks-ai-runtime
        +
        +  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:
             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.
        -
        -  MLflow tracking:
        +    parameters                   Free-form values passed through to the workload.
             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 attribute the run's usage to, by name.
        -    usage_policy_id              Usage policy to attribute the run's usage to, by id.
        +    usage_policy_name            Usage policy to bill the run to, by name.
        +    usage_policy_id              Usage policy to bill the run to, by id.
         
        -For details on a field, run "databricks air run -h config.<field>".
        +Use "-h config.<field>" for details on a 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
         
         >>> [CLI] air run -h config.compute
        @@ -100,14 +55,12 @@
             GPU_1xRTX6000 - 1 accelerator per node
         
           Fields:
        -    num_accelerators  (required) Total number of GPUs to allocate.
        -    accelerator_type  (required) Which accelerator to run on, e.g. GPU_1xA10.
        -
        -  Provisioned capacity (optional):
        +    num_accelerators  Total number of GPUs to allocate.
        +    accelerator_type  Which accelerator to run on, e.g. GPU_1xA10.
             pool_id           GPU pool to run on, by id.
             priority_class    Scheduling priority within the pool: BEST_EFFORT (lowest, preemptable) or NORMAL.
         
        -For details on a field, run "databricks air run -h config.compute.<field>".
        +Use "-h config.compute.<field>" for details on a field.
         
         === new submission fields are documented
         
        @@ -120,7 +70,7 @@
         
         >>> [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 'databricks 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 'air pools list'.
         
           Type:     string
           Required: no
        @@ -141,12 +91,8 @@
         
         >>> [CLI] air run -h config.environment.version
         config.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.
        +  Client image version to pin (default: 6). See environment version release notes: https://docs.databricks.com/aws/en/release-notes/serverless/environment-version/
         
        -  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
         
        @@ -154,19 +99,15 @@
         
         >>> [CLI] air run -h config.compute.accelerator_type
         config.compute.accelerator_type
        -  Which accelerator to run on, e.g. GPU_1xA10. Matched case-sensitively.
        +  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.
         
           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: yes
        +  Required: no
         
         === code source fields
         
        @@ -175,12 +109,12 @@
           Local code to upload and make available to the run.
         
           Fields:
        -    root_path      (required when code_source is set) Root of the code source to archive.
        +    root_path      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 "..".
         
        -For details on a field, run "databricks air run -h config.code_source.<field>".
        +Use "-h config.code_source.<field>" for details on a field.
         
         === union field
         
... (19 more lines truncated, raise DATABRICKS_CLI_TEST_MAX_LOG to see more)

latest (v1.26.0): same output as main (a0a6430)

TestAccept/air/help: branch ✅ | main (a0a6430) ❌ | latest (v1.26.0) ❌

main (a0a6430):

acceptance_test.go:1345: Diff:
        --- air/help/output.txt
        +++ /tmp/TestAcceptairhelp3365382524/002/output.txt
        @@ -2,31 +2,23 @@
         === help
         
         >>> [CLI] air --help
        -Run GPU workloads on Databricks serverless compute.
        +Run and manage AI Runtime training workloads on Databricks serverless GPU compute.
         
        -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".
        +These commands are under active development.
         
         Usage:
           databricks air [command]
         
        -Run workloads:
        -  run             Submit a workload from a YAML config
        -
        -Manage runs:
        +Available Commands:
           cancel          Cancel one or more runs
        -  get             Show a run's status, configuration, and timing
        -  list            List your active runs
        -  logs            Stream or fetch a run's logs
        +  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
         
        -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
         
        @@ -38,12 +23,6 @@
         
         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
        @@ -84,9 +63,9 @@
         === get help
         
         >>> [CLI] air get --help
        -Show a run's status, configuration, and timing.
        +Show status, configuration, and timing details for a specified run.
         
        -JOB_RUN_ID is the job run ID returned by "databricks air run".
        +JOB_RUN_ID is the job run ID returned by "air run".
         
         Usage:
           databricks air get JOB_RUN_ID [flags]
        @@ -103,18 +81,14 @@
         === pools help
         
         >>> [CLI] air pools --help
        -View GPU pools provisioned for your workspace.
        +View provisioned GPU pools
         
        -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 and its accelerator usage
        +  get         Show a GPU pool, including its accelerator usage (POOL_ID may be omitted when the workspace has exactly one pool)
           list        List the GPU pools available to the current workspace
         
         Flags:
        @@ -131,7 +99,7 @@
         === images help
         
         >>> [CLI] air images --help
        -Push container images for custom environments
        +Manage container images for AI Runtime
         
         Usage:
           databricks air images [flags]
        @@ -191,7 +159,7 @@
         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 "databricks air run".
        +JOB_RUN_ID is the job run ID returned by "air run".
         
         Usage:
           databricks air logs JOB_RUN_ID [flags]

latest (v1.26.0): same output as main (a0a6430)

TestAccept/help: branch ✅ | main (a0a6430) ❌ | latest (v1.26.0) ❌

main (a0a6430):

acceptance_test.go:1345: Diff:
        --- help/output.txt
        +++ /tmp/TestAccepthelp2288283559/002/output.txt
        @@ -181,7 +181,7 @@
           domains                                *Beta* Manage domains for organizing and discovering data assets.
         
         Developer Tools
        -  air                                    Run and manage AI Runtime workloads on serverless GPU compute
        +  air                                    Run and manage AI Runtime training workloads
           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

latest (v1.26.0):

acceptance_test.go:1345: Diff:
        --- help/output.txt
        +++ /tmp/TestAccepthelp2134631048/002/output.txt
        @@ -181,7 +181,7 @@
           domains                                *Beta* Manage domains for organizing and discovering data assets.
         
         Developer Tools
        -  air                                    Run and manage AI Runtime workloads on serverless GPU compute
        +  air                                    *Public Preview* Run and manage AI Runtime training workloads
           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

@ben-hansen-db ben-hansen-db left a comment

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.

This reorg is great, thanks for putting this up. We should fyi Maggie or Caroline

In your config.compute example it seems that A10 are missing, is that intentional?

Comment thread acceptance/air/config-help/output.txt Resolved
Comment thread acceptance/air/config-help/output.txt Outdated
root_path: .
command: python "$CODE_SOURCE_PATH/train.py"

Required:

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.

nice I like this organization

@eng-dev-ecosystem-bot

eng-dev-ecosystem-bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator

✅ Integration test report

Commit: 0415eb2

Run: 43153306909

Env 💚​RECOVERED ✅​pass 🙈​skip Time
💚​ aws linux-2core-8gb 1 270 18 5:16
💚​ aws-windows-latest-4core-16gb 1 272 16 4:05
💚​ azure linux-2core-8gb 1 269 18 5:00
💚​ azure-windows-latest-4core-16gb 1 271 16 3:36
💚​ gcp linux-2core-8gb 1 270 18 5:00
💚​ gcp-windows-latest-4core-16gb 1 272 16 4:00
Test Name aws linux-2core-8gb aws-windows-latest-4core-16gb azure linux-2core-8gb azure-windows-latest-4core-16gb gcp linux-2core-8gb gcp-windows-latest-4core-16gb
💚​ TestAccept 💚​R 💚​R 💚​R 💚​R 💚​R 💚​R
Top 6 slowest tests (at least 2 minutes):
duration env testname
4:02 aws linux-2core-8gb TestAccept
4:00 aws-windows-latest-4core-16gb TestAccept
3:57 azure linux-2core-8gb TestAccept
3:55 gcp-windows-latest-4core-16gb TestAccept
3:55 gcp linux-2core-8gb TestAccept
3:32 azure-windows-latest-4core-16gb TestAccept

@ben-hansen-db ben-hansen-db left a comment

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.

re-stamp

Comment thread acceptance/air/help/output.txt Outdated
Describe a workload in a YAML file, submit it with "air run", then follow it
with "air list", "air get", and "air logs".

Get started:

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.

imo this feels a bit long to be including at the top of every --help

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

agreed. just updated

@caroline-db caroline-db left a comment

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.

overall looks good, left a couple small comments/suggestions. thanks for this!

Comment thread cmd/air/air.go Outdated
&cobra.Group{ID: runGroupID, Title: "Run workloads:"},
&cobra.Group{ID: manageGroupID, Title: "Manage runs:"},
&cobra.Group{ID: packageGroupID, Title: "Package and deploy:"},
&cobra.Group{ID: capacityGroupID, Title: "Provisioned capacity (optional):"},

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 find the use of (optional) here to be confusing, since we aren't explicitly classifying other groups as required/optional. was the intent because it's not a GA feature or something else?

(I think the use of provisioned capacity (optional) inside the compute help where we did use (required) for accelerator_type/num_accelerators works there though)

Comment thread cmd/air/runconfig.go Outdated
type environmentConfig struct {
Dependencies dependencies `yaml:"dependencies" help:"Inline list of packages to install. Not allowed alongside unity_catalog_image."`
Version stringOrInt `yaml:"version" help:"Client image version to pin (default: 6). See environment version release notes: https://docs.databricks.com/aws/en/release-notes/serverless/environment-version/"`
Version stringOrInt `yaml:"version" help:"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. Supported versions and package lists: https://docs.databricks.com/aws/en/machine-learning/ai-runtime/develop-workloads/environment"`

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.

we should include the azure link here as well

Comment thread cmd/air/runconfig.go
@@ -53,26 +53,26 @@ var secretTemplateRe = sync.OnceValue(func() *regexp.Regexp { return regexp.Must
// runConfig is the top-level run YAML schema: experiment_name + compute /
// environment / code_source plus the command and run options.
type runConfig struct {

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 like introducing sections, it makes it clearer. here's another variant that I think is even easier to read, thoughts? It organizes by purpose instead of making required a separate section and advanced a catch-all, plus slight section renaming.

Workload:
  experiment_name (required)
  compute (required)
  command (required)
  environment
  code_source
  env_variables
  secrets
  parameters
  containers

Execution:
  max_retries
  timeout_minutes
  idempotency_token

MLflow tracking:
  mlflow_run_name
  mlflow_experiment_directory
  mlflow_artifact_location

Access and billing:
  permissions
  usage_policy_name
  usage_policy_id

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Makes sense! I switched billing to cost attribution as that seems to be more aligned with how we usually describe usage policy

stevenchen-db and others added 11 commits November 12, 2026 04:03
Group `air` subcommands by task (run, manage, package, provisioned
capacity), add a get-started example and a "Learn more" footer, add
examples to `air run`, and list YAML fields under headings so required
and common fields come before advanced and pool-only ones.

Co-authored-by: Isaac <no-reply@databricks.com>
Co-authored-by: Isaac <no-reply@databricks.com>
`command` is required unless `containers` is set, and
`compute.num_accelerators` / `compute.accelerator_type` are always
required, matching what validation enforces.

Co-authored-by: Isaac <no-reply@databricks.com>
Co-authored-by: Isaac <no-reply@databricks.com>
Co-authored-by: Isaac <no-reply@databricks.com>
Name the values that run (4-6, databricks_ai_v5, databricks_ai_v6),
what the Standard and Databricks AI environments contain, and link the
AI Runtime environment page instead of the general serverless notes.

Co-authored-by: Isaac <no-reply@databricks.com>
Co-authored-by: Isaac <no-reply@databricks.com>
The supported set changes with each environment release; the linked
page stays current.

Co-authored-by: Isaac <no-reply@databricks.com>
It pushed the command list down; `air run -h config` already has a
minimal example and the footer points to it.

Co-authored-by: Isaac <no-reply@databricks.com>
A bare "air run" reads like a standalone binary. Also point to logs and
get before list in the intro, since following a submitted run comes first.

Co-authored-by: Isaac <no-reply@databricks.com>
Workload / Execution / MLflow tracking / Access and cost attribution,
with required fields leading their group and marked inline instead of a
separate Required heading. Drop "(optional)" from the `air -h` pools
group; it stays in `config.compute` next to the required fields.

Co-authored-by: Isaac <no-reply@databricks.com>
A `docs` struct tag holds the page path shared by both clouds, so field
help stays short and no longer links only to AWS.

Co-authored-by: Isaac <no-reply@databricks.com>
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

@stevenchen-db
stevenchen-db added this pull request to the merge queue Nov 12, 2026
Merged via the queue into main with commit 87716ec Nov 12, 2026
28 checks passed
@eng-dev-ecosystem-bot

Copy link
Copy Markdown
Collaborator

❌ Integration test report

Commit: 87716ec

Run: 43285843501

Env ❌​FAIL 🤯​MISS 💚​RECOVERED ✅​pass 🙈​skip Time
❌​ aws linux-2core-8gb 59 423 11 1054 1284 355:27
❌​ aws-windows-latest-4core-16gb 39 470 8 949 1311 347:29
❌​ azure linux-2core-8gb 2 682 8 835 1292 354:53
❌​ azure-windows-latest-4core-16gb 37 593 11 805 1319 346:58
🤯​ gcp linux-2core-8gb 661 8 865 1290 355:32
❌​ gcp-windows-latest-4core-16gb 5 533 8 907 1317 348:22
1083 interesting tests: 995 MISS, 80 FAIL, 8 RECOVERED
Test Name aws linux-2core-8gb aws-windows-latest-4core-16gb azure linux-2core-8gb azure-windows-latest-4core-16gb gcp linux-2core-8gb gcp-windows-latest-4core-16gb
🤯​ TestAccept 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/apps/job_permissions 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/apps/job_permissions/DMS= 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/apps/job_permissions/DMS=true 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/artifacts/artifact_path_with_volume/volume_doesnot_exist 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/artifacts/artifact_path_with_volume/volume_doesnot_exist/DMS= 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/artifacts/artifact_path_with_volume/volume_doesnot_exist/DMS=true 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/artifacts/artifact_path_with_volume/volume_not_deployed 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/artifacts/artifact_path_with_volume/volume_not_deployed/DMS= 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/artifacts/artifact_path_with_volume/volume_not_deployed/DMS=true 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/config-remote-sync/cli_defaults 🤯​M 🙈​s 🤯​M 🙈​s 🤯​M 🙈​s
🤯​ TestAccept/bundle/config-remote-sync/cli_defaults/DMS= 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/cli_defaults/DMS=true 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/cluster_policy_cross_target 🤯​M 🙈​s 🤯​M 🙈​s 🤯​M 🙈​s
🤯​ TestAccept/bundle/config-remote-sync/cluster_policy_cross_target/DMS= 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/cluster_policy_cross_target/DMS=true 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/cluster_policy_remote_addition 🤯​M 🙈​s 🤯​M 🙈​s 🤯​M 🙈​s
🤯​ TestAccept/bundle/config-remote-sync/cluster_policy_remote_addition/DMS= 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/cluster_policy_remote_addition/DMS=true 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/config_edits 🤯​M 🙈​s 🤯​M 🙈​s 🤯​M 🙈​s
🤯​ TestAccept/bundle/config-remote-sync/config_edits/DMS= 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/config_edits/DMS=true 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/dashboard_etag 🤯​M 🙈​s 🤯​M 🙈​s 🤯​M 🙈​s
🤯​ TestAccept/bundle/config-remote-sync/dashboard_etag/DMS= 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/dashboard_etag/DMS=true 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/external_cluster_policy_cross_target 🤯​M 🙈​s 🤯​M 🙈​s 🤯​M 🙈​s
🤯​ TestAccept/bundle/config-remote-sync/external_cluster_policy_cross_target/DMS= 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/external_cluster_policy_cross_target/DMS=true 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/flushed_cache 🤯​M 🙈​s 🤯​M 🙈​s 🤯​M 🙈​s
🤯​ TestAccept/bundle/config-remote-sync/flushed_cache/DMS= 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/flushed_cache/DMS=true 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/formatting_preserved 🤯​M 🙈​s 🤯​M 🙈​s 🤯​M 🙈​s
🤯​ TestAccept/bundle/config-remote-sync/formatting_preserved/DMS= 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/formatting_preserved/DMS=true 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/job_fields 🤯​M 🙈​s 🤯​M 🙈​s 🤯​M 🙈​s
🤯​ TestAccept/bundle/config-remote-sync/job_fields/DMS= 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/job_fields/DMS=true 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/job_multiple_tasks 🤯​M 🙈​s 🤯​M 🙈​s 🤯​M 🙈​s
🤯​ TestAccept/bundle/config-remote-sync/job_multiple_tasks/DMS= 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/job_multiple_tasks/DMS=true 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/job_params_variables 🤯​M 🙈​s 🤯​M 🙈​s 🤯​M 🙈​s
🤯​ TestAccept/bundle/config-remote-sync/job_params_variables/DMS= 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/job_params_variables/DMS=true 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/job_pipeline_task 🤯​M 🙈​s 🤯​M 🙈​s 🤯​M 🙈​s
🤯​ TestAccept/bundle/config-remote-sync/job_pipeline_task/DMS= 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/job_pipeline_task/DMS=true 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/json_status_missing_state 🤯​M 🙈​s 🤯​M 🙈​s 🤯​M 🙈​s
🤯​ TestAccept/bundle/config-remote-sync/json_status_missing_state/DMS= 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/json_status_missing_state/DMS=true 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/json_status_selectors 🤯​M 🙈​s 🤯​M 🙈​s 🤯​M 🙈​s
🤯​ TestAccept/bundle/config-remote-sync/json_status_selectors/DMS= 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/json_status_selectors/DMS=true 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/multiple_files 🤯​M 🙈​s 🤯​M 🙈​s 🤯​M 🙈​s
🤯​ TestAccept/bundle/config-remote-sync/multiple_files/DMS= 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/multiple_files/DMS=true 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/multiple_resources 🤯​M 🙈​s 🤯​M 🙈​s 🤯​M 🙈​s
🤯​ TestAccept/bundle/config-remote-sync/multiple_resources/DMS= 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/multiple_resources/DMS=true 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/output_json 🤯​M 🙈​s 🤯​M 🙈​s 🤯​M 🙈​s
🤯​ TestAccept/bundle/config-remote-sync/output_json/DMS= 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/output_json/DMS=true 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/output_no_changes 🤯​M 🙈​s 🤯​M 🙈​s 🤯​M 🙈​s
🤯​ TestAccept/bundle/config-remote-sync/output_no_changes/DMS= 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/output_no_changes/DMS=true 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/pipeline_fields 🤯​M 🙈​s 🤯​M 🙈​s 🤯​M 🙈​s
🤯​ TestAccept/bundle/config-remote-sync/pipeline_fields/DMS= 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/pipeline_fields/DMS=true 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/policy_injected_cluster_fields 🤯​M 🙈​s 🤯​M 🙈​s 🤯​M 🙈​s
🤯​ TestAccept/bundle/config-remote-sync/policy_injected_cluster_fields/DMS= 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/policy_injected_cluster_fields/DMS=true 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/resolve_variables 🤯​M 🙈​s 🤯​M 🙈​s 🤯​M 🙈​s
🤯​ TestAccept/bundle/config-remote-sync/resolve_variables/DMS= 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/resolve_variables/DMS=true 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/select_basic 🤯​M 🙈​s 🤯​M 🙈​s 🤯​M 🙈​s
🤯​ TestAccept/bundle/config-remote-sync/select_basic/DMS= 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/select_basic/DMS=true 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/select_multiple 🤯​M 🙈​s 🤯​M 🙈​s 🤯​M 🙈​s
🤯​ TestAccept/bundle/config-remote-sync/select_multiple/DMS= 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/select_multiple/DMS=true 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/skip_deployment 🤯​M 🙈​s 🤯​M 🙈​s 🤯​M 🙈​s
🤯​ TestAccept/bundle/config-remote-sync/skip_deployment/DMS= 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/skip_deployment/DMS=true 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/skip_permissions 🤯​M 🙈​s 🤯​M 🙈​s 🤯​M 🙈​s
🤯​ TestAccept/bundle/config-remote-sync/skip_permissions/DMS= 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/skip_permissions/DMS=true 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/target_override 🤯​M 🙈​s 🤯​M 🙈​s 🤯​M 🙈​s
🤯​ TestAccept/bundle/config-remote-sync/target_override/DMS= 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/target_override/DMS=true 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/task_rename_revert 🤯​M 🙈​s 🤯​M 🙈​s 🤯​M 🙈​s
🤯​ TestAccept/bundle/config-remote-sync/task_rename_revert/DMS= 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/config-remote-sync/task_rename_revert/DMS=true 🤯​M 🤯​M 🤯​M
🤯​ TestAccept/bundle/debug/fetch-repository-info 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/debug/fetch-repository-info/DMS= 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/debug/fetch-repository-info/DMS=true 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/empty-bundle 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/empty-bundle/DATABRICKS_BUNDLE_ENABLE_EXPERIMENTAL_YAML_SYNC=/DMS= 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/empty-bundle/DATABRICKS_BUNDLE_ENABLE_EXPERIMENTAL_YAML_SYNC=/DMS=true 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/empty-bundle/DATABRICKS_BUNDLE_ENABLE_EXPERIMENTAL_YAML_SYNC=true/DMS= 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/empty-bundle/DATABRICKS_BUNDLE_ENABLE_EXPERIMENTAL_YAML_SYNC=true/DMS=true 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/files/no-snapshot-sync 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/files/no-snapshot-sync/DMS= 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/files/no-snapshot-sync/DMS=true 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/immutable/basic 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/immutable/basic/DMS= 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/immutable/breakglass 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/immutable/breakglass/DMS= 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/immutable/can-manage 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/immutable/can-manage/DMS= 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/immutable/destroy-redeploy 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/immutable/destroy-redeploy/DMS= 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/immutable/dev-mode 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/immutable/dev-mode/DMS= 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/immutable/legacy-state 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/immutable/legacy-state/DMS= 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/immutable/missing-snapshot 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/immutable/missing-snapshot/DMS= 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/immutable/no-artifacts 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/immutable/no-artifacts/DMS=/READPLAN= 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/immutable/no-artifacts/DMS=/READPLAN=1 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/immutable/permissions-change 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/immutable/permissions-change/DMS= 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/immutable/select ✅​p 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/immutable/select/DMS= ✅​p 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/mlops-stacks 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/mlops-stacks/DMS= 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/mlops-stacks/DMS=true 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/spark-jar-task 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/spark-jar-task/DMS= 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deploy/spark-jar-task/DMS=true 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deployment/bind/alert 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deployment/bind/alert/DMS= 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deployment/bind/alert/DMS=true 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deployment/bind/catalog 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deployment/bind/catalog/DMS= 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deployment/bind/catalog/DMS=true 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deployment/bind/cluster 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deployment/bind/cluster/DMS= 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deployment/bind/cluster/DMS=true 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deployment/bind/dashboard 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deployment/bind/dashboard/DMS=/READPLAN= 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deployment/bind/dashboard/DMS=/READPLAN=1 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deployment/bind/dashboard/DMS=true/READPLAN= 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deployment/bind/dashboard/DMS=true/READPLAN=1 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deployment/bind/dashboard/recreation 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deployment/bind/dashboard/recreation/DMS=/READPLAN= 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deployment/bind/dashboard/recreation/DMS=/READPLAN=1 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
🤯​ TestAccept/bundle/deployment/bind/dashboard/recreation/DMS=true/READPLAN= 🤯​M 🤯​M 🤯​M 🤯​M 🤯​M ✅​p
Top 50 slowest tests (at least 2 minutes):
duration env testname
20:27 aws-windows-latest-4core-16gb TestAccept/bundle/resources/clusters/lifecycle-started/DMS=true
20:26 aws-windows-latest-4core-16gb TestAccept/bundle/resources/clusters/deploy/update-after-create/DMS=true
15:12 gcp-windows-latest-4core-16gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=true
15:11 aws linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=
14:09 gcp linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=
14:05 aws linux-2core-8gb TestAccept/bundle/resources/clusters/deploy/update-after-create/DMS=true
13:54 gcp linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=true
13:54 azure-windows-latest-4core-16gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=true
13:23 azure linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=true
12:42 aws-windows-latest-4core-16gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=
12:16 aws-windows-latest-4core-16gb TestAccept/bundle/resources/clusters/lifecycle-started-toggle/DMS=
11:19 gcp-windows-latest-4core-16gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=
11:18 azure-windows-latest-4core-16gb TestAccept/bundle/invariant/delete_idempotent/DMS=/INPUT_CONFIG=cluster_apply_policy_default_values.yml.tmpl/READPLAN=
11:11 azure linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=
10:54 aws-windows-latest-4core-16gb TestAccept/bundle/invariant/no_drift/DMS=true/INPUT_CONFIG=cluster_libraries.yml.tmpl/READPLAN=
10:52 azure linux-2core-8gb TestAccept/bundle/invariant/destroy_idempotent/DMS=/INPUT_CONFIG=cluster_apply_policy_default_values.yml.tmpl/READPLAN=1
10:51 aws linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=true
10:42 gcp-windows-latest-4core-16gb TestAccept/bundle/invariant/delete_idempotent/DMS=/INPUT_CONFIG=cluster_libraries.yml.tmpl/READPLAN=
10:40 gcp linux-2core-8gb TestAccept/bundle/invariant/delete_idempotent/DMS=/INPUT_CONFIG=cluster_apply_policy_default_values.yml.tmpl/READPLAN=
10:39 aws linux-2core-8gb TestAccept/bundle/quiet-levels/DMS=true
10:27 aws-windows-latest-4core-16gb TestAccept/bundle/invariant/no_drift/DMS=true/INPUT_CONFIG=cluster_apply_policy_default_values.yml.tmpl/READPLAN=
10:17 aws-windows-latest-4core-16gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=true
10:07 azure-windows-latest-4core-16gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=
9:56 aws-windows-latest-4core-16gb TestAccept/bundle/invariant/no_drift/DMS=true/INPUT_CONFIG=cluster.yml.tmpl/READPLAN=1
9:38 aws-windows-latest-4core-16gb TestAccept/bundle/resources/clusters/resize-terminated-fallback/DMS=true
9:36 azure linux-2core-8gb TestAccept/bundle/invariant/delete_idempotent/DMS=/INPUT_CONFIG=vector_search_endpoint.yml.tmpl/READPLAN=1
9:35 azure linux-2core-8gb TestAccept/bundle/invariant/delete_idempotent/DMS=/INPUT_CONFIG=schema_tf_compat.yml.tmpl/READPLAN=1
9:32 aws linux-2core-8gb TestAccept/bundle/templates/default-python/combinations/classic/DLT=yes/DMS=/NBOOK=yes/PY=no/READPLAN=1
9:29 aws linux-2core-8gb TestAccept/bundle/resources/clusters/deploy/simple/DMS=
9:23 gcp-windows-latest-4core-16gb TestAccept/bundle/invariant/delete_idempotent/DMS=/INPUT_CONFIG=vector_search_index.yml.tmpl/READPLAN=1
9:14 aws-windows-latest-4core-16gb TestAccept/bundle/invariant/no_drift/DMS=true/INPUT_CONFIG=cluster.yml.tmpl/READPLAN=
9:09 aws-windows-latest-4core-16gb TestAccept/bundle/resources/clusters/lifecycle-started-toggle/DMS=true
9:06 gcp-windows-latest-4core-16gb TestAccept/bundle/resources/apps/lifecycle-started-omitted/DMS=
9:05 gcp-windows-latest-4core-16gb TestAccept/bundle/resources/clusters/deploy/local_ssd_count/DMS=
9:04 aws linux-2core-8gb TestAccept/bundle/resources/clusters/deploy/simple/DMS=true
8:50 aws linux-2core-8gb TestAccept/bundle/quiet-levels/DMS=
8:47 gcp linux-2core-8gb TestAccept/bundle/invariant/delete_idempotent/DMS=/INPUT_CONFIG=schema_tf_compat.yml.tmpl/READPLAN=
8:37 gcp-windows-latest-4core-16gb TestAccept/bundle/invariant/delete_idempotent/DMS=/INPUT_CONFIG=job_escaped_refs.yml.tmpl/READPLAN=1
8:36 azure-windows-latest-4core-16gb TestAccept/bundle/resources/clusters/lifecycle-started/DMS=true
8:32 gcp-windows-latest-4core-16gb TestAccept/bundle/invariant/delete_idempotent/DMS=/INPUT_CONFIG=cluster_apply_policy_default_values.yml.tmpl/READPLAN=1
8:31 azure linux-2core-8gb TestAccept/bundle/invariant/destroy_idempotent/DMS=/INPUT_CONFIG=cluster_apply_policy_default_values.yml.tmpl/READPLAN=
8:27 aws-windows-latest-4core-16gb TestAccept/bundle/invariant/no_drift/DMS=/INPUT_CONFIG=cluster_apply_policy_default_values.yml.tmpl/READPLAN=1
8:26 aws linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started-omitted/DMS=true
8:25 azure linux-2core-8gb TestAccept/bundle/invariant/delete_idempotent/DMS=/INPUT_CONFIG=pipeline.yml.tmpl/READPLAN=
8:24 gcp linux-2core-8gb TestAccept/bundle/invariant/delete_idempotent/DMS=/INPUT_CONFIG=job_with_depends_on.yml.tmpl/READPLAN=1
8:18 aws-windows-latest-4core-16gb TestAccept/bundle/invariant/no_drift/DMS=/INPUT_CONFIG=cluster.yml.tmpl/READPLAN=1
8:16 azure linux-2core-8gb TestAccept/bundle/invariant/delete_idempotent/DMS=/INPUT_CONFIG=vector_search_index.yml.tmpl/READPLAN=
8:15 aws-windows-latest-4core-16gb TestAccept/bundle/resources/clusters/resize-terminated-fallback/DMS=
8:15 gcp-windows-latest-4core-16gb TestAccept/bundle/resources/clusters/lifecycle-started/DMS=true
8:12 gcp linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started-omitted/DMS=true
(936 table rows omitted to keep the report under 60000 bytes)

idelafuente-oc pushed a commit to idelafuente-oc/cli that referenced this pull request Nov 14, 2026
## Changes
Follow-up to databricks#7512: `databricks air -h` describes `pools` as optional.

```diff
 Provisioned capacity:
-  pools           View GPU pools provisioned for your workspace
+  pools           View provisioned GPU pools, if any (not required to run)
```

## Why
Few workspaces have GPU pools, and the old line read as something every
workspace has or needs before running.

## Tests
- Regenerated `acceptance/air/help`; all `air` acceptance tests and
`acceptance/help` pass.
- `./task checks` and lint pass.

This pull request and its description were written by Isaac.

---------

Co-authored-by: Isaac <no-reply@databricks.com>
idelafuente-oc pushed a commit to idelafuente-oc/cli that referenced this pull request Nov 16, 2026
…bricks#7652)

Replaces databricks#7628, which was opened from a fork and couldn't run CI. Same
change, rebased on `main`.

## Changes
`databricks air run --help` now names the databricks-ai-runtime agent
skill and gives the install command, below the `-h config` lookup lines:

```
  databricks air run -h config.compute.accelerator_type   one field

To have a coding agent write the YAML and follow the run, install the
databricks-ai-runtime skill:

  databricks aitools install --skills-only --skills databricks-ai-runtime
```

- The install command is now a constant, `skillInstallCommand`, in
`cmd/air/runconfig.go`. The `-h config` skill note uses it as well.
- The `air -h` footer in `cmd/air/air.go` still has its own copy of the
command. I left that file alone because databricks#7622 edits the same footer. It
can move to the constant after that PR lands.

## Why
Coding agents read `air run --help` right before they write a workload
YAML, so this page should point to the skill.
- On v1.26.0 the skill appears only in `air run -h config`.
- On `main`, databricks#7512 added it to the `air -h` footer too. `air run --help`
still doesn't mention it.
- databricks#7622 makes the install hint name this skill on air subcommands. That
hint runs from `PersistentPreRunE`, and cobra doesn't run that for
`--help`. Help text is the only way to show the skill on help pages.

## Tests
- New unit test `TestRunHelpPointsToAgentSkill` in
`cmd/air/air_test.go`.
- Regenerated `acceptance/air/config-help/output.txt` with `-update`.
The only diff is the 5 new lines in `air run --help`.
- Passing: `go test ./acceptance -run 'TestAccept/air/'`, `go vet
./cmd/air/`, `./task lint-q` and `./task ws`.
- `go test ./cmd/air/` passes except
`TestLogsCommandRepeatsRunLinkAfterStreaming`. That test fails the same
way on an unmodified `origin/main` checkout (bdb37ab) in this
environment.

This pull request and its description were written by Isaac.

---------

Co-authored-by: Isaac <no-reply@databricks.com>
deco-sdk-tagging Bot added a commit that referenced this pull request Nov 19, 2026
## Release v1.27.0

### Notable Changes

 * `databricks aitools install`, `update` and `uninstall` now exit with code 1 when they do nothing they were asked to. `install` fails when it sets up nothing: no coding agent is detected, every agent is skipped or fails to install, or no skill in the release can be installed (also with `--path`). `update` fails when every update or check it attempts fails, and `uninstall` when every removal it attempts fails. Scripts that ran these commands as a best-effort step and relied on exit code 0 should handle the new exit code. ([#7481](#7481))
 * Add `file:<path>` selectors to `pipelines run` and pipeline `bundle run`. `--refresh` and `--full-refresh` now use space-separated lists, such as `--refresh "orders payments"`, instead of comma-separated lists. Single names containing spaces now require backticks, e.g. ``--refresh 'table:`order details`'``. ([#7184](#7184))
 * The Databricks CLI is now available on PyPI as `databricks`: run it with `uvx databricks`, or install it with `uv tool install databricks`, `pipx install databricks` or `pip install databricks`. The package contains only the prebuilt CLI binary. Uninstall the legacy `databricks-cli` package first, since both install a `databricks` command. ([#7704](#7704), [#7777](#7777))

### CLI

 * Add `databricks sandbox fs` commands (`cp`, `ls`, `cat`, `mkdir`, `rm`) to transfer files between your local filesystem and sandboxes using `<sandbox-id>:/path`. ([#7372](#7372))
 * `databricks fs` commands retry reads (stat, list, open) and deletes on DBFS and Volumes when the server returns a transient error or does not respond within the HTTP timeout. ([#7556](#7556))
 * Retry UC Volumes file operations (`fs cp`, `fs ls`, `fs rm`, bundle uploads to Volumes) when the Files API returns HTTP 408, 429, 502, 503 or 504 (for example "AWS S3 is throttling requests"), or on a transient network error; this regressed in v1.10.0. ([#7559](#7559))
 * Stop warning when the host metadata request (`/.well-known/databricks-config`) times out; the CLI already falls back to your config, and the message is still shown with `--debug`. ([#7752](#7752))
 * Add `databricks aitools auto-install disable` and `enable` to turn off (or back on) the automatic installation of Databricks AI tools on CLI upgrades. A global-scope `databricks aitools uninstall` also turns it off. ([#7701](#7701))
 * Stop printing the Databricks AI tooling install hint on `auth`, `configure`, `current-user me`, `version`, `help`, and shell-completion commands. ([#7452](#7452))
 * When Codex, Cursor, GitHub Copilot CLI, OpenCode, Gemini CLI, Antigravity, Pi, Goose or Kiro run the CLI without Databricks skills installed for that agent, the CLI now prints a one-line hint to install them with `databricks aitools install --agents <agent> --scope global`, previously shown only to Claude Code. ([#7586](#7586))
 * `databricks aitools install` now rejects an unknown `--agents` name before it shows the scope prompt, instead of after. ([#7469](#7469))
 * `databricks aitools install` no longer asks "Proceed?" after the agent picker; the picker selection confirms the plan. The picker title now shows the install scope, its hint says Enter installs, `--skills-only` runs label plugin agents "skills" and pre-check every agent whose config dir exists, and the plan summary after it is reduced to the scope line. ([#7478](#7478))
 * `databricks aitools install --output json` reports more specific `error_category` values: `SKILLS_FETCH_FAILED`, `RELEASE_LOOKUP_FAILED`, `RATE_LIMITED`, `MANIFEST_INVALID`, `STATE_INVALID` and `PLUGIN_CLI_TIMEOUT`. A coding agent CLI that does not answer in time is now reported as `timed out after <duration>`, followed by any stderr it wrote before it was stopped. ([#7475](#7475))
 * `databricks aitools install` no longer prompts when a coding agent runs it, even in a pseudo-terminal; it uses the non-interactive defaults instead and prints a note saying so. ([#7477](#7477))
 * `databricks aitools install` now prints the directory it installed skills into (for example `Installed 1 skill in ~/.databricks/aitools/skills.`), so agents can open the installed `SKILL.md` files without searching for them. ([#7668](#7668))
 * `databricks aitools install` now ends a failed install with a step to recover, in the text output and in a new `recovery` field of `--output json`. ([#7480](#7480))
 * `databricks aitools install` now installs plugins for the other coding agents even when installing skill files fails. ([#7479](#7479))
 * `databricks aitools install` now installs skill files for a detected coding agent whose CLI is not on PATH (for example a Claude Code desktop or IDE install), unless it already has the plugin, says how to switch to the plugin later, and warns when the current project also has the plugin. `databricks aitools update` no longer tries to install the plugin for such an agent, and no longer writes skill files next to a plugin that such an agent already has. ([#7482](#7482))
 * Fix `databricks aitools install` waiting a long time on an unreachable or slow workspace while it resolves authentication for telemetry; that wait is now limited to a few seconds. ([#7468](#7468))
 * `databricks aitools install`, `update` and `list` now refuse a skills manifest that names a skill or file outside the skills directory, before writing any skill files. A skill whose name or file paths are not portable is skipped with a warning, and `update` keeps its installed copy. ([#7722](#7722))
 * `databricks aitools install` and `databricks aitools update` refresh only the marketplace the Databricks plugin is listed in, so another unreachable marketplace no longer blocks them. When that refresh fails, both commands warn, install or update the plugin from the local copy of the marketplace, and record the plugin version as unknown. ([#7473](#7473))
 * `databricks aitools install` and `databricks aitools update` now wait up to 20 seconds instead of 5 for a coding agent's CLI to answer the plugin capability check, so a slow first start is less likely to report the agent as unavailable. ([#7472](#7472))
 * `databricks aitools install` no longer fails a plugin-only install when the lookup of the latest skills release on GitHub fails or is rate-limited. The plugin is installed and its version is recorded as unknown. ([#7474](#7474))
 * `databricks aitools` commands now send usage telemetry, and the CLI records when it recommends installing Databricks AI tools. When the configured workspace is slow or unreachable, `aitools install`, `update` and `uninstall` can take up to about 6 seconds longer, and `list`, `version` and runs that stop early up to about 3 seconds. Set `DATABRICKS_CLI_DISABLE_TELEMETRY=1` to opt out. ([#7467](#7467), [#7469](#7469), [#7470](#7470))
 * `databricks aitools install` and `databricks aitools update` now report a coding agent CLI shim (`.cmd` or `.bat`) on Windows that prints its plugin help and then exits with an error as `shim-exited-with-error`, with the command to run to see the error, instead of reporting the CLI as not on PATH. ([#7476](#7476))
 * `apps init` no longer suggests installing skills when every detected coding agent already has the Databricks plugin. ([#7467](#7467))
 * `databricks auth login` now gives up on the optional workspace lookup after about 5 seconds instead of retrying for about 5 minutes, and explains the fallback to the manual workspace ID prompt. ([#7522](#7522))
 * Throttle Claude Code's native plugin install hint separately from the text hint: it prints at most once per 10 minutes per session, so the install dialog still comes up when a subagent, a hook, or a command outside a Claude Code subprocess runs the session's first `databricks` command. ([#7692](#7692))
 * Print Claude Code's native plugin install hint alongside the text hint, so Claude Code offers a one-click install of the Databricks plugin. Claude Code now counts as having the tooling only when it loads it: skills only in `~/.databricks/aitools/skills` don't count, and a project- or local-scope plugin counts only when the CLI runs inside that project. `auth token`, `auth docker token` and CLI subprocesses no longer print install hints. ([#7585](#7585))
 * Interactive prompts and pagers now work in Git for Windows' bash and other MSYS2 shells when they run under ConPTY (the default since Git for Windows 2.47) or directly in a Windows console. ([#7699](#7699))
 * Add the `databricks feedback` command to send feedback about the CLI to Databricks. ([#7724](#7724))
 * Fix shell completion in `databricks fs` commands for local paths typed with a leading `./` or repeated separators, which previously offered no suggestions. ([#7679](#7679))
 * Fix a panic in `databricks labs` commands when a non-string SDK setting such as `DATABRICKS_DEBUG_HEADERS` or `DATABRICKS_RATE_LIMIT` is set in the environment. ([#7673](#7673))
 * Fix a panic in `databricks labs install` for projects whose `labs.yml` has no `install` section. ([#7673](#7673))
 * `NO_COLOR` no longer disables prompts, spinners or the list pager; they run without color. ([#7700](#7700))
 * Add the Beta `databricks pipelines test` command, which runs the tests of a pipeline, and the `testing` property of pipelines in bundles. ([#7429](#7429))
 * Add `databricks sandbox forward`, which serves an app running in a sandbox at a local URL. ([#7395](#7395))
 * Bound the whole telemetry upload at exit, including config resolution and authentication, by its timeout, so a stalled auth or telemetry endpoint no longer keeps a command from exiting. ([#7467](#7467))
 * `databricks version --check` now suggests `databricks aitools install` on stderr when a coding agent is detected without the Databricks plugin or skills. ([#7471](#7471))

### AI Runtime

 * `air get -o json` now reports `PENDING` while the run waits for compute, matching `air list`, and includes the run's `status_message`. ([#7455](#7455))
 * Wrap long failure reasons and log lines in the `air list` info and logs panes, keep the MLflow link (labeled with its retry) when a run's last retry failed before starting, and point `air logs` at earlier retries when the last one has no logs. ([#7456](#7456))
 * `databricks air logs --node` now reports an out-of-range node index when it can determine the run's node count, instead of looking like a successful run with no logs. ([#7516](#7516))
 * Add experiment, duration, accelerator, and dashboard metadata to `air list --output json`. For retried runs, `started_at` now reports the latest attempt, matching `air get`. ([#7568](#7568))
 * `air list` shortens MLflow run names and unnamed-run IDs by keeping their end behind a leading `…`, and its columns no longer overflow on wide (for example CJK) text; `air get` shows an unnamed run's full MLflow run ID. ([#7582](#7582))
 * Shrink the Experiment and User columns of the interactive `air list` table to fit the terminal width, keeping the end of a shortened experiment name. ([#7583](#7583))
 * Show the experiment, accelerators and configuration in the `air list` info pane for runs where it showed `N/A`. ([#7587](#7587))
 * Strip terminal control characters from the MLflow run, experiment and user names shown by `air list` and `air get`, so a run name cannot clear or retitle the terminal of whoever lists it. ([#7601](#7601))
 * `air logs`, `air get`, and `air run --watch` no longer make an extra credential-check request before fetching the run, and `air get` reuses the configured workspace ID instead of looking it up. ([#7613](#7613))
 * `air list` no longer waits on extra current-user requests before listing runs, which makes the default list about 150ms faster. ([#7615](#7615))
 * `air list --all-status` requests larger index pages, so it makes far fewer round trips once the server supports `page_size`. ([#7616](#7616))
 * Fit the interactive `air list` table to narrow terminals: when the Experiment and User columns are at their floors, shorten Started to `MM-DD HH:MM` and size the MLflow column to its labels, then hide Accelerators, User, MLflow and Progress in that order, naming the hidden columns in the hint line. ([#7629](#7629))
 * `air get -o json` now includes `mlflow_run_id` and `mlflow_experiment_id`, so a run can be handed to MLflow-based steps without parsing `mlflow_url`. They identify the MLflow run `mlflow_url` links to, including one from an earlier retry that `mlflow_retry` names. ([#7636](#7636))
 * `air get` and the `air list` info pane now show the environment of runs on the Databricks AI environment (`databricks_ai_v*`) instead of `N/A`. ([#7637](#7637))
 * `air run` now rejects a `code_source.include_paths` path that selects no files instead of uploading a snapshot without it; glob patterns and pathspec magic are left to git. ([#7643](#7643))
 * `air convert-to-dabs` now suggests the `--output-dir` that converts a working-tree workload whose `code_source.root_path` is outside the bundle directory, instead of suggesting `sync.paths`. ([#7644](#7644))
 * `air run` now lists a `code_source.root_path` outside a git repository relative to `root_path`, so running from a subdirectory of `root_path` no longer uploads an empty or partial snapshot. ([#7646](#7646))
 * `air list --all-status` now fills `--limit` past purged or inaccessible indexed runs. ([#7743](#7743))
 * `air run` now warns about missing PyTorch when a pinned snapshot's `include_paths` selects a Python file. ([#7744](#7744))
 * `air cancel JOB_RUN_ID` now rejects run IDs that are not AI Runtime runs instead of cancelling unrelated Jobs runs. In `-o json` output, the `failed[].error` text for a run that does not exist or that you cannot view now starts with `failed to get run <id>:` instead of the cancel API error. ([#7569](#7569))
 * `air get -o json` now reports `mlflow_retry` when the MLflow link comes from an earlier retry because the run's last retry never reached MLflow. ([#7620](#7620))
 * `databricks air run --help` now shows how to install the databricks-ai-runtime coding agent skill. ([#7652](#7652))
 * `air run --watch -o json` now reports each lifecycle `STATUS` transition once and never reports a non-terminal state after the run has ended, including when logs are served from MLflow artifacts. ([#7621](#7621))
 * `air convert-to-dabs` now explains the `--output-dir` workaround when `code_source.root_path` resolves to the bundle root, and notes when the generated job carries the default `max_retries`. ([#7579](#7579))
 * `air run` now refuses to upload a `code_source` snapshot that selects no files (for example when `root_path` is git-ignored) and explains the cause, and `--dry-run` runs the snapshot file selection and reports the file count. ([#7570](#7570))
 * Repeat the Jobs run link after live log streaming ends. ([#7571](#7571))
 * `air get -o json` includes run details including flat `accelerator_type` and `num_accelerators`. Use `--include-config` to include stored config, which may contain plaintext `env_variables` and parameters; downloads over 1 MiB are omitted, and config-dependent `max_retries` is otherwise null. ([#7624](#7624))
 * `air get` and the `air list` info pane no longer show `Max Retries 0` when the Jobs API leaves the task's retry limit out. For a run submitted with `air run`, the limit now comes from the run's uploaded config, shown as `3 (CLI default)` when the config doesn't set `max_retries`; it shows `N/A` when the limit can't be known (job runs, multi-container runs, legacy runs with no explicit value, or an unreadable config). ([#7623](#7623))
 * 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](#7512))
 * `air run -h config` now lists the environment variables AI Runtime sets on every node (such as `MLFLOW_RUN_ID` and `CODE_SOURCE_PATH`), and `air logs --help` notes that `--download-to` cannot be combined with `--tail` or `--minutes`. ([#7655](#7655))
 * Support full workspace accelerator types in `air list` filters while preserving family matching, and reject invalid filter values. ([#7515](#7515))
 * `databricks air list --all-status` now warns when the AI Runtime run index is unavailable and it falls back to scanning Jobs runs. That fallback scan is capped at 250 runs, and a stuck index request fails after 15 seconds instead of retrying for minutes. `--all-status --filter user=<your email>` now uses the run index instead of scanning the workspace's full run history. ([#7619](#7619))
 * Return structured JSON errors for invalid `air list --filter` values when `-o json` is used. ([#7612](#7612))
 * `air list --all-status` no longer fails when a listed run has been purged. ([#7523](#7523))
 * **Behavior change:** `databricks air logs` now prints the logs available now and exits, also for an active run, matching `kubectl logs`, `docker logs` and `databricks apps logs`. Pass `--follow` (`-f`) to stream new lines until the run completes; `--tail N --follow` prints the last N lines first. `databricks air run --watch` still submits and streams. ([#7658](#7658))
 * `databricks air logs -o json` and `databricks air run --watch -o json` now emit a `WAITING` event, for example `{"type":"WAITING","message":"Waiting for accelerator compute capacity..."}`, when the reported waiting status changes. ([#7695](#7695))
 * `databricks air logs` on a run that ended in the last two minutes now waits for the log index to settle before printing, instead of sometimes dropping lines that were indexed late. ([#7663](#7663))
 * `air logs` and `air run --watch` now print the waiting status (for example `Waiting for accelerator compute capacity...`) as a line on stderr when stderr is not a terminal, instead of printing nothing until the run produces logs. ([#7657](#7657))
 * Route AIR log links to the MLflow Logs page instead of the hidden artifact path. ([#7491](#7491))
 * Invalid `compute.accelerator_type` errors and `air run -h config.compute` no longer list the CLI's built-in accelerator types, which could differ from the workspace's. ([#7520](#7520))
 * `databricks air --help` now notes that GPU pools are not required to run workloads. ([#7581](#7581))
 * `air run` now prints the job run URL with the `?o=<workspace-id>` suffix, matching `air get` and `air list`; `dashboard_url` in `air run -o json` and the `--watch` events gains it too. When `air list` cannot resolve the workspace ID, its links now omit `?o=` instead of ending in `?o=0`. ([#7573](#7573))
 * `databricks air run` now reports an unknown workload YAML key by its field path, suggests the closest valid field, and points to `-h config` instead of naming an internal Go type. ([#7574](#7574))
 * `air run` (including `--dry-run`) now warns before submitting when the `code_source` imports `torch` but PyTorch is not declared: the environment is the Standard environment (version 5 or later) with no `torch` dependency, so the run may fail after it waits for a GPU. ([#7656](#7656))

### Bundles

 * Add `isolation_mode` to the `catalogs` resource, so a catalog can be deployed as `OPEN` or `ISOLATED`. ([#7463](#7463))
 * `bundle validate` no longer warns when resource permissions and top-level or target permissions name the same principal. ([#7291](#7291))
 * Retry bundle file uploads, reads and deletes when the server does not respond within the HTTP timeout ("request timed out after ... of inactivity"). ([#7521](#7521))
 * Show how to recover when `bundle deploy` fails because an app's service principal does not exist or was deleted. ([#7533](#7533))
 * Retry transient server errors when creating Lakebase (`postgres_*`) resources in the direct deployment engine. ([#7557](#7557))
 * Fix `bundle plan` reporting the `spark_conf` and `custom_tags` the backend derives from `is_single_node: true` as drift on clusters. ([#7577](#7577))
 * Stop planning a spurious update for Lakeflow Connect pipelines whose `ingestion_definition.data_staging_options` is filled in by the backend. ([#7603](#7603))
 * Retry the root path check in `bundle destroy` on transient errors, so a dropped connection no longer fails the destroy. ([#7597](#7597))
 * Use the Lakebase branch when its create request times out but the branch was created, instead of failing the deploy, in the direct deployment engine. ([#7602](#7602))
 * Retry transient server errors when deleting resources in the direct deployment engine. ([#7708](#7708))
 * Use the Lakebase project when its create request times out but the project was created, instead of failing the deploy with "already exists", in the direct deployment engine. ([#7747](#7747))
 * Use the feature, model serving endpoint or dashboard that a create request created despite timing out, instead of failing the deploy, in the direct deployment engine. ([#7757](#7757))
 * Use the Lakebase role when its create request fails with a transient error but the role was created, instead of failing the deploy, in the direct deployment engine. ([#7767](#7767))
 * Use the MCP service, model service or model provider service that a create request created despite failing with a timeout, a 499 or a reset stream, instead of failing the deploy, in the direct deployment engine. Create recovery for features, serving endpoints and dashboards now also covers 499 and reset streams. ([#7782](#7782))
 * Retry app updates and deletes in the direct deployment engine when they fail with 400 BAD_REQUEST because the app compute is `UPDATING`, after waiting for the compute to settle. ([#7606](#7606))
 * Enable drift detection for `source_code_path` and `git_source` on apps. ([#6399](#6399))
 * `bundle destroy` and `bundle deploy` no longer fail with "internal error, missing in state" when the state holds an empty-ID entry left by an interrupted recreate in an older CLI. ([#7676](#7676))
 * Fix a feature whose `full_name` contains uppercase letters being recreated on every deploy. ([#7398](#7398))
 * Fix `bundle deployment bind` (and `bundle generate --bind`) failing with `no such node "resources.internal_immutable_snapshots.immutable"` when `workspace.sync_mode` is `immutable`, as reported in [#7306](#7306). ([#7329](#7329))
 * Retry creating the deployment lock (without `--force-lock`) when the request fails with a transient server error, times out ("request timed out after ... of inactivity") or loses its connection ("unexpected EOF"). ([#7594](#7594))
 * Fix a materialization set member whose `feature_name` contains uppercase letters failing to deploy, or recreating the set on every deploy. ([#7398](#7398))
 * Delete the old resource when its name follows a renamed schema. ([#7718](#7718))
 * Fix `pipelines dry-run` starting a real run when given a job KEY, and a crash in its shell completion. ([#7672](#7672))
 * Rename schemas in place; schemas and volumes follow a renamed catalog or schema. ([#7343](#7343))
 * Fix a panic when validating or deploying jobs with local libraries and serverless job clusters. ([#7725](#7725))
 * Fix `tgz` artifacts with `git` set producing an empty tarball or failing when the bundle is in a subdirectory of the git repository. ([#7674](#7674))
 * Apply `presets.trigger_pause_status` and the development mode pause default to `triggers[]` entries on jobs. ([#7450](#7450))

### Dependency Updates

 * Bump dependencies with known vulnerabilities. ([#7750](#7750))
 * Update the Go SDK to [v0.198.0](https://github.com/databricks/databricks-sdk-go/releases/tag/v0.198.0). ([#7530](#7530))
 * Update the Go SDK to [v0.199.0](https://github.com/databricks/databricks-sdk-go/releases/tag/v0.199.0). ([#7584](#7584))
 * Update the Go SDK to [v0.200.0](https://github.com/databricks/databricks-sdk-go/releases/tag/v0.200.0). ([#7653](#7653))
 * Update the Go SDK to [v0.201.0](https://github.com/databricks/databricks-sdk-go/releases/tag/v0.201.0). ([#7769](#7769))
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

AIR Databricks AI Runtime CLI

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants