aitools: add --scope flag, deprecate --project/--global by jamesbroadhead · Pull Request #5234 · databricks/cli

jamesbroadhead · 2026-05-11T14:52:37Z

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.

github-actions · 2026-05-11T14:54:08Z

Approval status: pending

`/cmd/aitools/` - needs approval

8 files changed
Suggested: @simonfaltum
Also eligible: @lennartkats-db, @fjakobs, @Shridhad, @atilafassina, @keugenek, @arsenyinfo, @igrekun, @pkosiec, @MarioCadenas, @pffigueiredo, @ditadi, @calvarjorge, @renaudhartert-db, @hectorcast-db, @parthban-db, @tanmay-db, @Divyansh-db, @tejaskochar-db, @mihaimitrea-db, @chrisst, @rauchy

General files (require maintainer)

Files: NEXT_CHANGELOG.md
Based on git history:

@simonfaltum -- recent work in ./

_{Any maintainer (@andrewnester, @anton-107, @denik, @pietern, @shreyas-goenka, @simonfaltum, @renaudhartert-db) can approve all areas.

See OWNERS for ownership rules.}

Adds --scope=project|global|both as the single source of truth for scope selection on install/update/uninstall/list. Keeps --project and --global working via cobra.Deprecated (hidden from --help, emit stderr warning). Mixing --scope with --project/--global is rejected up front. Also documents the --agents auto-detect contract in install --help. Stacked-on-#4917 base rewritten onto current main (16 noisy merge/cherry-pick commits collapsed into this single change; underlying diff unchanged at 9 files / +219 / -13). Co-authored-by: Isaac

jamesbroadhead · 2026-05-18T21:43:49Z

👋 @simonfaltum — Claude here on James's behalf.

#4917 merged earlier today, so this PR is now stacked on main and no longer needs to wait. I've rebased the branch onto current main and force-pushed; the diff is now the actual scope-flag delta (9 files, +219/-13) without the merge noise from the old base.

Ready for a re-review whenever you've got a moment.

(comment posted by Claude)

Teaches list to render as a structured {release, skills[...], summary{}} document when --output json is passed. Text rendering is unchanged. Stacked on jb/aitools-interface (#5234). Original branch was rebased onto current main + that PR's tip; layout drift from #4917's pre-merge shape was reconciled (cmd/aitools/* paths, unexported listSkillsFn, 3-value installer.GetSkillsRef signature). Co-authored-by: Isaac

simonfaltum

I found a couple of should-fix items and one test gap. The affected package tests pass locally: go test ./cmd/aitools.

simonfaltum · 2026-05-19T07:45:15Z

+			// list: empty scope = show both. Both flags set is equivalent.
 			var scope string
-			if projectFlag {
+			switch {
+			case projectFlag && !globalFlag:
 				scope = installer.ScopeProject
-			} else if globalFlag {
+			case globalFlag && !projectFlag:
 				scope = installer.ScopeGlobal
 			}


Should-fix: this changes list --project --global from an error on main into a successful "both scopes" invocation. Since --scope=both is the new explicit spelling, I would keep the old validation for the deprecated flags so accidental invalid invocations don't start succeeding silently.

simonfaltum · 2026-05-19T07:45:15Z

+	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:
+		return false, false, fmt.Errorf("invalid --scope %q: must be one of project, global, both", scopeFlag)


Should-fix: for commands that pass allowBoth=false (install and uninstall), an invalid value like --scope=all still reports both as a valid option, but retrying with --scope=both immediately errors. Can this branch on allowBoth and say project or global for those commands?

simonfaltum · 2026-05-19T07:45:15Z

 				return err
 			}

+			projectFlag, globalFlag, err := parseScopeFlag(scopeFlag, projectFlag, globalFlag, true)


Test gap: parseScopeFlag is covered, and install/list have command-level tests, but update/uninstall don't exercise the new Cobra flag registration and RunE wiring. A small table test for --scope=project|global|both, invalid value, and legacy flag conflict would protect these paths.

jamesbroadhead requested a review from simonfaltum May 11, 2026 14:52

jamesbroadhead temporarily deployed to test-trigger-is May 11, 2026 14:53 — with GitHub Actions Inactive

jamesbroadhead mentioned this pull request May 11, 2026

Promote aitools skills-management commands to top-level #4917

Merged

6 tasks

jamesbroadhead had a problem deploying to test-trigger-is May 11, 2026 15:41 — with GitHub Actions Failure

jamesbroadhead temporarily deployed to test-trigger-is May 11, 2026 15:46 — with GitHub Actions Inactive

jamesbroadhead force-pushed the jb/aitools-interface branch from 526cd9c to a7e3d03 Compare May 12, 2026 20:13

jamesbroadhead temporarily deployed to test-trigger-is May 12, 2026 20:14 — with GitHub Actions Inactive

jamesbroadhead force-pushed the jb/aitools-interface branch from a7e3d03 to 37cf784 Compare May 13, 2026 14:32

jamesbroadhead temporarily deployed to test-trigger-is May 13, 2026 14:33 — with GitHub Actions Inactive

simonfaltum temporarily deployed to test-trigger-is May 18, 2026 17:39 — with GitHub Actions Inactive

simonfaltum temporarily deployed to test-trigger-is May 18, 2026 17:40 — with GitHub Actions Inactive

simonfaltum temporarily deployed to test-trigger-is May 18, 2026 18:01 — with GitHub Actions Inactive

simonfaltum temporarily deployed to test-trigger-is May 18, 2026 18:31 — with GitHub Actions Inactive

Base automatically changed from jbroadhead/aitools-public to main May 18, 2026 19:26

simonfaltum temporarily deployed to test-trigger-is May 18, 2026 19:31 — with GitHub Actions Inactive

simonfaltum temporarily deployed to test-trigger-is May 18, 2026 20:33 — with GitHub Actions Inactive

jamesbroadhead force-pushed the jb/aitools-interface branch from 8f0319a to 7666312 Compare May 18, 2026 21:43

jamesbroadhead temporarily deployed to test-trigger-is May 18, 2026 21:44 — with GitHub Actions Inactive

jamesbroadhead mentioned this pull request May 18, 2026

aitools list: emit JSON via --output json #5233

Open

4 tasks

simonfaltum reviewed May 19, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

aitools: add --scope flag, deprecate --project/--global#5234
jamesbroadhead wants to merge 1 commit into
mainfrom
jb/aitools-interface

jamesbroadhead commented May 11, 2026

Uh oh!

github-actions Bot commented May 11, 2026 •

edited

Loading

Uh oh!

jamesbroadhead commented May 18, 2026

Uh oh!

simonfaltum left a comment

Uh oh!

simonfaltum May 19, 2026

Uh oh!

simonfaltum May 19, 2026

Uh oh!

simonfaltum May 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

jamesbroadhead commented May 11, 2026

Summary

Why land this with the rename

Surface

Test plan

Uh oh!

github-actions Bot commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Approval status: pending

/cmd/aitools/ - needs approval

General files (require maintainer)

Uh oh!

jamesbroadhead commented May 18, 2026

Uh oh!

simonfaltum left a comment

Choose a reason for hiding this comment

Uh oh!

simonfaltum May 19, 2026

Choose a reason for hiding this comment

Uh oh!

simonfaltum May 19, 2026

Choose a reason for hiding this comment

Uh oh!

simonfaltum May 19, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions Bot commented May 11, 2026 •

edited

Loading

`/cmd/aitools/` - needs approval