aitools: mention databricks aitools install in version --check

`databricks version --check` (text output) is followed by the `apps init` skills tip on stderr when a coding agent is detected without Databricks tooling. Stdout keeps only the update-check result:

```diff
 Databricks CLI v0.245.0
 You're on the latest version.
+Tip: coding agents detected without Databricks skills. Run 'databricks aitools install' to install them.
```

The tip comes from `agents.MaybeVersionCheckTip`. It is not printed when an agent has the databricks plugin (in its own manifest or recorded in the CLI install state) or Databricks skills (in the shared store, in the agent's own skills dir, or in the project dirs up to the repository root), on Databricks Runtime, or when Claude Code drives the CLI (`agents.MaybeHint` already covers that caller). Changelog fragment: `.nextchanges/cli/version-check-aitools-hint.md`.

Co-authored-by: Isaac <no-reply@databricks.com>

Author: anton-107

.nextchanges/cli/version-check-aitools-hint.md

@@ -0,0 +1 @@
+* `databricks version --check` now suggests `databricks aitools install` on stderr when a coding agent is detected without the Databricks plugin or skills. ([#7471](https://github.com/databricks/cli/pull/7471))

acceptance/cmd/version/claude-home/.claude/.gitkeep

@@ -18,3 +18,26 @@ This is a development build; skipping the update check.
   "update_available": false,
   "development_build": true
 }
+
+=== version --check with a coding agent and no Databricks tooling
+
+>>> [CLI] version --check
+Databricks CLI v[CLI_VERSION]
+This is a development build; skipping the update check.
+Tip: coding agents detected without Databricks skills. Run 'databricks aitools install' to install them.
+
+=== version --check --output json with a coding agent prints no tip
+
+>>> [CLI] version --check --output json
+{
+  "current_version": "[CLI_VERSION]",
+  "update_available": false,
+  "development_build": true
+}
+
+=== version --check from Claude Code prints only the root hint
+
+>>> [CLI] version --check
+Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install
+Databricks CLI v[CLI_VERSION]
+This is a development build; skipping the update check.

acceptance/cmd/version/codex-home/.codex/.gitkeep

@@ -8,3 +8,21 @@ trace $CLI version --check
 
 title "version --check --output json"
 trace $CLI version --check --output json
+
+# The tip is printed on stderr only when a coding agent is detected without
+# Databricks tooling. The committed codex-home/.codex is a Codex CLI config dir
+# without the databricks plugin or skills.
+title "version --check with a coding agent and no Databricks tooling"
+sethome ./codex-home
+trace $CLI version --check
+
+title "version --check --output json with a coding agent prints no tip"
+trace $CLI version --check --output json
+
+# Claude Code callers get only the root hint (agents.MaybeHint), not the tip.
+title "version --check from Claude Code prints only the root hint"
+sethome ./claude-home
+export CLAUDECODE=1
+unset CLAUDE_CODE_SESSION_ID
+unset CLAUDE_CONFIG_DIR
+trace $CLI version --check

acceptance/cmd/version/output.txt

@@ -3,9 +3,14 @@
 package version
 
 import (
+	"context"
+
 	"github.com/databricks/cli/cmd/root"
 	"github.com/databricks/cli/internal/build"
+	"github.com/databricks/cli/libs/aitools/agents"
+	"github.com/databricks/cli/libs/aitools/installer"
 	"github.com/databricks/cli/libs/cmdio"
+	"github.com/databricks/cli/libs/flags"
 	"github.com/databricks/cli/libs/versioncheck"
 	"github.com/spf13/cobra"
 )
@@ -30,6 +35,20 @@ Download the latest release: https://github.com/databricks/cli/releases
 {{- end}}
 `
 
+// renderUpdateCheck renders result and, in text mode, follows it with the
+// aitools install tip on stderr (agents.MaybeVersionCheckTip), so stdout keeps
+// only the update-check result.
+func renderUpdateCheck(ctx context.Context, result *versioncheck.Result, output flags.Output) error {
+	err := cmdio.RenderWithTemplate(ctx, result, "", updateCheckTemplate)
+	if err != nil {
+		return err
+	}
+	if output == flags.OutputText {
+		agents.MaybeVersionCheckTip(ctx, installer.InstalledTools)
+	}
+	return nil
+}
+
 func New() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "version",
@@ -46,7 +65,7 @@ func New() *cobra.Command {
 	cmd.RunE = func(cmd *cobra.Command, args []string) error {
 		ctx := cmd.Context()
 		if check {
-			return cmdio.RenderWithTemplate(ctx, versioncheck.Check(ctx), "", updateCheckTemplate)
+			return renderUpdateCheck(ctx, versioncheck.Check(ctx), root.OutputType(cmd))
 		}
 		return cmdio.Render(ctx, build.GetInfo())
 	}

acceptance/cmd/version/script

@@ -1,9 +1,17 @@
 package version
 
 import (
+	"bytes"
+	"os"
+	"path/filepath"
 	"testing"
 
+	"github.com/databricks/cli/internal/testutil"
+	"github.com/databricks/cli/libs/aitools/agents"
+	"github.com/databricks/cli/libs/aitools/installer"
 	"github.com/databricks/cli/libs/cmdio"
+	"github.com/databricks/cli/libs/dbr"
+	"github.com/databricks/cli/libs/flags"
 	"github.com/databricks/cli/libs/versioncheck"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -85,3 +93,74 @@ Could not reach GitHub to check for a newer version. See https://github.com/data
 		})
 	}
 }
+
+func TestRenderUpdateCheckAIToolsTip(t *testing.T) {
+	upToDate := &versioncheck.Result{CurrentVersion: "0.245.0", LatestVersion: "0.245.0"}
+	devBuild := &versioncheck.Result{CurrentVersion: "0.0.0-dev+abc123", DevelopmentBuild: true}
+	upToDateText := "Databricks CLI v0.245.0\nYou're on the latest version.\n"
+	tip := "Tip: coding agents detected without Databricks skills. Run 'databricks aitools install' to install them.\n"
+
+	tests := []struct {
+		name                string
+		result              *versioncheck.Result
+		output              flags.Output
+		recordedCodexPlugin bool
+		wantStdout          string
+		wantStderr          string
+	}{
+		{
+			name:       "text output prints the tip on stderr",
+			result:     upToDate,
+			output:     flags.OutputText,
+			wantStdout: upToDateText,
+			wantStderr: tip,
+		},
+		{
+			name:                "codex plugin recorded in the install state",
+			result:              upToDate,
+			output:              flags.OutputText,
+			recordedCodexPlugin: true,
+			wantStdout:          upToDateText,
+		},
+		{
+			name:       "development build prints the tip too",
+			result:     devBuild,
+			output:     flags.OutputText,
+			wantStdout: "Databricks CLI v0.0.0-dev+abc123\nThis is a development build; skipping the update check.\n",
+			wantStderr: tip,
+		},
+		{
+			name:       "json output",
+			result:     upToDate,
+			output:     flags.OutputJSON,
+			wantStdout: "{\n  \"current_version\": \"0.245.0\",\n  \"latest_version\": \"0.245.0\",\n  \"update_available\": false\n}\n",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			home := t.TempDir()
+			testutil.SetAgentEnv(t, "HOME", home, "USERPROFILE", home)
+			t.Chdir(t.TempDir())
+			// Codex CLI is detected by its config dir; a plugin install through
+			// `databricks aitools install` is recorded only in the install state.
+			require.NoError(t, os.MkdirAll(filepath.Join(home, ".codex"), 0o755))
+			if tt.recordedCodexPlugin {
+				state := &installer.InstallState{
+					Plugins: map[string]installer.PluginRecord{
+						"codex": {Plugin: "databricks", Version: "0.2.6"},
+					},
+				}
+				require.NoError(t, installer.SaveState(filepath.Join(home, agents.CanonicalSkillsDir), state))
+			}
+
+			var stdout, stderr bytes.Buffer
+			ctx := dbr.MockRuntime(t.Context(), dbr.Environment{})
+			ctx = cmdio.InContext(ctx, cmdio.NewIO(ctx, tt.output, nil, &stdout, &stderr, "", ""))
+			err := renderUpdateCheck(ctx, tt.result, tt.output)
+			require.NoError(t, err)
+			assert.Equal(t, tt.wantStdout, stdout.String())
+			assert.Equal(t, tt.wantStderr, stderr.String())
+		})
+	}
+}

cmd/version/version.go

@@ -4,18 +4,52 @@ import (
 	"context"
 
 	"github.com/databricks/cli/libs/cmdio"
+	"github.com/databricks/cli/libs/dbr"
 	"github.com/databricks/cli/libs/log"
 	"github.com/databricks/cli/libs/telemetry/protos"
+	"github.com/databricks/databricks-sdk-go/useragent"
 )
 
+// skillsTipText is the tip printed by PrintSkillsTip and MaybeVersionCheckTip.
+const skillsTipText = "Tip: coding agents detected without Databricks skills. Run 'databricks aitools install' to install them."
+
 // PrintSkillsTip prints the non-interactive `apps init` tip to install skills
 // and records that it was shown. Callers decide whether the tooling is missing
 // (see HasDatabricksToolingInstalled).
 func PrintSkillsTip(ctx context.Context) {
-	cmdio.LogString(ctx, "Tip: coding agents detected without Databricks skills. Run 'databricks aitools install' to install them.")
+	cmdio.LogString(ctx, skillsTipText)
 	logHintShown(ctx, protos.AitoolsHintKindAppsInitTip)
 }
 
+// MaybeVersionCheckTip prints skillsTipText after `databricks version --check`
+// when a coding agent is detected without Databricks tooling. Claude Code
+// callers are skipped because MaybeHint already covers them, with its
+// per-session throttle. installedPlugins is a parameter because this package
+// cannot import the installer; callers pass installer.InstalledTools. No
+// telemetry is logged: `databricks version` never resolves auth, so the event
+// would not be uploaded (see logHintShown).
+func MaybeVersionCheckTip(ctx context.Context, installedPlugins func(context.Context) []string) {
+	if useragent.AgentProvider() == claudeAgentProvider {
+		return
+	}
+	if dbr.HasDetection(ctx) && dbr.RunsOnRuntime(ctx) {
+		return
+	}
+	if HasDatabricksToolingInstalled(ctx) || len(installedPlugins(ctx)) > 0 {
+		return
+	}
+	// Recorded plugins are checked above, so DatabricksTooling only needs the
+	// agent's own manifest, its skills dir and the project dirs up to the
+	// repository root.
+	noRecordedPlugin := func() bool { return false }
+	for _, a := range Registry {
+		if a.DatabricksTooling(ctx, noRecordedPlugin) != ToolingNone {
+			return
+		}
+	}
+	cmdio.LogString(ctx, skillsTipText)
+}
+
 // RecommendSkillsInstall checks if coding agents are detected without Databricks tooling (skills
 // or the databricks plugin) installed.
 // In interactive mode, prompts the user to install now using installFn. In non-interactive mode, prints a hint.

cmd/version/version_test.go

@@ -7,7 +7,9 @@ import (
 	"path/filepath"
 	"testing"
 
+	"github.com/databricks/cli/internal/testutil"
 	"github.com/databricks/cli/libs/cmdio"
+	"github.com/databricks/cli/libs/dbr"
 	"github.com/databricks/cli/libs/telemetry"
 	"github.com/databricks/cli/libs/telemetry/protos"
 	"github.com/stretchr/testify/assert"
@@ -132,3 +134,72 @@ func TestRecommendSkillsInstallInteractiveDecline(t *testing.T) {
 	// The prompt is logged when shown, so a declined prompt still counts.
 	assert.Equal(t, []protos.AitoolsHintKind{protos.AitoolsHintKindAppsInitPrompt}, hintKinds(t, ctx))
 }
+
+func TestMaybeVersionCheckTip(t *testing.T) {
+	noPlugins := func(context.Context) []string { return nil }
+	recordedCodexPlugin := func(context.Context) []string { return []string{"codex_0.2.6"} }
+
+	for _, tc := range []struct {
+		name             string
+		agentEnv         []string
+		agentDirs        []string
+		globalSkills     bool
+		claudePlugin     bool
+		projectSkills    bool
+		agentSkills      bool
+		fromSubdir       bool
+		onDBR            bool
+		installedPlugins func(context.Context) []string
+		wantTip          bool
+	}{
+		{name: "agent without tooling", agentDirs: []string{".codex"}, installedPlugins: noPlugins, wantTip: true},
+		{name: "no agent detected", installedPlugins: noPlugins},
+		{name: "plugin in agent manifest", agentDirs: []string{".claude"}, claudePlugin: true, installedPlugins: noPlugins},
+		{name: "plugin recorded in install state", agentDirs: []string{".codex"}, installedPlugins: recordedCodexPlugin},
+		{name: "global skills", agentDirs: []string{".kiro"}, globalSkills: true, installedPlugins: noPlugins},
+		{name: "project skills", agentDirs: []string{".kiro"}, projectSkills: true, installedPlugins: noPlugins},
+		{name: "project skills at the repository root, run from a subdirectory", agentDirs: []string{".kiro"}, projectSkills: true, fromSubdir: true, installedPlugins: noPlugins},
+		{name: "skills only in the agent's own skills dir", agentDirs: []string{".cursor"}, agentSkills: true, installedPlugins: noPlugins},
+		{name: "databricks runtime", agentDirs: []string{".codex"}, onDBR: true, installedPlugins: noPlugins},
+		{name: "claude code caller is left to MaybeHint", agentEnv: []string{"CLAUDECODE", "1"}, agentDirs: []string{".claude"}, installedPlugins: noPlugins},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			home := t.TempDir()
+			testutil.SetAgentEnv(t, append([]string{"HOME", home, "USERPROFILE", home}, tc.agentEnv...)...)
+			project := t.TempDir()
+			if tc.fromSubdir {
+				// The walk up to the repository root stops at the nearest .git.
+				require.NoError(t, os.Mkdir(filepath.Join(project, ".git"), 0o755))
+				subdir := filepath.Join(project, "src")
+				require.NoError(t, os.Mkdir(subdir, 0o755))
+				t.Chdir(subdir)
+			} else {
+				t.Chdir(project)
+			}
+			for _, dir := range tc.agentDirs {
+				require.NoError(t, os.MkdirAll(filepath.Join(home, dir), 0o755))
+			}
+			if tc.claudePlugin {
+				writePluginManifest(t, home, `{"plugins":{"databricks@claude-plugins-official":[{"version":"0.2.6"}]}}`)
+			}
+			if tc.globalSkills {
+				require.NoError(t, os.MkdirAll(filepath.Join(home, CanonicalSkillsDir, "databricks"), 0o755))
+			}
+			if tc.projectSkills {
+				require.NoError(t, os.MkdirAll(filepath.Join(project, ".kiro", "skills", "databricks-apps"), 0o755))
+			}
+			if tc.agentSkills {
+				require.NoError(t, os.MkdirAll(filepath.Join(home, ".cursor", "skills", "databricks-apps"), 0o755))
+			}
+
+			ctx, stderr := cmdio.NewTestContextWithStderr(t.Context())
+			ctx = dbr.MockRuntime(ctx, dbr.Environment{IsDbr: tc.onDBR})
+			MaybeVersionCheckTip(ctx, tc.installedPlugins)
+			if tc.wantTip {
+				assert.Equal(t, skillsTipText+"\n", stderr.String())
+			} else {
+				assert.Empty(t, stderr.String())
+			}
+		})
+	}
+}