[air] Move AIR commands out of experimental

.github/OWNERS

@@ -73,11 +73,13 @@
 /cmd/aitools/               team:eng-apps-devex team:ide @lennartkats-db
 /libs/aitools/              team:eng-apps-devex team:ide @lennartkats-db
 
+# AI Runtime
+/cmd/air/         team:ai-training
+/acceptance/air/  team:ai-training
+
 # CLI compatibility manifest
 /internal/build/cli-compat.json  team:eng-apps-devex team:platform
 /libs/clicompat/                 team:eng-apps-devex team:platform
 
 # Experimental
-/experimental/air/             team:ai-training
-/acceptance/experimental/air/  team:ai-training
 /experimental/aitools/      team:eng-apps-devex @lennartkats-db

.nextchanges/cli/air-graduation.md

@@ -0,0 +1 @@
+* The AI Runtime commands are now available under `databricks air`. The deprecated `databricks experimental air` alias remains available temporarily. ([#6722](https://github.com/databricks/cli/pull/6722))

acceptance/experimental/air/cancel/output.txt → acceptance/air/cancel/output.txt

@@ -1,10 +1,10 @@
 
 === cancel by id (text)
->>> [CLI] experimental air cancel 123
+>>> [CLI] air cancel 123
 Successfully requested cancellation for run 123
 
 === cancel by id (json)
->>> [CLI] experimental air cancel 123 -o json
+>>> [CLI] air cancel 123 -o json
 {
   "v": 1,
   "ts": "[TIMESTAMP]",
@@ -16,13 +16,13 @@ Successfully requested cancellation for run 123
 }
 
 === cancel multiple ids
->>> [CLI] experimental air cancel 123 456
+>>> [CLI] air cancel 123 456
 Successfully requested cancellation for run 123
 Successfully requested cancellation for run 456
 Successfully requested cancellation for 2 run(s).
 
 === cancel --all
->>> [CLI] experimental air cancel --all -y
+>>> [CLI] air cancel --all -y
 Searching active runs for [USERNAME] in [DATABRICKS_URL]...
 Successfully requested cancellation for run [NUMID]
 Successfully requested cancellation for run [NUMID]

acceptance/air/cancel/script

@@ -0,0 +1,11 @@
+title "cancel by id (text)"
+trace $CLI air cancel 123
+
+title "cancel by id (json)"
+trace $CLI air cancel 123 -o json
+
+title "cancel multiple ids"
+trace $CLI air cancel 123 456
+
+title "cancel --all"
+trace $CLI air cancel --all -y

acceptance/experimental/air/config-help/output.txt → acceptance/air/config-help/output.txt

@@ -1,21 +1,21 @@
 
 === command help
->>> [CLI] experimental air run --help
+>>> [CLI] air run --help
 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 experimental air run -h config
-  databricks experimental air run -h config.compute
-  databricks experimental air run -h config.compute.accelerator_type
+  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 experimental air run [flags]
+  databricks air run [flags]
 
 Flags:
       --dry-run                  Validate the config without submitting
@@ -32,7 +32,7 @@ Global Flags:
   -t, --target string    bundle target to use (if applicable)
 
 === schema overview
->>> [CLI] experimental air run -h config
+>>> [CLI] air run -h config
 config
   The run YAML schema. Pass a field path for details, e.g. config.compute.accelerator_type.
 
@@ -58,7 +58,7 @@ config
 Use "-h config.<field>" for details on a field.
 
 === nested object lists its fields
->>> [CLI] experimental air run -h config.compute
+>>> [CLI] air run -h config.compute
 config.compute
   Which accelerators to run on and how many.
 
@@ -71,87 +71,87 @@ config.compute
 Use "-h config.compute.<field>" for details on a field.
 
 === new submission fields are documented
->>> [CLI] experimental air run -h config.mlflow_artifact_location
+>>> [CLI] air run -h config.mlflow_artifact_location
 config.mlflow_artifact_location
   DBFS location where MLflow artifacts are written. A /Volumes path is normalized to dbfs:/Volumes/... .
 
   Type:     string
   Required: no
 
->>> [CLI] experimental air run -h config.compute.pool_id
+>>> [CLI] air run -h config.compute.pool_id
 config.compute.pool_id
   GPU pool to run on, by id. A GPU pool is a pre-provisioned accelerator reservation; contact your Databricks account team to provision one. Must be 1-255 characters. List available pools with 'air list pools'.
 
   Type:     string
   Required: no
 
->>> [CLI] experimental air run -h config.compute.priority_class
+>>> [CLI] air run -h config.compute.priority_class
 config.compute.priority_class
   Scheduling priority within the pool: BEST_EFFORT (lowest, preemptable), NORMAL, or CRITICAL (highest). Requires pool_id.
 
   Type:     string
   Required: no
 
->>> [CLI] experimental air run -h config.environment.dependencies
+>>> [CLI] air run -h config.environment.dependencies
 config.environment.dependencies
   Inline list of packages to install. Not allowed alongside unity_catalog_image.
 
   Type:     list of strings
   Required: no
 
->>> [CLI] experimental air run -h config.environment.version
+>>> [CLI] air run -h config.environment.version
 config.environment.version
   Client image version to pin.
 
   Type:     string or int
   Required: no
 
 === leaf field
->>> [CLI] experimental air run -h config.compute.accelerator_type
+>>> [CLI] air run -h config.compute.accelerator_type
 config.compute.accelerator_type
   Which accelerator to run on, e.g. GPU_1xA10. See https://docs.databricks.com/aws/en/machine-learning/ai-runtime/cli/yaml-config#reference for the current list of supported GPU types. Matched case-sensitively.
 
   Type:     string
   Required: no
 
 === conditionally required leaf
->>> [CLI] experimental air run -h config.code_source.type
+>>> [CLI] air run -h config.code_source.type
 config.code_source.type
   Kind of code source. Must be "snapshot", the only supported type.
 
   Type:     string
   Required: when code_source is set
 
 === union field reports both accepted shapes
->>> [CLI] experimental air run -h config.code_source.snapshot.git.remote
+>>> [CLI] air run -h config.code_source.snapshot.git.remote
 config.code_source.snapshot.git.remote
   No longer supported: the snapshot archives your local copy. Only false is accepted; use commit to pin a revision.
 
   Type:     bool or string
   Required: no
 
 === git-pinned subdirectory snapshots document root_path scoping
->>> [CLI] experimental air run -h config.code_source.snapshot.root_path
+>>> [CLI] air run -h config.code_source.snapshot.root_path
 config.code_source.snapshot.root_path
   Root of the code source to archive. A git-pinned subdirectory packages only that subtree.
 
   Type:     string
   Required: when code_source.snapshot is set
 
 === the config. prefix is optional
->>> [CLI] experimental air run -h compute.num_accelerators
+>>> [CLI] air run -h compute.num_accelerators
 config.compute.num_accelerators
   Total number of GPUs to allocate. Must be a positive multiple of the accelerator type's per-node GPU count. See https://docs.databricks.com/aws/en/machine-learning/ai-runtime/cli/yaml-config#reference for supported GPU types.
 
   Type:     int
   Required: no
 
 === unknown field suggests the near match
->>> [CLI] experimental air run -h config.compute.acclerator_type
+>>> [CLI] air run -h config.compute.acclerator_type
 Error: unknown config field "config.compute.acclerator_type"; did you mean "accelerator_type"?
 
 fields under "config.compute" are: accelerator_type, num_accelerators, pool_id, priority_class
 
 === free-form map keys are not schema fields
->>> [CLI] experimental air run -h config.parameters.learning_rate
+>>> [CLI] air run -h config.parameters.learning_rate
 Error: "config.parameters" holds user-defined keys, so "learning_rate" is not part of the schema; see "config.parameters" instead

acceptance/air/config-help/script

@@ -0,0 +1,41 @@
+# Pin the rendered config field help. Any change to a `help:` struct tag on the
+# run YAML schema shows up as a diff here.
+
+# Plain -h must keep documenting the command itself, and advertise the config
+# path syntax so the feature is discoverable.
+title "command help"
+trace $CLI air run --help
+
+title "schema overview"
+trace $CLI air run -h config
+
+title "nested object lists its fields"
+trace $CLI air run -h config.compute
+
+title "new submission fields are documented"
+trace $CLI air run -h config.mlflow_artifact_location
+trace $CLI air run -h config.compute.pool_id
+trace $CLI air run -h config.compute.priority_class
+trace $CLI air run -h config.environment.dependencies
+trace $CLI air run -h config.environment.version
+
+title "leaf field"
+trace $CLI air run -h config.compute.accelerator_type
+
+title "conditionally required leaf"
+trace $CLI air run -h config.code_source.type
+
+title "union field reports both accepted shapes"
+trace $CLI air run -h config.code_source.snapshot.git.remote
+
+title "git-pinned subdirectory snapshots document root_path scoping"
+trace $CLI air run -h config.code_source.snapshot.root_path
+
+title "the config. prefix is optional"
+trace $CLI air run -h compute.num_accelerators
+
+title "unknown field suggests the near match"
+trace $CLI air run -h config.compute.acclerator_type
+
+title "free-form map keys are not schema fields"
+trace $CLI air run -h config.parameters.learning_rate

acceptance/experimental/air/convert-to-dabs/output.txt → acceptance/air/convert-to-dabs/output.txt

@@ -1,6 +1,6 @@
 
 === convert an AIR run YAML into a DABs bundle (in place, next to the source)
->>> [CLI] experimental air convert-to-dabs train.yaml
+>>> [CLI] air convert-to-dabs train.yaml
 Wrote a Databricks Asset Bundle to .:
   databricks.yml
   generated_artifacts/training_config.yaml
@@ -77,13 +77,13 @@ Workspace:
 Validation OK!
 
 === re-converting refuses to clobber the generated bundle
->>> [CLI] experimental air convert-to-dabs train.yaml
+>>> [CLI] air convert-to-dabs train.yaml
 Error: databricks.yml already exists in .; pass --force to overwrite or remove it
 
 Exit code: 1
 
 === --force overwrites it
->>> [CLI] experimental air convert-to-dabs train.yaml --force
+>>> [CLI] air convert-to-dabs train.yaml --force
 Wrote a Databricks Asset Bundle to .:
   databricks.yml
   generated_artifacts/training_config.yaml

acceptance/experimental/air/convert-to-dabs/script → acceptance/air/convert-to-dabs/script

@@ -1,5 +1,5 @@
 title "convert an AIR run YAML into a DABs bundle (in place, next to the source)"
-trace $CLI experimental air convert-to-dabs train.yaml
+trace $CLI air convert-to-dabs train.yaml
 
 title "emitted databricks.yml (code_source packaged as a tgz artifact; no code is copied)"
 trace cat databricks.yml
@@ -11,7 +11,7 @@ title "the emitted bundle validates"
 trace $CLI bundle validate
 
 title "re-converting refuses to clobber the generated bundle"
-errcode trace $CLI experimental air convert-to-dabs train.yaml
+errcode trace $CLI air convert-to-dabs train.yaml
 
 title "--force overwrites it"
-trace $CLI experimental air convert-to-dabs train.yaml --force
+trace $CLI air convert-to-dabs train.yaml --force

acceptance/experimental/air/get-ai-runtime/output.txt → acceptance/air/get-ai-runtime/output.txt

@@ -1,6 +1,6 @@
 
 === get (text)
->>> [CLI] experimental air get 123
+>>> [CLI] air get 123
 
 ╭─ Configuration ────────────────────────────────────────────────╮
 │                                                                │
@@ -35,7 +35,7 @@ Run URL:    [DATABRICKS_URL]/jobs/runs/123?o=[NUMID]
 MLflow URL: [DATABRICKS_URL]/ml/experiments/exp1/runs/run1
 
 === get (json)
->>> [CLI] experimental air get 123 -o json
+>>> [CLI] air get 123 -o json
 {
   "v": 1,
   "ts": "[TIMESTAMP]",

acceptance/experimental/air/get-ai-runtime/script → acceptance/air/get-ai-runtime/script

@@ -5,7 +5,7 @@ $CLI workspace mkdirs "/Workspace/Users/user@example.com/.air/cli_launch/my-exp/
 $CLI workspace import "/Workspace/Users/user@example.com/.air/cli_launch/my-exp/my-exp_abc/training_config.yaml" --file training_config.yaml --format AUTO &> LOG.import
 
 title "get (text)"
-trace $CLI experimental air get 123
+trace $CLI air get 123
 
 title "get (json)"
-trace $CLI experimental air get 123 -o json
+trace $CLI air get 123 -o json

acceptance/experimental/air/get/output.txt → acceptance/air/get/output.txt

@@ -1,6 +1,6 @@
 
 === get (text)
->>> [CLI] experimental air get 123
+>>> [CLI] air get 123
 
 ╭─ Configuration ────────────────────────────────────────────────╮
 │                                                                │
@@ -35,7 +35,7 @@ Run URL:    [DATABRICKS_URL]/jobs/runs/123?o=[NUMID]
 MLflow URL: [DATABRICKS_URL]/ml/experiments/exp1/runs/run1
 
 === get (json)
->>> [CLI] experimental air get 123 -o json
+>>> [CLI] air get 123 -o json
 {
   "v": 1,
   "ts": "[TIMESTAMP]",
@@ -54,13 +54,13 @@ MLflow URL: [DATABRICKS_URL]/ml/experiments/exp1/runs/run1
 }
 
 === invalid run id
->>> [CLI] experimental air get notanumber
+>>> [CLI] air get notanumber
 Error: invalid JOB_RUN_ID "notanumber": must be a positive integer
 
 Exit code: 1
 
 === invalid run id (json)
->>> [CLI] experimental air get notanumber -o json
+>>> [CLI] air get notanumber -o json
 {
   "v": 1,
   "ts": "[TIMESTAMP]",

acceptance/air/get/script

@@ -0,0 +1,11 @@
+title "get (text)"
+trace $CLI air get 123
+
+title "get (json)"
+trace $CLI air get 123 -o json
+
+title "invalid run id"
+errcode trace $CLI air get notanumber
+
+title "invalid run id (json)"
+errcode trace $CLI air get notanumber -o json