Skip to content

air: remove stale Public Preview label from CLI help - #7502

Merged
caroline-db merged 1 commit into
mainfrom
air-ga-help
Nov 11, 2026
Merged

caroline-db merged 1 commit into
mainfrom
air-ga-help

Conversation

@caroline-db

Copy link
Copy Markdown
Contributor

Changes

Remove the stale Public Preview label from the AIR entry in the general Databricks CLI help.

Why

AIR is GA, and the label had already been removed from the AIR command help.

Tests

Not run for PR submission. This is a minimal help-text-only change with an updated acceptance fixture.

This PR was written by Codex.

@caroline-db
caroline-db requested review from a team as code owners November 11, 2026 18:37
@github-actions github-actions Bot added the AIR Databricks AI Runtime CLI label Nov 11, 2026
@caroline-db
caroline-db requested a review from pietern November 11, 2026 18:38
@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Commit: d35e09e80 | Workflow run

Regression test report

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

1 tests: regression=1 unreleased=0 coverage=0 failing=0
test branch main (4eeacdb) latest (v1.26.0)
TestAccept/help ✅ ❌ ❌
TestAccept/help: branch ✅ | main (4eeacdb) ❌ | latest (v1.26.0) ❌

main (4eeacdb):

acceptance_test.go:1345: Diff:
        --- help/output.txt
        +++ /tmp/TestAccepthelp1424733974/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 training workloads
        +  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
        
FAIL

latest (v1.26.0): same output as main (4eeacdb)

@eng-dev-ecosystem-bot

Copy link
Copy Markdown
Collaborator

✅ Integration test report

Commit: d35e09e

Run: 43081904889

Env 🔄​flaky ✅​pass 🙈​skip Time
✅​ aws linux-2core-8gb 271 16 12:37
✅​ aws-windows-latest-4core-16gb 273 14 9:44
✅​ azure linux-2core-8gb 270 16 11:01
✅​ azure-windows-latest-4core-16gb 272 14 7:13
✅​ gcp linux-2core-8gb 271 16 12:20
🔄​ gcp-windows-latest-4core-16gb 2 271 14 10:21
Test Name gcp-windows-latest-4core-16gb
🔄​ TestSyncFullFileSync 🔄​f
🔄​ TestSyncIncrementalFileOverwritesFolder 🔄​f
Top 19 slowest tests (at least 2 minutes):
duration env testname
4:43 aws linux-2core-8gb TestFilerWorkspaceFilesExtensionsReadDir
3:59 gcp linux-2core-8gb TestAccept
3:50 aws linux-2core-8gb TestAccept
3:45 azure linux-2core-8gb TestAccept
3:40 azure-windows-latest-4core-16gb TestAccept
3:38 gcp-windows-latest-4core-16gb TestAccept
3:29 aws-windows-latest-4core-16gb TestAccept
3:12 gcp linux-2core-8gb TestFilerWorkspaceFilesExtensionsStat
2:53 gcp-windows-latest-4core-16gb TestFilerReadWrite/workspace_files
2:35 aws linux-2core-8gb TestImportDirWithOverwriteFlag
2:34 aws linux-2core-8gb TestSyncFullFileSync
2:31 gcp linux-2core-8gb TestFilerWorkspaceFilesExtensionsReadDir
2:24 gcp linux-2core-8gb TestImportDirDoesNotOverwrite
2:19 azure-windows-latest-4core-16gb TestExportDir
2:11 gcp-windows-latest-4core-16gb TestFilerWorkspaceFilesExtensionsReadDir
2:07 aws-windows-latest-4core-16gb TestFilerWorkspaceNotebook/rNb.r
2:02 aws linux-2core-8gb TestFilerRecursiveDelete/workspace_files_extensions
2:00 aws-windows-latest-4core-16gb TestFilerRecursiveDelete/workspace_files
2:00 aws-windows-latest-4core-16gb TestFilerWorkspaceFilesExtensionsStat

@caroline-db
caroline-db added this pull request to the merge queue Nov 11, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to no response for status checks Nov 11, 2026
@caroline-db
caroline-db added this pull request to the merge queue Nov 11, 2026
Merged via the queue into main with commit 78702d5 Nov 11, 2026
27 checks passed
@caroline-db
caroline-db deleted the air-ga-help branch November 11, 2026 21:47
@eng-dev-ecosystem-bot

Copy link
Copy Markdown
Collaborator

❌ Integration test report

Commit: 78702d5

Run: 43106180278

Env ❌​FAIL 🟨​KNOWN 💚​RECOVERED ✅​pass 🙈​skip Time
❌​ aws linux-2core-8gb 44 1 11 1500 1278 229:37
❌​ aws-windows-latest-4core-16gb 42 1 11 1421 1305 229:25
❌​ azure linux-2core-8gb 39 3 9 1485 1286 224:38
❌​ azure-windows-latest-4core-16gb 41 3 9 1402 1313 224:53
❌​ gcp linux-2core-8gb 41 1 11 1490 1284 242:01
❌​ gcp-windows-latest-4core-16gb 41 3 9 1409 1311 242:50
62 interesting tests: 50 FAIL, 8 RECOVERED, 4 KNOWN
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 🟨​K 🟨​K 🟨​K 🟨​K 🟨​K 🟨​K
❌​ TestAccept/bundle/deploy/spark-jar-task ❌​F ❌​F ✅​p ✅​p ✅​p ✅​p
❌​ TestAccept/bundle/deploy/spark-jar-task/DMS= ❌​F ❌​F ✅​p ✅​p ✅​p ✅​p
❌​ TestAccept/bundle/deploy/spark-jar-task/DMS=true ❌​F ❌​F ✅​p ✅​p ✅​p ✅​p
❌​ TestAccept/bundle/deployment/bind/job/generate-and-bind ✅​p ✅​p ✅​p ✅​p ✅​p ❌​F
❌​ TestAccept/bundle/deployment/bind/job/generate-and-bind/DMS=true ✅​p ✅​p ✅​p ✅​p ✅​p ❌​F
💚​ TestAccept/bundle/resources/apps/lifecycle-started 💚​R 💚​R 💚​R 💚​R 💚​R 💚​R
💚​ TestAccept/bundle/resources/apps/lifecycle-started-omitted 💚​R 💚​R 💚​R 💚​R 💚​R 💚​R
💚​ TestAccept/bundle/resources/apps/lifecycle-started-omitted/DMS=true 💚​R 💚​R 💚​R 💚​R 💚​R 💚​R
💚​ TestAccept/bundle/resources/apps/lifecycle-started-toggle 💚​R 💚​R 💚​R 💚​R 💚​R 💚​R
💚​ TestAccept/bundle/resources/apps/lifecycle-started-toggle/DMS= 💚​R 💚​R 💚​R 💚​R 💚​R 💚​R
💚​ TestAccept/bundle/resources/apps/lifecycle-started-toggle/DMS=true 💚​R 💚​R 💚​R 💚​R 💚​R 💚​R
💚​ TestAccept/bundle/resources/apps/lifecycle-started/DMS= 💚​R 💚​R 💚​R 💚​R 💚​R 💚​R
💚​ TestAccept/bundle/resources/apps/lifecycle-started/DMS=true 💚​R 💚​R 💚​R 💚​R 💚​R 💚​R
❌​ TestAccept/bundle/resources/grants/schemas/change_privilege ✅​p ✅​p ✅​p ✅​p ❌​F ✅​p
❌​ TestAccept/bundle/resources/grants/schemas/change_privilege/DMS= ✅​p ✅​p ✅​p ✅​p ❌​F ✅​p
❌​ TestAccept/bundle/resources/permissions/pipelines/recreate ✅​p ✅​p ✅​p ❌​F ✅​p ✅​p
❌​ TestAccept/bundle/resources/permissions/pipelines/recreate/DMS= ✅​p ✅​p ✅​p ❌​F ✅​p ✅​p
❌​ TestAccept/bundle/resources/postgres_branches/purge_on_delete_transitions ❌​F ✅​p ✅​p ✅​p ✅​p ✅​p
❌​ TestAccept/bundle/resources/postgres_branches/purge_on_delete_transitions/DMS= ❌​F ✅​p ✅​p ✅​p ✅​p ✅​p
❌​ TestAccept/bundle/resources/postgres_branches/update_protected ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_branches/update_protected/DMS= ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_branches/update_protected/DMS=true ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_branches/update_ttl ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_branches/update_ttl/DMS= ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_branches/update_ttl/DMS=true ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_databases/update ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_databases/update/DMS= ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_databases/update/DMS=true ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_endpoints/remove_suspend_timeout ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_endpoints/remove_suspend_timeout/DMS= ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_endpoints/remove_suspend_timeout/DMS=true ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_endpoints/update_autoscaling ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_endpoints/update_autoscaling/DMS= ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_endpoints/update_autoscaling/DMS=true ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_endpoints/update_pg_settings ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_endpoints/update_pg_settings/DMS= ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_endpoints/update_pg_settings/DMS=true ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_endpoints/update_suspend_timeout ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_endpoints/update_suspend_timeout/DMS= ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_endpoints/update_suspend_timeout/DMS=true ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_projects/add_default_endpoint_settings ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_projects/add_default_endpoint_settings/DMS= ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_projects/add_default_endpoint_settings/DMS=true ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_projects/remove_history_retention ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_projects/remove_history_retention/DMS= ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_projects/remove_history_retention/DMS=true ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_projects/update_default_endpoint_suspend ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_projects/update_default_endpoint_suspend/DMS= ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_projects/update_default_endpoint_suspend/DMS=true ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_projects/update_display_name ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_projects/update_display_name/DMS= ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_projects/update_display_name/DMS=true ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_projects/update_history_retention ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_projects/update_history_retention/DMS= ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_projects/update_history_retention/DMS=true ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_roles/update ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_roles/update/DMS= ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
❌​ TestAccept/bundle/resources/postgres_roles/update/DMS=true ❌​F ❌​F ❌​F ❌​F ❌​F ❌​F
🟨​ TestAccept/bundle/resources/postgres_synced_tables/recreate 💚​R 💚​R 🟨​K 🟨​K 💚​R 🟨​K
🟨​ TestAccept/bundle/resources/postgres_synced_tables/recreate/DMS= 💚​R 💚​R 💚​R 🟨​K 💚​R 💚​R
🟨​ TestAccept/bundle/resources/postgres_synced_tables/recreate/DMS=true 💚​R 💚​R 🟨​K 💚​R 💚​R 🟨​K
Top 50 slowest tests (at least 2 minutes):
duration env testname
12:58 gcp linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=
12:39 gcp linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=true
11:04 aws-windows-latest-4core-16gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=
10:56 aws linux-2core-8gb TestAccept/bundle/resources/clusters/lifecycle-started/DMS=true
10:50 aws linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=
10:47 gcp-windows-latest-4core-16gb TestAccept/bundle/resources/clusters/lifecycle-started-toggle/DMS=true
10:41 aws-windows-latest-4core-16gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=true
10:23 gcp-windows-latest-4core-16gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=true
10:13 gcp-windows-latest-4core-16gb TestAccept/bundle/resources/clusters/lifecycle-started/DMS=true
9:58 gcp-windows-latest-4core-16gb TestAccept/bundle/resources/clusters/lifecycle-started/DMS=
9:50 azure linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=
9:46 aws-windows-latest-4core-16gb TestAccept/bundle/resources/clusters/lifecycle-started/DMS=true
9:37 azure-windows-latest-4core-16gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=true
9:06 azure linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=true
9:04 aws linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=true
8:42 gcp linux-2core-8gb TestAccept/bundle/resources/clusters/lifecycle-started/DMS=
8:32 gcp linux-2core-8gb TestAccept/bundle/resources/clusters/lifecycle-started/DMS=true
8:20 gcp linux-2core-8gb TestAccept/bundle/resources/clusters/deploy/local_ssd_count/DMS=true
8:19 aws linux-2core-8gb TestAccept/bundle/invariant/no_drift/DMS=true/INPUT_CONFIG=cluster_apply_policy_default_values.yml.tmpl/READPLAN=1
8:11 azure-windows-latest-4core-16gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=
7:58 aws linux-2core-8gb TestAccept/bundle/invariant/delete_idempotent/DMS=/INPUT_CONFIG=cluster_apply_policy_default_values.yml.tmpl/READPLAN=1
7:53 aws linux-2core-8gb TestAccept/bundle/resources/clusters/lifecycle-started/DMS=
7:47 aws-windows-latest-4core-16gb TestAccept/bundle/invariant/destroy_idempotent/DMS=/INPUT_CONFIG=cluster_libraries.yml.tmpl/READPLAN=
7:41 gcp-windows-latest-4core-16gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=
7:40 azure-windows-latest-4core-16gb TestAccept/bundle/invariant/delete_idempotent/DMS=/INPUT_CONFIG=cluster_libraries.yml.tmpl/READPLAN=
7:40 gcp-windows-latest-4core-16gb TestAccept/bundle/resources/clusters/resize-terminated-fallback/DMS=true
7:39 aws-windows-latest-4core-16gb TestAccept/bundle/resources/clusters/lifecycle-started-toggle/DMS=
7:35 azure linux-2core-8gb TestAccept/bundle/resources/clusters/lifecycle-started/DMS=true
7:31 aws linux-2core-8gb TestAccept/bundle/invariant/no_drift/DMS=true/INPUT_CONFIG=cluster_apply_policy_default_values.yml.tmpl/READPLAN=
7:31 gcp-windows-latest-4core-16gb TestAccept/bundle/resources/clusters/lifecycle-started-toggle/DMS=
7:27 gcp linux-2core-8gb TestAccept/bundle/resources/clusters/lifecycle-started-toggle/DMS=true
7:20 gcp-windows-latest-4core-16gb TestAccept/bundle/resources/clusters/deploy/update-after-create/DMS=
7:20 aws linux-2core-8gb TestAccept/bundle/resources/clusters/lifecycle-started-toggle/DMS=true
7:20 gcp-windows-latest-4core-16gb TestAccept/bundle/invariant/delete_idempotent/DMS=/INPUT_CONFIG=cluster_libraries.yml.tmpl/READPLAN=1
7:13 gcp-windows-latest-4core-16gb TestAccept/bundle/invariant/delete_idempotent/DMS=/INPUT_CONFIG=cluster_apply_policy_default_values.yml.tmpl/READPLAN=1
7:11 aws-windows-latest-4core-16gb TestAccept/bundle/resources/clusters/lifecycle-started-toggle/DMS=true
6:54 azure-windows-latest-4core-16gb TestAccept/bundle/resources/clusters/lifecycle-started/DMS=
6:48 azure-windows-latest-4core-16gb TestAccept/bundle/invariant/delete_idempotent/DMS=/INPUT_CONFIG=cluster_libraries.yml.tmpl/READPLAN=1
6:45 aws linux-2core-8gb TestAccept/bundle/config-remote-sync/multiple_resources/DMS=true
6:44 gcp linux-2core-8gb TestAccept/bundle/resources/clusters/deploy/local_ssd_count/DMS=
6:43 aws linux-2core-8gb TestAccept/bundle/config-remote-sync/multiple_resources/DMS=
6:42 gcp-windows-latest-4core-16gb TestAccept/bundle/resources/clusters/deploy/local_ssd_count/DMS=
6:37 azure linux-2core-8gb TestAccept/bundle/resources/clusters/lifecycle-started/DMS=
6:30 azure linux-2core-8gb TestAccept/bundle/config-remote-sync/multiple_resources/DMS=
6:27 aws-windows-latest-4core-16gb TestAccept/bundle/resources/clusters/lifecycle-started/DMS=
6:26 gcp linux-2core-8gb TestAccept/bundle/config-remote-sync/multiple_resources/DMS=true
6:25 aws linux-2core-8gb TestAccept/bundle/invariant/delete_idempotent/DMS=/INPUT_CONFIG=cluster.yml.tmpl/READPLAN=
6:13 azure-windows-latest-4core-16gb TestAccept/bundle/invariant/delete_idempotent/DMS=/INPUT_CONFIG=cluster_apply_policy_default_values.yml.tmpl/READPLAN=1
5:53 azure linux-2core-8gb TestAccept/bundle/config-remote-sync/multiple_resources/DMS=true
5:51 azure-windows-latest-4core-16gb TestAccept/bundle/resources/clusters/lifecycle-started-toggle/DMS=

idelafuente-oc pushed a commit to idelafuente-oc/cli that referenced this pull request Nov 14, 2026
…bricks#7512)

## 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" (databricks#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.

<details open><summary><code>databricks air -h</code></summary>

**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
```

</details>

<details><summary><code>databricks air run -h</code></summary>

**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
```

</details>

<details><summary><code>databricks air run -h config</code></summary>

**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
```

</details>

<details><summary><code>databricks air run -h
config.compute</code></summary>

**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>".
```

</details>

<details><summary><code>databricks air run -h
config.environment.version</code></summary>

**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
```

</details>

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

---------

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

4 participants