aitools: add --scope flag, deprecate --project/--global (#5234)

## Summary

Split out from #4917. While that PR keeps responsibility for *moving*
the aitools skills-management surface out of `experimental/`, this PR
makes the user-facing interface changes that should land at the same
moment:

- New `--scope=project|global` flag on
`install`/`update`/`uninstall`/`list`, with `--scope=both` accepted by
`update` and `list`.
- `--project` and `--global` are marked deprecated via cobra's
`Deprecated` property: hidden from `--help`, emit a stderr deprecation
warning when used, continue to function so existing scripts don't break.
They're slated for removal in a later release.
- `--scope` combined with `--project`/`--global` is rejected up front
with an actionable error.
- `install`'s `--help` now documents the non-interactive `--agents`
auto-detect contract so callers know what gets picked.

**Stacked on #4917.** Base will rebase to `main` once that lands.
Splitting because (a) #4917 is otherwise a pure file move and reviewers
asked to keep it that way, and (b) the interface change has its own
product question (boolean pair vs. enum) worth landing as a discrete
unit.

## Why land this with the rename

aitools is being declared a stable top-level surface in #4917. This is
the cheapest moment to fix the two-boolean shape before external scripts
depend on it. An enum is also better for agent-driven invocations than
two booleans with implicit precedence: `--scope=project|global|both` is
one flag with valid values, not two flags with order-dependent
semantics.

## Surface

```
databricks aitools install   --scope=project|global             (--scope=both rejected)
databricks aitools uninstall --scope=project|global             (--scope=both rejected)
databricks aitools update    --scope=project|global|both
databricks aitools list      --scope=project|global|both        (default: both)

databricks aitools install --project    # warns: use --scope=project
databricks aitools install --global     # warns: use --scope=global
```

## Test plan

- [ ] `databricks aitools install --scope=project` and `--scope=global`
go to the right destination
- [ ] `databricks aitools install --scope=both` errors with a clear
message
- [ ] `databricks aitools install --project` still works and prints the
deprecation warning to stderr
- [ ] `databricks aitools install --scope=global --project` errors with
the conflict message
- [ ] `databricks aitools list --scope=both` shows both scopes
(equivalent to no flag)
- [ ] `databricks aitools install --help` no longer shows
`--project`/`--global`; `--scope` is documented; `--agents` auto-detect
behavior is described
- [ ] Unit: `TestParseScopeFlag` (table-driven on the translation),
`TestInstallScopeFlag`, `TestListScopeFlag` — all green

This pull request was AI-assisted by Isaac.

---------

Co-authored-by: simon <4305831+simonfaltum@users.noreply.github.com>
Co-authored-by: simon <simon.faltum@databricks.com>

Author: jamesbroadhead

NEXT_CHANGELOG.md

@@ -8,7 +8,7 @@
 
 ### CLI
 
-* Added `databricks aitools` command group for installing Databricks skills into your coding agents (Claude Code, Cursor, Codex CLI, OpenCode, GitHub Copilot, Antigravity). Skills are fetched from [github.com/databricks/databricks-agent-skills](https://github.com/databricks/databricks-agent-skills) and either symlinked into each agent's skills directory or copied into the current project. Use `databricks aitools install` to set up, `update` to pull newer versions, `list` to see what's available, and `uninstall` to remove them.
+* Added `databricks aitools` command group for installing Databricks skills into your coding agents (Claude Code, Cursor, Codex CLI, OpenCode, GitHub Copilot, Antigravity). Skills are fetched from [github.com/databricks/databricks-agent-skills](https://github.com/databricks/databricks-agent-skills) and either symlinked into each agent's skills directory or copied into the current project. Use `databricks aitools install` to set up, `update` to pull newer versions, `list` to see what's available, and `uninstall` to remove them. Pick where they go with `--scope=project|global` (`--scope=both` is accepted on `update` and `list`).
 * `[__settings__].default_profile` is now consulted as a fallback by `databricks api`, `databricks auth token`, and bundle commands when neither `--profile` nor `DATABRICKS_CONFIG_PROFILE` is set. `databricks auth token` continues to give precedence to `DATABRICKS_HOST` over `default_profile`. For bundle commands, `default_profile` only applies when the bundle does not pin its own `workspace.host`.
 
 ### Bundles

cmd/aitools/install.go

@@ -51,7 +51,7 @@ func defaultPromptAgentSelection(ctx context.Context, detected []*agents.Agent)
 }
 
 func NewInstallCmd() *cobra.Command {
-	var skillsFlag, agentsFlag string
+	var skillsFlag, agentsFlag, scopeFlag string
 	var includeExperimental bool
 	var projectFlag, globalFlag bool
 
@@ -61,17 +61,30 @@ func NewInstallCmd() *cobra.Command {
 		Long: `Install Databricks AI skills for detected coding agents.
 
 By default, skills are installed globally to each agent's skills directory.
-Use --project to install to the current project directory instead.
+Use --scope=project to install to the current project directory instead.
 When multiple agents are detected, skills are stored in a canonical location
 and symlinked to each agent to avoid duplication.
 
 Use --skills name1,name2 to install specific skills.
 
+Agent selection:
+  --agents <name>[,<name>...]   Install only for the named agents.
+  (unset, interactive)          Multi-select prompt over detected agents.
+  (unset, non-interactive)      Install for every detected agent.
+
+The list of agents the command will act on is always logged to stderr before
+the install runs, so callers can verify what was picked.
+
 Supported agents: Claude Code, Cursor, Codex CLI, OpenCode, GitHub Copilot, Antigravity`,
 		Args: cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()
 
+			projectFlag, globalFlag, err := parseScopeFlag(scopeFlag, projectFlag, globalFlag, false)
+			if err != nil {
+				return err
+			}
+
 			// Resolve scope.
 			scope, err := resolveScopeWithPrompt(ctx, projectFlag, globalFlag)
 			if err != nil {
@@ -130,8 +143,10 @@ Supported agents: Claude Code, Cursor, Codex CLI, OpenCode, GitHub Copilot, Anti
 	cmd.Flags().StringVar(&skillsFlag, "skills", "", "Specific skills to install (comma-separated)")
 	cmd.Flags().StringVar(&agentsFlag, "agents", "", "Agents to install for (comma-separated, e.g. claude-code,cursor)")
 	cmd.Flags().BoolVar(&includeExperimental, "experimental", false, "Include experimental skills")
+	cmd.Flags().StringVar(&scopeFlag, "scope", "", "Install scope: project or global (default: global, or prompt when interactive)")
 	cmd.Flags().BoolVar(&projectFlag, "project", false, "Install to project directory (cwd)")
 	cmd.Flags().BoolVar(&globalFlag, "global", false, "Install globally (default)")
+	markScopeBoolsDeprecated(cmd)
 	return cmd
 }
 

cmd/aitools/install_test.go

@@ -411,6 +411,45 @@ func TestInstallGlobalAndProjectErrors(t *testing.T) {
 	assert.Contains(t, err.Error(), "cannot use --global and --project together")
 }
 
+func TestInstallScopeFlag(t *testing.T) {
+	tests := []struct {
+		name      string
+		args      []string
+		wantScope string
+		wantErr   string
+	}{
+		{name: "scope project", args: []string{"--scope", "project"}, wantScope: installer.ScopeProject},
+		{name: "scope global", args: []string{"--scope", "global"}, wantScope: installer.ScopeGlobal},
+		{name: "scope both rejected", args: []string{"--scope", "both"}, wantErr: "--scope=both is not supported"},
+		{name: "scope invalid value", args: []string{"--scope", "all"}, wantErr: `invalid --scope "all"`},
+		{name: "scope conflicts with legacy", args: []string{"--scope", "global", "--project"}, wantErr: "cannot use --scope with --project or --global"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			setupTestAgents(t)
+			calls := setupInstallMock(t)
+
+			ctx := cmdio.MockDiscard(t.Context())
+			cmd := NewInstallCmd()
+			cmd.SetContext(ctx)
+			cmd.SetArgs(tt.args)
+			cmd.SilenceErrors = true
+			cmd.SilenceUsage = true
+
+			err := cmd.Execute()
+			if tt.wantErr != "" {
+				require.Error(t, err)
+				assert.Contains(t, err.Error(), tt.wantErr)
+				return
+			}
+			require.NoError(t, err)
+			require.Len(t, *calls, 1)
+			assert.Equal(t, tt.wantScope, (*calls)[0].opts.Scope)
+		})
+	}
+}
+
 func TestInstallNoFlagNonInteractiveUsesGlobal(t *testing.T) {
 	setupTestAgents(t)
 	calls := setupInstallMock(t)

cmd/aitools/list.go

@@ -19,29 +19,42 @@ import (
 var listSkillsFn = defaultListSkills
 
 func NewListCmd() *cobra.Command {
+	var scopeFlag string
 	var projectFlag, globalFlag bool
 
 	cmd := &cobra.Command{
 		Use:   "list",
 		Short: "List installed AI tools components",
 		Args:  cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			if projectFlag && globalFlag {
+			// Reject the legacy --project --global combination here so it
+			// doesn't silently degrade to --scope=both. Users who want both
+			// scopes should use --scope=both (the new explicit spelling).
+			if projectFlag && globalFlag && scopeFlag == "" {
 				return errors.New("cannot use --global and --project together")
 			}
-			// For list: no flag = show both scopes (empty string).
+
+			projectFlag, globalFlag, err := parseScopeFlag(scopeFlag, projectFlag, globalFlag, true)
+			if err != nil {
+				return err
+			}
+
+			// list: empty scope = show both. --scope=both also lands here.
 			var scope string
-			if projectFlag {
+			switch {
+			case projectFlag && !globalFlag:
 				scope = installer.ScopeProject
-			} else if globalFlag {
+			case globalFlag && !projectFlag:
 				scope = installer.ScopeGlobal
 			}
 			return listSkillsFn(cmd, scope)
 		},
 	}
 
+	cmd.Flags().StringVar(&scopeFlag, "scope", "", "Scope to show: project, global, or both (default: both)")
 	cmd.Flags().BoolVar(&projectFlag, "project", false, "Show only project-scoped skills")
 	cmd.Flags().BoolVar(&globalFlag, "global", false, "Show only globally-scoped skills")
+	markScopeBoolsDeprecated(cmd)
 	return cmd
 }
 

cmd/aitools/list_test.go

@@ -3,6 +3,7 @@ package aitools
 import (
 	"testing"
 
+	"github.com/databricks/cli/libs/aitools/installer"
 	"github.com/databricks/cli/libs/cmdio"
 	"github.com/spf13/cobra"
 	"github.com/stretchr/testify/assert"
@@ -36,7 +37,58 @@ func TestListCommandCallsListFn(t *testing.T) {
 func TestListCommandHasScopeFlags(t *testing.T) {
 	cmd := NewListCmd()
 	f := cmd.Flags().Lookup("project")
-	require.NotNil(t, f, "--project flag should exist")
+	require.NotNil(t, f, "--project flag should exist (deprecated alias)")
+	assert.NotEmpty(t, f.Deprecated, "--project should be marked deprecated")
 	f = cmd.Flags().Lookup("global")
-	require.NotNil(t, f, "--global flag should exist")
+	require.NotNil(t, f, "--global flag should exist (deprecated alias)")
+	assert.NotEmpty(t, f.Deprecated, "--global should be marked deprecated")
+	f = cmd.Flags().Lookup("scope")
+	require.NotNil(t, f, "--scope flag should exist")
+}
+
+func TestListScopeFlag(t *testing.T) {
+	tests := []struct {
+		name      string
+		args      []string
+		wantScope string
+		wantErr   string
+	}{
+		{name: "scope project", args: []string{"--scope", "project"}, wantScope: installer.ScopeProject},
+		{name: "scope global", args: []string{"--scope", "global"}, wantScope: installer.ScopeGlobal},
+		{name: "scope both shows both", args: []string{"--scope", "both"}, wantScope: ""},
+		{name: "scope invalid", args: []string{"--scope", "all"}, wantErr: `invalid --scope "all"`},
+		{name: "legacy both flags together rejected", args: []string{"--project", "--global"}, wantErr: "cannot use --global and --project together"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			orig := listSkillsFn
+			t.Cleanup(func() { listSkillsFn = orig })
+
+			var gotScope string
+			called := false
+			listSkillsFn = func(_ *cobra.Command, scope string) error {
+				called = true
+				gotScope = scope
+				return nil
+			}
+
+			ctx := cmdio.MockDiscard(t.Context())
+			cmd := NewListCmd()
+			cmd.SetContext(ctx)
+			cmd.SetArgs(tt.args)
+			cmd.SilenceErrors = true
+			cmd.SilenceUsage = true
+
+			err := cmd.Execute()
+			if tt.wantErr != "" {
+				require.Error(t, err)
+				assert.Contains(t, err.Error(), tt.wantErr)
+				return
+			}
+			require.NoError(t, err)
+			assert.True(t, called)
+			assert.Equal(t, tt.wantScope, gotScope)
+		})
+	}
 }

cmd/aitools/scope.go

@@ -11,6 +11,7 @@ import (
 	"github.com/databricks/cli/libs/aitools/installer"
 	"github.com/databricks/cli/libs/cmdio"
 	"github.com/databricks/cli/libs/env"
+	"github.com/spf13/cobra"
 )
 
 // promptScopeSelection is a package-level var so tests can replace it with a mock.
@@ -82,6 +83,53 @@ func defaultPromptScopeSelection(ctx context.Context) (string, error) {
 
 const scopeBoth = "both"
 
+// markScopeBoolsDeprecated hides --project and --global from help and emits a
+// stderr warning pointing at --scope when they're used. The booleans are kept
+// so existing scripts and the experimental backward-compat aliases keep
+// working through the next release.
+func markScopeBoolsDeprecated(cmd *cobra.Command) {
+	cmd.Flags().Lookup("project").Deprecated = "use --scope=project"
+	cmd.Flags().Lookup("project").Hidden = true
+	cmd.Flags().Lookup("global").Deprecated = "use --scope=global"
+	cmd.Flags().Lookup("global").Hidden = true
+}
+
+// parseScopeFlag translates --scope into the equivalent --project/--global bool pair.
+// Returns (projectFlag, globalFlag, nil) unchanged when --scope is empty so the
+// deprecated booleans can keep flowing through the existing resolveScope* helpers
+// (including update's supported `--project --global` "both scopes" path). Errors
+// if --scope is combined with --project or --global. When allowBoth is false,
+// --scope=both is rejected up front so install and uninstall don't have to
+// special-case it.
+//
+// Note: install/list/uninstall reject the legacy `--project --global` combination
+// at their own RunE / resolveScope layer; update intentionally accepts it as the
+// "both scopes" path until those flags are removed.
+func parseScopeFlag(scopeFlag string, projectFlag, globalFlag, allowBoth bool) (proj, glob bool, err error) {
+	if scopeFlag == "" {
+		return projectFlag, globalFlag, nil
+	}
+	if projectFlag || globalFlag {
+		return false, false, errors.New("cannot use --scope with --project or --global; --project and --global are deprecated aliases for --scope")
+	}
+	switch scopeFlag {
+	case installer.ScopeProject:
+		return true, false, nil
+	case installer.ScopeGlobal:
+		return false, true, nil
+	case scopeBoth:
+		if !allowBoth {
+			return false, false, errors.New("--scope=both is not supported for this command; use 'project' or 'global'")
+		}
+		return true, true, nil
+	default:
+		if allowBoth {
+			return false, false, fmt.Errorf("invalid --scope %q: must be one of project, global, both", scopeFlag)
+		}
+		return false, false, fmt.Errorf("invalid --scope %q: must be one of project, global", scopeFlag)
+	}
+}
+
 // detectInstalledScopes checks which scopes have a .state.json file present.
 func detectInstalledScopes(globalDir, projectDir string) (global, project bool, err error) {
 	globalState, err := installer.LoadState(globalDir)
@@ -132,7 +180,7 @@ func resolveScopeForUpdate(ctx context.Context, projectFlag, globalFlag bool, gl
 	switch {
 	case hasGlobal && hasProject:
 		if !cmdio.IsPromptSupported(ctx) {
-			return nil, errors.New("skills are installed in both global and project scopes; use --global, --project, or both flags to specify which to update")
+			return nil, errors.New("skills are installed in both global and project scopes; use --scope=global, --scope=project, or --scope=both to specify which to update")
 		}
 		scopes, err := promptUpdateScopeSelection(ctx)
 		if err != nil {
@@ -158,7 +206,7 @@ func resolveScopeForUpdate(ctx context.Context, projectFlag, globalFlag bool, gl
 // Unlike update, uninstall never allows "both" scopes at once.
 func resolveScopeForUninstall(ctx context.Context, projectFlag, globalFlag bool, globalDir, projectDir string) (string, error) {
 	if projectFlag && globalFlag {
-		return "", errors.New("cannot uninstall both scopes at once; run uninstall separately for --global and --project")
+		return "", errors.New("cannot uninstall both scopes at once; run uninstall separately with --scope=global and --scope=project")
 	}
 
 	hasGlobal, hasProject, err := detectInstalledScopes(globalDir, projectDir)
@@ -182,7 +230,7 @@ func resolveScopeForUninstall(ctx context.Context, projectFlag, globalFlag bool,
 	switch {
 	case hasGlobal && hasProject:
 		if !cmdio.IsPromptSupported(ctx) {
-			return "", errors.New("skills are installed in both global and project scopes; use --global or --project to specify which to uninstall")
+			return "", errors.New("skills are installed in both global and project scopes; use --scope=global or --scope=project to specify which to uninstall")
 		}
 		scope, err := promptUninstallScopeSelection(ctx)
 		if err != nil {
@@ -230,10 +278,10 @@ func scopeNotInstalledError(scope, verb, projectDir string, hasGlobal, hasProjec
 			"no project-scoped skills found in the current directory.\n\n"+
 				"Project-scoped skills are detected based on your working directory.\n"+
 				"Make sure you are in the project root where you originally ran\n"+
-				"'databricks aitools install --project'.\n\n"+
+				"'databricks aitools install --scope=project'.\n\n"+
 				"Expected location: %s/", expectedPath)
 	} else {
-		msg = "no globally-scoped skills installed. Run 'databricks aitools install --global' to install"
+		msg = "no globally-scoped skills installed. Run 'databricks aitools install --scope=global' to install"
 	}
 
 	hint := crossScopeHint(scope, verb, hasGlobal, hasProject)
@@ -248,10 +296,10 @@ func scopeNotInstalledError(scope, verb, projectDir string, hasGlobal, hasProjec
 // The verb parameter (e.g. "update", "uninstall") controls the action in the hint message.
 func crossScopeHint(requestedScope, verb string, hasGlobal, hasProject bool) string {
 	if requestedScope == installer.ScopeProject && hasGlobal {
-		return fmt.Sprintf("Global skills are installed. Run without --project to %s those.", verb)
+		return fmt.Sprintf("Global skills are installed. Run with --scope=global to %s those.", verb)
 	}
 	if requestedScope == installer.ScopeGlobal && hasProject {
-		return fmt.Sprintf("Project-scoped skills are installed. Run without --global to %s those.", verb)
+		return fmt.Sprintf("Project-scoped skills are installed. Run with --scope=project to %s those.", verb)
 	}
 	return ""
 }