cmd/experimental/air: scaffold AI runtime CLI command package

Add the experimental `air` command group as the Go port surface for the
Python `air` CLI. Every subcommand (run, status, list, logs, cancel,
register-image) is registered as a stub that returns a not-implemented
error; the real implementations land in later milestones.

Includes unit tests for the command-tree wiring and the not-implemented
stubs, plus an acceptance test exercising the stubs end-to-end.

Co-authored-by: Isaac

Author: riddhibhagwat-db

acceptance/experimental/air/unimplemented/out.test.toml

@@ -0,0 +1,36 @@
+
+=== run
+>>> [CLI] experimental air run
+Error: `air run` is not implemented yet
+
+Exit code: 1
+
+=== status
+>>> [CLI] experimental air status 123
+Error: `air status` is not implemented yet
+
+Exit code: 1
+
+=== list
+>>> [CLI] experimental air list
+Error: `air list` is not implemented yet
+
+Exit code: 1
+
+=== logs
+>>> [CLI] experimental air logs 123
+Error: `air logs` is not implemented yet
+
+Exit code: 1
+
+=== cancel
+>>> [CLI] experimental air cancel 123
+Error: `air cancel` is not implemented yet
+
+Exit code: 1
+
+=== register-image
+>>> [CLI] experimental air register-image my-image:latest
+Error: `air register-image` is not implemented yet
+
+Exit code: 1

acceptance/experimental/air/unimplemented/output.txt

@@ -0,0 +1,19 @@
+# Each stub must fail with "not implemented"; errcode records the exit code.
+
+title "run"
+errcode trace $CLI experimental air run
+
+title "status"
+errcode trace $CLI experimental air status 123
+
+title "list"
+errcode trace $CLI experimental air list
+
+title "logs"
+errcode trace $CLI experimental air logs 123
+
+title "cancel"
+errcode trace $CLI experimental air cancel 123
+
+title "register-image"
+errcode trace $CLI experimental air register-image my-image:latest

acceptance/experimental/air/unimplemented/script

@@ -0,0 +1,6 @@
+Local = true
+Cloud = false
+
+# Stubs fail locally before any API call, so no server stubs needed.
+[EnvMatrix]
+DATABRICKS_BUNDLE_ENGINE = []

acceptance/experimental/air/unimplemented/test.toml

@@ -0,0 +1,36 @@
+package air
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+)
+
+// New returns the root command for the experimental AI runtime CLI.
+//
+// Milestone 0: scaffolds the command group with every subcommand registered as a
+// stub (not yet implemented), pending the port from the Python `air` CLI.
+func New() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "air",
+		Short: "Run and manage AI runtime training workloads",
+		Long: `Run and manage AI runtime training workloads on Databricks serverless GPU compute.
+
+This command set is the Go port of the standalone Python "air" CLI. It is
+experimental and may change in future versions.`,
+	}
+
+	cmd.AddCommand(newRunCommand())
+	cmd.AddCommand(newStatusCommand())
+	cmd.AddCommand(newListCommand())
+	cmd.AddCommand(newLogsCommand())
+	cmd.AddCommand(newCancelCommand())
+	cmd.AddCommand(newRegisterImageCommand())
+
+	return cmd
+}
+
+// notImplemented returns the placeholder error used by milestone-0 stubs.
+func notImplemented(name string) error {
+	return fmt.Errorf("`air %s` is not implemented yet", name)
+}

cmd/experimental/air/air.go

@@ -0,0 +1,22 @@
+package air
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+// TestNewRegistersAllSubcommands asserts the `ai` command wires up every
+// expected subcommand, so none is accidentally dropped from New.
+func TestNewRegistersAllSubcommands(t *testing.T) {
+	registered := make(map[string]bool)
+	for _, c := range New().Commands() {
+		registered[c.Name()] = true
+	}
+
+	want := []string{"run", "status", "list", "logs", "cancel", "register-image"}
+	for _, name := range want {
+		assert.True(t, registered[name], "subcommand %q is not registered", name)
+	}
+	assert.Len(t, registered, len(want), "unexpected number of subcommands")
+}

cmd/experimental/air/air_test.go

@@ -0,0 +1,27 @@
+package air
+
+import (
+	"github.com/spf13/cobra"
+)
+
+func newCancelCommand() *cobra.Command {
+	var (
+		all bool
+		yes bool
+	)
+
+	cmd := &cobra.Command{
+		Use:   "cancel [RUN_ID...]",
+		Args:  cobra.ArbitraryArgs,
+		Short: "Cancel one or more runs",
+		Long:  `Cancel one or more runs by ID, or cancel all of your active runs with --all.`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return notImplemented("cancel")
+		},
+	}
+
+	cmd.Flags().BoolVar(&all, "all", false, "Cancel all of your active runs")
+	cmd.Flags().BoolVarP(&yes, "yes", "y", false, "Skip the confirmation prompt")
+
+	return cmd
+}

cmd/experimental/air/cancel.go

@@ -0,0 +1,31 @@
+package air
+
+import (
+	"github.com/databricks/cli/cmd/root"
+	"github.com/spf13/cobra"
+)
+
+func newListCommand() *cobra.Command {
+	var (
+		limit    int
+		active   bool
+		allUsers bool
+		filters  []string
+	)
+
+	cmd := &cobra.Command{
+		Use:   "list",
+		Args:  root.NoArgs,
+		Short: "List recent runs",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return notImplemented("list")
+		},
+	}
+
+	cmd.Flags().IntVar(&limit, "limit", 20, "Maximum number of runs to show")
+	cmd.Flags().BoolVar(&active, "active", false, "Show only active runs")
+	cmd.Flags().BoolVar(&allUsers, "all-users", false, "Show runs from all users")
+	cmd.Flags().StringArrayVar(&filters, "filter", nil, "Filter runs, e.g. experiment=foo* (repeatable)")
+
+	return cmd
+}

cmd/experimental/air/list.go

@@ -0,0 +1,34 @@
+package air
+
+import (
+	"github.com/databricks/cli/cmd/root"
+	"github.com/spf13/cobra"
+)
+
+func newLogsCommand() *cobra.Command {
+	var (
+		node       int
+		lines      int
+		retry      int
+		downloadTo string
+		review     bool
+	)
+
+	cmd := &cobra.Command{
+		Use:   "logs RUN_ID",
+		Args:  root.ExactArgs(1),
+		Short: "Stream or fetch logs for a run",
+		Long:  `Stream logs from an active run, or fetch logs from a completed run.`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return notImplemented("logs")
+		},
+	}
+
+	cmd.Flags().IntVar(&node, "node", 0, "Fetch logs from this node")
+	cmd.Flags().IntVar(&lines, "lines", 10000, "For completed runs, print the last N lines")
+	cmd.Flags().IntVar(&retry, "retry", -1, "View logs from a specific retry attempt (default: latest)")
+	cmd.Flags().StringVar(&downloadTo, "download-to", "", "Download all logs to this directory instead of printing")
+	cmd.Flags().BoolVar(&review, "review", false, "Download logs from all nodes and filter for error signatures")
+
+	return cmd
+}

cmd/experimental/air/logs.go

@@ -0,0 +1,33 @@
+package air
+
+import (
+	"github.com/databricks/cli/cmd/root"
+	"github.com/spf13/cobra"
+)
+
+func newRegisterImageCommand() *cobra.Command {
+	var (
+		scope           string
+		key             string
+		interactiveAuth bool
+		tagPolicy       string
+		timeoutMinutes  int
+	)
+
+	cmd := &cobra.Command{
+		Use:   "register-image IMAGE_URL",
+		Args:  root.ExactArgs(1),
+		Short: "Mirror a Docker image into the workspace registry",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return notImplemented("register-image")
+		},
+	}
+
+	cmd.Flags().StringVar(&scope, "scope", "", "Databricks secret scope holding registry credentials")
+	cmd.Flags().StringVar(&key, "key", "", "Databricks secret key holding registry credentials")
+	cmd.Flags().BoolVar(&interactiveAuth, "interactive-authenticate", false, "Prompt for registry credentials and store them as a secret")
+	cmd.Flags().StringVar(&tagPolicy, "tag-policy", "auto", "Image resolution policy: auto or latest")
+	cmd.Flags().IntVar(&timeoutMinutes, "timeout-minutes", 60, "Timeout to wait for the image to become available")
+
+	return cmd
+}