Skip to content

aitools: store the auto-install state and opt-out, gate it in cli-compat - #7701

Merged
anton-107 merged 2 commits into
mainfrom
aitools/auto-install-state-opt-out
Nov 17, 2026
Merged

anton-107 merged 2 commits into
mainfrom
aitools/auto-install-state-opt-out

Conversation

@anton-107

Copy link
Copy Markdown
Contributor

First of three stacked PRs that install Databricks AI tools automatically on the first run of a new CLI version. This one stores the state and the opt-out and adds the remote gate; nothing installs yet.

Summary

~/.databricks/aitools/auto-install.json      # libs/aitools/autoinstall/state.go
  { "last_version": "...", "attempts": N, "opted_out": true }

databricks aitools auto-install disable      -> opted_out = true
databricks aitools auto-install enable       -> opted_out = false
                                                (+ warns if DATABRICKS_AITOOLS_AUTO_INSTALL=false is set)
databricks aitools uninstall (global scope)  -> opted_out = true

internal/build/cli-compat.json entry
  { "appkit": ..., "skills": ..., "auto_install": true }   # gate; no entry sets it, so it stays off
  clicompat.ResolveAutoInstall(ctx, cliVersion)
  • The state is a dedicated file, not a libs/cache entry: cache paths include the CLI version, entries expire, and databricks cache clear wipes them, so an opt-out would not survive an upgrade.
  • Only a global-scope uninstall opts out (auto-install only touches global scope); partial global uninstalls (--skills, --agents) count, because the update path would re-add removed skills. Uninstall prints nothing new; its --help says it.
  • The gate is a per-entry field because a top-level manifest key would fail older CLIs' semver key validation. Older CLIs ignore unknown entry fields. TestManifestLeavesAutoInstallOff keeps it off until the change that turns it on updates that test; the bump-cli-compat skill now says to carry the flag to a new entry.
  • Changelog fragment: .nextchanges/cli/aitools-auto-install-opt-out.md.

Review order

  1. libs/aitools/autoinstall/state.go: the state file, SetOptedOut, the env var.
  2. cmd/aitools/autoinstall.go, cmd/aitools/uninstall.go: the toggle commands and the uninstall opt-out.
  3. libs/clicompat/clicompat.go and its test: the auto_install gate.

Supporting: acceptance/cmd/aitools/auto-install/, .agents/skills/bump-cli-compat/SKILL.md, the changelog fragment.

Evidence

  • acceptance/cmd/aitools/auto-install/enable-disable (new):
    >>> [CLI] aitools auto-install disable
    Automatic installation of Databricks AI tools is disabled.
    >>> auto_install_state
    { "opted_out": true }
    >>> DATABRICKS_AITOOLS_AUTO_INSTALL=false [CLI] aitools auto-install enable
    Automatic installation of Databricks AI tools is enabled.
    DATABRICKS_AITOOLS_AUTO_INSTALL still disables it in this environment; unset it to let it run.
    === a global uninstall turns it off      -> { "opted_out": true }
    === a project uninstall leaves it on     -> {}
    
  • TestResolveAutoInstall (range resolution of the flag) and TestManifestLeavesAutoInstallOff in libs/clicompat.
  • Locally on Linux: go test ./cmd/aitools/... ./libs/aitools/... ./libs/clicompat/... and the cmd/aitools, experimental/aitools and help acceptance suites pass; lint, whitespace, deadcode and changelog checks pass; GOOS=windows/darwin build and vet pass.

Merge Danger

Door: two-way

A new command, a new file under ~/.databricks/aitools, and an optional manifest field nothing sets.

Blast Radius: small

  • aitools uninstall --scope=global (or the default global uninstall) now writes ~/.databricks/aitools/auto-install.json. A write failure is a warning and does not fail the uninstall.
  • Windows/macOS behavior is not run here, only built and vetted.

This pull request and its description were written by Isaac.

@anton-107
anton-107 requested review from a team and lennartkats-db as code owners November 16, 2026 19:37
@github-actions github-actions Bot added the aitools AI tools (databricks aitools) related changes label Nov 16, 2026
@anton-107
anton-107 force-pushed the aitools/auto-install-state-opt-out branch from f60fc1f to 258418b Compare November 16, 2026 19:37
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Commit: 8926e091f | Workflow run

Regression test report

Selected 1 changed tests (limit=20, 0 not selected)

1 tests: regression=1 unreleased=0 coverage=0 failing=0
test branch main (bdc5f0e) latest (v1.26.0)
TestAccept/cmd/aitools/auto-install/enable-disable ✅ ❌ ❌
TestAccept/cmd/aitools/auto-install/enable-disable: branch ✅ | main (bdc5f0e) ❌ | latest (v1.26.0) ❌

main (bdc5f0e):

acceptance_test.go:1248: Substituted DATABRICKS_SKILLS_BASE_URL "$DATABRICKS_HOST" -> "http://127.0.0.1:35575" ("[DATABRICKS_HOST]")
    acceptance_test.go:1380: Diff:
        --- cmd/aitools/auto-install/enable-disable/output.txt
        +++ /tmp/TestAcceptcmdaitoolsauto-installenable-disable826394319/002/output.txt
        @@ -7,71 +7,106 @@
         === disable stores the opt-out
         
         >>> [CLI] aitools auto-install disable
        -Automatic installation of Databricks AI tools is disabled.
        +Install Databricks skills and plugins into your coding agent so it can work
        +effectively with Databricks resources (bundles, jobs, SQL, and more).
         
        ->>> auto_install_state
        -{
        -  "opted_out": true
        -}
        +Supported agents: Claude Code, Cursor, Codex CLI, OpenCode, GitHub Copilot, Antigravity, Pi, Gemini CLI, Goose, Kiro.
         
        -=== enable clears it
        +Skills and plugins are sourced from
        +https://github.com/databricks/databricks-agent-skills
         
        ->>> [CLI] aitools auto-install enable
        -Automatic installation of Databricks AI tools is enabled.
        +Usage:
        +  databricks aitools [command]
         
        +Available Commands:
        +  install     Install Databricks skills and plugins for coding agents
        +  list        List installed skills and plugins
        +  uninstall   Uninstall Databricks skills and plugins
        +  update      Update installed skills and plugins
        +  version     Show installed skills and plugins version
        +
        +Flags:
        +  -h, --help[=true|false]   help for aitools
        +
        +Global Flags:
        +      --debug[=true|false]   enable debug logging
        +  -o, --output type          output type: text or json (default text)
        +  -p, --profile string       ~/.databrickscfg profile
        +  -t, --target string        bundle target to use (if applicable)
        +
        +Use "databricks aitools [command] --help" for more information about a command.
        +
         >>> auto_install_state
        -{}
        +(no auto-install state)
         
        -=== enable says when the environment still turns it off
        +=== enable clears it
         
        ->>> DATABRICKS_AITOOLS_AUTO_INSTALL=false [CLI] aitools auto-install enable
        -Automatic installation of Databricks AI tools is enabled.
        -DATABRICKS_AITOOLS_AUTO_INSTALL still disables it in this environment; unset it to let it run.
        +>>> [CLI] aitools auto-install enable
        +Install Databricks skills and plugins into your coding agent so it can work
        +effectively with Databricks resources (bundles, jobs, SQL, and more).
         
        -=== disable replaces a state file it cannot read
        +Supported agents: Claude Code, Cursor, Codex CLI, OpenCode, GitHub Copilot, Antigravity, Pi, Gemini CLI, Goose, Kiro.
         
        ->>> [CLI] aitools auto-install disable
        -Automatic installation of Databricks AI tools is disabled.
        +Skills and plugins are sourced from
        +https://github.com/databricks/databricks-agent-skills
         
        ->>> auto_install_state
        -{
        -  "opted_out": true
        -}
        +Usage:
        +  databricks aitools [command]
         
        -=== a global uninstall that removes nothing leaves it on
        +Available Commands:
        +  install     Install Databricks skills and plugins for coding agents
        +  list        List installed skills and plugins
        +  uninstall   Uninstall Databricks skills and plugins
        +  update      Update installed skills and plugins
        +  version     Show installed skills and plugins version
         
        ->>> [CLI] aitools uninstall --scope=global
        -Error: no skills or plugins installed
        +Flags:
        +  -h, --help[=true|false]   help for aitools
         
        -Exit code: 1
        +Global Flags:
        +      --debug[=true|false]   enable debug logging
        +  -o, --output type          output type: text or json (default text)
        +  -p, --profile string       ~/.databrickscfg profile
        +  -t, --target string        bundle target to use (if applicable)
         
        +Use "databricks aitools [command] --help" for more information about a command.
        +
         >>> auto_install_state
        -{}
        +(no auto-install state)
         
        -=== a global uninstall of a mistyped skill leaves it on
        +=== enable says when the environment still turns it off
         
        ->>> [CLI] aitools uninstall --scope=global --skills databricks-tset
        -Error: skill "databricks-tset" is not installed
        +>>> DATABRICKS_AITOOLS_AUTO_INSTALL=false [CLI] aitools auto-install enable
        +Install Databricks skills and plugins into your coding agent so it can work
        +effectively with Databricks resources (bundles, jobs, SQL, and more).
         
        -Exit code: 1
        +Supported agents: Claude Code, Cursor, Codex CLI, OpenCode, GitHub Copilot, Antigravity, Pi, Gemini CLI, Goose, Kiro.
         
        ->>> auto_install_state
        -{}
        +Skills and plugins are sourced from
        +https://github.com/databricks/databricks-agent-skills
         
        -=== a global uninstall turns it off
        +Usage:
        +  databricks aitools [command]
         
        ->>> [CLI] aitools uninstall --scope=global
        -Uninstalled 1 skill.
        +Available Commands:
        +  install     Install Databricks skills and plugins for coding agents
        +  list        List installed skills and plugins
        +  uninstall   Uninstall Databricks skills and plugins
        +  update      Update installed skills and plugins
        +  version     Show installed skills and plugins version
         
        ->>> auto_install_state
        -{
        -  "opted_out": true
        -}
        +Flags:
        +  -h, --help[=true|false]   help for aitools
         
        -=== a project uninstall leaves it on
        +Global Flags:
        +      --debug[=true|false]   enable debug logging
        +  -o, --output type          output type: text or json (default text)
        +  -p, --profile string       ~/.databrickscfg profile
        +  -t, --target string        bundle target to use (if applicable)
         
        ->>> [CLI] aitools uninstall --scope=project
        -Uninstalled 1 skill.
        +Use "databricks aitools [command] --help" for more information about a command.
         
        ->>> auto_install_state
        -{}
        +=== disable replaces a state file it cannot read
        +script: line 227: [TEST_TMP_DIR]/home/.databricks/aitools/auto-install.json: No such file or directory
        +
        +Exit code: 1
        
FAIL

latest (v1.26.0):

acceptance_test.go:1248: Substituted DATABRICKS_SKILLS_BASE_URL "$DATABRICKS_HOST" -> "http://127.0.0.1:36823" ("[DATABRICKS_HOST]")
    acceptance_test.go:1380: Diff:
        --- cmd/aitools/auto-install/enable-disable/output.txt
        +++ /tmp/TestAcceptcmdaitoolsauto-installenable-disable529376778/002/output.txt
        @@ -7,71 +7,106 @@
         === disable stores the opt-out
         
         >>> [CLI] aitools auto-install disable
        -Automatic installation of Databricks AI tools is disabled.
        +Install Databricks skills and plugins into your coding agent so it can work
        +effectively with Databricks resources (bundles, jobs, SQL, and more).
         
        ->>> auto_install_state
        -{
        -  "opted_out": true
        -}
        +Supported agents: Claude Code, Cursor, Codex CLI, OpenCode, GitHub Copilot, Antigravity, Pi, Gemini CLI, Goose, Kiro.
         
        -=== enable clears it
        +Skills and plugins are sourced from
        +https://github.com/databricks/databricks-agent-skills
         
        ->>> [CLI] aitools auto-install enable
        -Automatic installation of Databricks AI tools is enabled.
        +Usage:
        +  databricks aitools [command]
         
        +Available Commands:
        +  install     Install Databricks skills and plugins for coding agents
        +  list        List installed skills and plugins
        +  uninstall   Uninstall Databricks skills and plugins
        +  update      Update installed skills and plugins
        +  version     Show installed skills and plugins version
        +
        +Flags:
        +  -h, --help   help for aitools
        +
        +Global Flags:
        +      --debug            enable debug logging
        +  -o, --output type      output type: text or json (default text)
        +  -p, --profile string   ~/.databrickscfg profile
        +  -t, --target string    bundle target to use (if applicable)
        +
        +Use "databricks aitools [command] --help" for more information about a command.
        +
         >>> auto_install_state
        -{}
        +(no auto-install state)
         
        -=== enable says when the environment still turns it off
        +=== enable clears it
         
        ->>> DATABRICKS_AITOOLS_AUTO_INSTALL=false [CLI] aitools auto-install enable
        -Automatic installation of Databricks AI tools is enabled.
        -DATABRICKS_AITOOLS_AUTO_INSTALL still disables it in this environment; unset it to let it run.
        +>>> [CLI] aitools auto-install enable
        +Install Databricks skills and plugins into your coding agent so it can work
        +effectively with Databricks resources (bundles, jobs, SQL, and more).
         
        -=== disable replaces a state file it cannot read
        +Supported agents: Claude Code, Cursor, Codex CLI, OpenCode, GitHub Copilot, Antigravity, Pi, Gemini CLI, Goose, Kiro.
         
        ->>> [CLI] aitools auto-install disable
        -Automatic installation of Databricks AI tools is disabled.
        +Skills and plugins are sourced from
        +https://github.com/databricks/databricks-agent-skills
         
        ->>> auto_install_state
        -{
        -  "opted_out": true
        -}
        +Usage:
        +  databricks aitools [command]
         
        -=== a global uninstall that removes nothing leaves it on
        +Available Commands:
        +  install     Install Databricks skills and plugins for coding agents
        +  list        List installed skills and plugins
        +  uninstall   Uninstall Databricks skills and plugins
        +  update      Update installed skills and plugins
        +  version     Show installed skills and plugins version
         
        ->>> [CLI] aitools uninstall --scope=global
        -Error: no skills or plugins installed
        +Flags:
        +  -h, --help   help for aitools
         
        -Exit code: 1
        +Global Flags:
        +      --debug            enable debug logging
        +  -o, --output type      output type: text or json (default text)
        +  -p, --profile string   ~/.databrickscfg profile
        +  -t, --target string    bundle target to use (if applicable)
         
        +Use "databricks aitools [command] --help" for more information about a command.
        +
         >>> auto_install_state
        -{}
        +(no auto-install state)
         
        -=== a global uninstall of a mistyped skill leaves it on
        +=== enable says when the environment still turns it off
         
        ->>> [CLI] aitools uninstall --scope=global --skills databricks-tset
        -Error: skill "databricks-tset" is not installed
        +>>> DATABRICKS_AITOOLS_AUTO_INSTALL=false [CLI] aitools auto-install enable
        +Install Databricks skills and plugins into your coding agent so it can work
        +effectively with Databricks resources (bundles, jobs, SQL, and more).
         
        -Exit code: 1
        +Supported agents: Claude Code, Cursor, Codex CLI, OpenCode, GitHub Copilot, Antigravity, Pi, Gemini CLI, Goose, Kiro.
         
        ->>> auto_install_state
        -{}
        +Skills and plugins are sourced from
        +https://github.com/databricks/databricks-agent-skills
         
        -=== a global uninstall turns it off
        +Usage:
        +  databricks aitools [command]
         
        ->>> [CLI] aitools uninstall --scope=global
        -Uninstalled 1 skill.
        +Available Commands:
        +  install     Install Databricks skills and plugins for coding agents
        +  list        List installed skills and plugins
        +  uninstall   Uninstall Databricks skills and plugins
        +  update      Update installed skills and plugins
        +  version     Show installed skills and plugins version
         
        ->>> auto_install_state
        -{
        -  "opted_out": true
        -}
        +Flags:
        +  -h, --help   help for aitools
         
        -=== a project uninstall leaves it on
        +Global Flags:
        +      --debug            enable debug logging
        +  -o, --output type      output type: text or json (default text)
        +  -p, --profile string   ~/.databrickscfg profile
        +  -t, --target string    bundle target to use (if applicable)
         
        ->>> [CLI] aitools uninstall --scope=project
        -Uninstalled 1 skill.
        +Use "databricks aitools [command] --help" for more information about a command.
         
        ->>> auto_install_state
        -{}
        +=== disable replaces a state file it cannot read
        +script: line 227: [TEST_TMP_DIR]/home/.databricks/aitools/auto-install.json: No such file or directory
        +
        +Exit code: 1
        
FAIL

@eng-dev-ecosystem-bot

eng-dev-ecosystem-bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

✅ Integration test report

Commit: 8926e09

Run: 44103348944

Env 💚​RECOVERED ✅​pass 🙈​skip Time
💚​ aws linux-2core-8gb 1 270 16 8:56
💚​ aws-windows-latest-4core-16gb 1 272 14 7:08
💚​ azure linux-2core-8gb 1 269 16 7:38
💚​ azure-windows-latest-4core-16gb 1 271 14 6:11
💚​ gcp linux-2core-8gb 1 270 16 7:16
💚​ gcp-windows-latest-4core-16gb 1 272 14 7:49
Test Name aws linux-2core-8gb aws-windows-latest-4core-16gb azure linux-2core-8gb azure-windows-latest-4core-16gb gcp linux-2core-8gb gcp-windows-latest-4core-16gb
💚​ TestAccept 💚​R 💚​R 💚​R 💚​R 💚​R 💚​R
Top 4 slowest tests (at least 2 minutes):
duration env testname
3:54 aws-windows-latest-4core-16gb TestAccept
3:33 azure-windows-latest-4core-16gb TestAccept
3:25 gcp-windows-latest-4core-16gb TestAccept
2:46 gcp-windows-latest-4core-16gb TestFilerWorkspaceFilesExtensionsReadDir

@simonfaltum simonfaltum left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Automated review from simonfaltum's review agent (pr-review skill) at 258418b. Each finding was verified against the code; simonfaltum may follow up.

No blocking issues found, approving. 12 non-blocking comment(s) and 3 question(s) below.

This first PR of the stack stores the auto-install state and opt-out, adds aitools auto-install enable/disable, makes a global uninstall opt out, and adds an auto_install gate to the cli-compat manifest, still off everywhere. The structure is sound, CI is green and nothing is blocking. Before the gate is turned on, it's worth fixing two things: a global uninstall that fails or removes nothing still opts the user out, and older CLIs remove auto_install when they rewrite the shared manifest cache. Smaller items: a mistyped subcommand exits 0, the README isn't updated, unit tests are missing, and a few nits. There are also three non-blocking questions about shipping the visible command before the feature, reinstall keeping the opt-out, and how far the remote off switch reaches.

Questions

  1. This PR makes databricks aitools auto-install visible and adds a changelog entry, but nothing installs until #7702 lands, and auto-install enable prints "Automatic installation of Databricks AI tools is enabled." #7702's description says it adds no changelog fragment because nothing is user-visible while the gate is off. Should the command be hidden (as legacy_skills.go does) and the changelog fragment moved to the PR that turns the gate on? Or is shipping the opt-out first intended, for example to record opt-outs before launch? (non-blocking)
  2. After databricks aitools uninstall --scope=global, a later databricks aitools install --scope=global keeps opted_out: true; nothing in the install path touches the state. A user who uninstalls and reinstalls to fix a broken setup never gets the automatic updates the help text describes, and nothing tells them. Should an explicit global install clear an opt-out that came from uninstall (which would mean recording where the opt-out came from), or at least mention that auto-install is still off? (non-blocking)
  3. The AutoInstall comment says the feature "can be turned on (or off again) remotely". But a change only reaches a machine on its first run of a version after the change. And once a release ships with the gate on, turning it off doesn't reach machines that use a fresh or stale local cache or the embedded manifest. Is that the intended guarantee for the off switch, or should the comment be narrowed or the gate re-checked? (non-blocking)

Accepted answers

  • Why does a partial global uninstall opt out?
  • Why does uninstall not tell the user it opted out?
  • Why a per-entry manifest field that must be copied forward?
  • Why add ResolveAutoInstall, LastVersion and Attempts with no caller?

Comments outside the changed lines

  • [nit] .github/PULL_REQUEST_TEMPLATE.md: .agents/skills/pr-checklist/SKILL.md asks agent-written PRs to follow .github/PULL_REQUEST_TEMPLATE.md exactly: ## Changes, ## Why, ## Tests, with no new sections such as ## Summary, and a single italicized disclosure line at the end. Consider restructuring the description into those sections.

Comment thread cmd/aitools/uninstall.go
Comment on lines +112 to +119
// Auto-install only ever installs in global scope, so only a global
// uninstall could be undone by it on the next CLI upgrade. A partial
// one counts too: the update it runs re-adds removed skills.
if scope == installer.ScopeGlobal {
if err := autoinstall.SetOptedOut(ctx, true); err != nil {
log.Warnf(ctx, "Could not turn off the automatic installation of Databricks AI tools: %v", err)
}
}

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nice to have] The opt-out is saved before uninstallSkillsFn runs, so a global uninstall that fails or finds nothing to remove still turns auto-install off, without saying so. Two examples: databricks aitools uninstall --scope=global --skills databricks-tset (a typo) fails with "is not installed"; and a bare databricks aitools uninstall on a machine with no global install falls through to global scope (scope.go:280-284) and returns ErrNothingInstalled. Both leave opted_out: true, and so does the legacy-install error path. Consider calling SetOptedOut only after uninstallSkillsFn returns without error, and add a case to the acceptance test.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 8926e09: the opt-out is now saved only after a global uninstall succeeds and removed something. The acceptance test covers both of your examples (nothing installed, and a mistyped --skills); each leaves the state unchanged.

Comment on lines +60 to +65
// AutoInstall turns on the automatic installation of Databricks AI tools
// on the first run of a new CLI version in this range. Off when absent, so
// the feature ships off and can be turned on (or off again) remotely; a
// change reaches a machine on its first run of a version after the change.
// CLIs that predate the field ignore it.
AutoInstall bool `json:"auto_install,omitempty"`

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nice to have] Older CLIs don't just ignore auto_install; they also remove it from the cache. In v1.26.0 and earlier, writeLocalManifest re-marshals the parsed two-field Entry into os.UserCacheDir()/databricks/compat-manifest.json, a path every CLI version shares. Once the remote manifest sets auto_install: true, an older CLI on the same machine (a second install, or one bundled with an IDE) that runs aitools install or apps init rewrites the cache without the field. A newer CLI then reads the gate as off: for up to an hour from a fresh cache, and for longer from a stale one when the remote fetch fails. Released binaries can't be changed, so the new code should stay off that file: give the cache a new file name (e.g. compat-manifest-v2.json), ideally storing the fetched bytes as they are so the next new field doesn't hit the same problem.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, this is real. The gate stays off in this PR, so nothing reads the field yet. I'll move the new code off the shared cache file before the change that turns the gate on, rather than growing this PR.


func newAutoInstallCmd() *cobra.Command {
cmd := &cobra.Command{
Use: "auto-install",

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nice to have] The auto-install group has no RunE. For a non-root command, cobra's legacyArgs accepts any arguments and then shows help, so databricks aitools auto-install disabel prints help and exits 0 with the setting unchanged. A script that turns auto-install off would never notice. Add RunE: root.ReportUnknownSubcommand, as the repo's other command groups do; cmd/aitools/install.go already imports cmd/root.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 8926e09: added RunE: root.ReportUnknownSubcommand, so auto-install disabel now fails with exit 1.

Ask the user for the **minimum CLI version** that supports the new features.

Add a new entry keyed to that CLI version with the new `appkit` and `"skills": "latest"`. Update `AgentSkillsFallbackVersion` in `internal/build/clicompat.go` to the tested skills version. If skills compatibility changed, replace `"latest"` in the affected older ranges with the last compatible release. Preserve unrelated AppKit and skills compatibility boundaries.
Add a new entry keyed to that CLI version with the new `appkit` and `"skills": "latest"`. If the previous highest entry has `"auto_install": true`, copy it to the new entry: it turns on the automatic installation of AI tools for its range, so a new entry without it turns the feature off for every newer CLI. Update `AgentSkillsFallbackVersion` in `internal/build/clicompat.go` to the tested skills version. If skills compatibility changed, replace `"latest"` in the affected older ranges with the last compatible release. Preserve unrelated AppKit and skills compatibility boundaries.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nice to have] This adds the "copy auto_install to the new entry" step to the skill, but internal/build/README.md describes the same procedure and was not updated. A maintainer who follows the README's "Breaking changes" step (line 65) would add an entry without the flag and turn the feature off for every newer CLI. The "Manifest format" section (line 7) doesn't list the field, and the "Trust model" (line 83) says the manifest can only steer clients to published tags, when it can now also trigger installs. Update all three.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 8926e09: the README now covers the field in the format section, the copy-forward step for breaking-change entries, and the trust model.

// SetOptedOut turns auto-install off (true) or back on (false), keeping the
// rest of the state. A state file that cannot be read is replaced: the user's
// explicit choice matters more than a broken record.
func SetOptedOut(ctx context.Context, optedOut bool) error {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nice to have] .agents/rules/testing.md asks for a test file for each source file. The contract the next PR relies on, SetOptedOut keeping LastVersion and Attempts, isn't tested anywhere, because the acceptance test never has those fields. Add a small state_test.go covering Load on a missing or corrupt file, SetOptedOut keeping the other fields, and EnvOptedOut parsing.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added libs/aitools/autoinstall/state_test.go in 8926e09: Load on a missing or corrupt file, SetOptedOut keeping LastVersion and Attempts (and replacing a corrupt file), and EnvOptedOut for each value.

Comment on lines +11 to +12
title "enable clears it"
trace $CLI aitools auto-install enable

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nit] The acceptance harness passes the developer's environment to the CLI (auth.ProcessEnv drops only auth variables), so with DATABRICKS_AITOOLS_AUTO_INSTALL=false exported, this step prints the "still disables it" warning and the golden comparison fails. Add unset DATABRICKS_AITOOLS_AUTO_INSTALL at the top of the script, or set Env.DATABRICKS_AITOOLS_AUTO_INSTALL = "true" in test.toml, as the harness already does for DATABRICKS_CLI_DISABLE_UPDATE_CHECK. An empty value won't work, because EnvOptedOut treats empty as off.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 8926e09: test.toml now sets DATABRICKS_AITOOLS_AUTO_INSTALL = "true". Checked by running with =false exported.

Comment on lines +22 to +28
$CLI aitools auto-install enable > /dev/null 2>&1

title "a global uninstall turns it off"
$CLI aitools install --skills-only --scope=global --agents=cursor &> LOG.install-global
trace $CLI aitools uninstall --scope=global
trace auto_install_state
$CLI aitools auto-install enable > /dev/null 2>&1

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nit] Lines 22 and 28 run $CLI aitools auto-install enable > /dev/null 2>&1, and .agents/rules/testing.md asks for LOG.<name> instead of /dev/null. Use &> LOG.enable-reset (as the install steps already do), or trace the steps, since their output is deterministic. A failing reset is then visible under go test -v.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 8926e09: the reset steps now write to LOG.enable-reset-*.

Comment thread cmd/aitools/uninstall.go Outdated
// Auto-install only ever installs in global scope, so only a global
// uninstall could be undone by it on the next CLI upgrade. A partial
// one counts too: the update it runs re-adds removed skills.
if scope == installer.ScopeGlobal {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nit] When the working directory is $HOME, ProjectSkillsDir and GlobalSkillsDir are the same directory. So databricks aitools uninstall --scope=project run from ~ removes the global install but stores no opt-out, and auto-install would put it back. Checking dir == globalDir instead of scope == installer.ScopeGlobal covers this.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Leaving this as it is. A project-scope uninstall run from ~ is an edge case, and keying on the directory would make --scope=project opt out in that one place, which is harder to explain than the scope rule in the help text.

Comment thread libs/clicompat/clicompat_test.go Outdated
Comment on lines +356 to +357
// The remote manifest is this same file on main, so turning auto_install on
// anywhere is a launch decision: change this test in the PR that makes it.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nit] .agents/rules/comments.md asks for Go doc comments that start with the function name, and the other tests in this file follow that. Reword to // TestManifestLeavesAutoInstallOff checks ....

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 8926e09.

Comment thread libs/aitools/autoinstall/state.go Outdated
Comment on lines +94 to +95
// EnvVar turns auto-install off when set to false (or 0, no, off).
const EnvVar = "DATABRICKS_AITOOLS_AUTO_INSTALL"

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nit] The Go style guide (.agents/rules/style-guide-go.md) asks for named constants at the top of the file. Move EnvVar up next to stateFileName.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 8926e09.

First of three changes that install Databricks AI tools automatically on
the first run of a new CLI version. This one stores the state and the
opt-out and adds the remote gate; nothing installs yet.

- ~/.databricks/aitools/auto-install.json holds last_version, attempts
  and opted_out. It is a dedicated file, not a libs/cache entry, so an
  opt-out survives upgrades and `databricks cache clear`.
- `databricks aitools auto-install disable|enable` toggles the opt-out;
  enable warns when DATABRICKS_AITOOLS_AUTO_INSTALL=false is set.
- A global-scope `databricks aitools uninstall` (including --skills and
  --agents) opts out.
- cli-compat.json entries get an optional auto_install field, resolved by
  clicompat.ResolveAutoInstall. No entry sets it, and
  TestManifestLeavesAutoInstallOff keeps it off.

Co-authored-by: Isaac <no-reply@databricks.com>
@anton-107
anton-107 force-pushed the aitools/auto-install-state-opt-out branch from 258418b to c5eef9c Compare November 17, 2026 10:30
- A global uninstall opts out only when it removed something, so a
  mistyped --skills or an empty scope no longer turns auto-install off.
- `aitools auto-install <typo>` now fails instead of printing help and
  exiting 0.
- Document auto_install in internal/build/README.md (format, the
  copy-forward step for new entries, the trust model).
- Say that any non-true DATABRICKS_AITOOLS_AUTO_INSTALL value opts out,
  and move EnvVar next to the other constant.
- Add unit tests for the state file; pin the env var in the acceptance
  test and log the reset steps instead of discarding them.

Co-authored-by: Isaac <no-reply@databricks.com>
@anton-107
anton-107 added this pull request to the merge queue Nov 17, 2026
Merged via the queue into main with commit 52ade19 Nov 17, 2026
29 checks passed
@anton-107
anton-107 deleted the aitools/auto-install-state-opt-out branch November 17, 2026 14:59
anton-107 added a commit that referenced this pull request Nov 17, 2026
#7701 landed on main as a squash of this branch's base; its conflicts resolve
to this branch's side, as main has not changed those files since.

Co-authored-by: Isaac <no-reply@databricks.com>
deco-sdk-tagging Bot added a commit that referenced this pull request Nov 19, 2026
## Release v1.27.0

### Notable Changes

 * `databricks aitools install`, `update` and `uninstall` now exit with code 1 when they do nothing they were asked to. `install` fails when it sets up nothing: no coding agent is detected, every agent is skipped or fails to install, or no skill in the release can be installed (also with `--path`). `update` fails when every update or check it attempts fails, and `uninstall` when every removal it attempts fails. Scripts that ran these commands as a best-effort step and relied on exit code 0 should handle the new exit code. ([#7481](#7481))
 * Add `file:<path>` selectors to `pipelines run` and pipeline `bundle run`. `--refresh` and `--full-refresh` now use space-separated lists, such as `--refresh "orders payments"`, instead of comma-separated lists. Single names containing spaces now require backticks, e.g. ``--refresh 'table:`order details`'``. ([#7184](#7184))
 * The Databricks CLI is now available on PyPI as `databricks`: run it with `uvx databricks`, or install it with `uv tool install databricks`, `pipx install databricks` or `pip install databricks`. The package contains only the prebuilt CLI binary. Uninstall the legacy `databricks-cli` package first, since both install a `databricks` command. ([#7704](#7704), [#7777](#7777))

### CLI

 * Add `databricks sandbox fs` commands (`cp`, `ls`, `cat`, `mkdir`, `rm`) to transfer files between your local filesystem and sandboxes using `<sandbox-id>:/path`. ([#7372](#7372))
 * `databricks fs` commands retry reads (stat, list, open) and deletes on DBFS and Volumes when the server returns a transient error or does not respond within the HTTP timeout. ([#7556](#7556))
 * Retry UC Volumes file operations (`fs cp`, `fs ls`, `fs rm`, bundle uploads to Volumes) when the Files API returns HTTP 408, 429, 502, 503 or 504 (for example "AWS S3 is throttling requests"), or on a transient network error; this regressed in v1.10.0. ([#7559](#7559))
 * Stop warning when the host metadata request (`/.well-known/databricks-config`) times out; the CLI already falls back to your config, and the message is still shown with `--debug`. ([#7752](#7752))
 * Add `databricks aitools auto-install disable` and `enable` to turn off (or back on) the automatic installation of Databricks AI tools on CLI upgrades. A global-scope `databricks aitools uninstall` also turns it off. ([#7701](#7701))
 * Stop printing the Databricks AI tooling install hint on `auth`, `configure`, `current-user me`, `version`, `help`, and shell-completion commands. ([#7452](#7452))
 * When Codex, Cursor, GitHub Copilot CLI, OpenCode, Gemini CLI, Antigravity, Pi, Goose or Kiro run the CLI without Databricks skills installed for that agent, the CLI now prints a one-line hint to install them with `databricks aitools install --agents <agent> --scope global`, previously shown only to Claude Code. ([#7586](#7586))
 * `databricks aitools install` now rejects an unknown `--agents` name before it shows the scope prompt, instead of after. ([#7469](#7469))
 * `databricks aitools install` no longer asks "Proceed?" after the agent picker; the picker selection confirms the plan. The picker title now shows the install scope, its hint says Enter installs, `--skills-only` runs label plugin agents "skills" and pre-check every agent whose config dir exists, and the plan summary after it is reduced to the scope line. ([#7478](#7478))
 * `databricks aitools install --output json` reports more specific `error_category` values: `SKILLS_FETCH_FAILED`, `RELEASE_LOOKUP_FAILED`, `RATE_LIMITED`, `MANIFEST_INVALID`, `STATE_INVALID` and `PLUGIN_CLI_TIMEOUT`. A coding agent CLI that does not answer in time is now reported as `timed out after <duration>`, followed by any stderr it wrote before it was stopped. ([#7475](#7475))
 * `databricks aitools install` no longer prompts when a coding agent runs it, even in a pseudo-terminal; it uses the non-interactive defaults instead and prints a note saying so. ([#7477](#7477))
 * `databricks aitools install` now prints the directory it installed skills into (for example `Installed 1 skill in ~/.databricks/aitools/skills.`), so agents can open the installed `SKILL.md` files without searching for them. ([#7668](#7668))
 * `databricks aitools install` now ends a failed install with a step to recover, in the text output and in a new `recovery` field of `--output json`. ([#7480](#7480))
 * `databricks aitools install` now installs plugins for the other coding agents even when installing skill files fails. ([#7479](#7479))
 * `databricks aitools install` now installs skill files for a detected coding agent whose CLI is not on PATH (for example a Claude Code desktop or IDE install), unless it already has the plugin, says how to switch to the plugin later, and warns when the current project also has the plugin. `databricks aitools update` no longer tries to install the plugin for such an agent, and no longer writes skill files next to a plugin that such an agent already has. ([#7482](#7482))
 * Fix `databricks aitools install` waiting a long time on an unreachable or slow workspace while it resolves authentication for telemetry; that wait is now limited to a few seconds. ([#7468](#7468))
 * `databricks aitools install`, `update` and `list` now refuse a skills manifest that names a skill or file outside the skills directory, before writing any skill files. A skill whose name or file paths are not portable is skipped with a warning, and `update` keeps its installed copy. ([#7722](#7722))
 * `databricks aitools install` and `databricks aitools update` refresh only the marketplace the Databricks plugin is listed in, so another unreachable marketplace no longer blocks them. When that refresh fails, both commands warn, install or update the plugin from the local copy of the marketplace, and record the plugin version as unknown. ([#7473](#7473))
 * `databricks aitools install` and `databricks aitools update` now wait up to 20 seconds instead of 5 for a coding agent's CLI to answer the plugin capability check, so a slow first start is less likely to report the agent as unavailable. ([#7472](#7472))
 * `databricks aitools install` no longer fails a plugin-only install when the lookup of the latest skills release on GitHub fails or is rate-limited. The plugin is installed and its version is recorded as unknown. ([#7474](#7474))
 * `databricks aitools` commands now send usage telemetry, and the CLI records when it recommends installing Databricks AI tools. When the configured workspace is slow or unreachable, `aitools install`, `update` and `uninstall` can take up to about 6 seconds longer, and `list`, `version` and runs that stop early up to about 3 seconds. Set `DATABRICKS_CLI_DISABLE_TELEMETRY=1` to opt out. ([#7467](#7467), [#7469](#7469), [#7470](#7470))
 * `databricks aitools install` and `databricks aitools update` now report a coding agent CLI shim (`.cmd` or `.bat`) on Windows that prints its plugin help and then exits with an error as `shim-exited-with-error`, with the command to run to see the error, instead of reporting the CLI as not on PATH. ([#7476](#7476))
 * `apps init` no longer suggests installing skills when every detected coding agent already has the Databricks plugin. ([#7467](#7467))
 * `databricks auth login` now gives up on the optional workspace lookup after about 5 seconds instead of retrying for about 5 minutes, and explains the fallback to the manual workspace ID prompt. ([#7522](#7522))
 * Throttle Claude Code's native plugin install hint separately from the text hint: it prints at most once per 10 minutes per session, so the install dialog still comes up when a subagent, a hook, or a command outside a Claude Code subprocess runs the session's first `databricks` command. ([#7692](#7692))
 * Print Claude Code's native plugin install hint alongside the text hint, so Claude Code offers a one-click install of the Databricks plugin. Claude Code now counts as having the tooling only when it loads it: skills only in `~/.databricks/aitools/skills` don't count, and a project- or local-scope plugin counts only when the CLI runs inside that project. `auth token`, `auth docker token` and CLI subprocesses no longer print install hints. ([#7585](#7585))
 * Interactive prompts and pagers now work in Git for Windows' bash and other MSYS2 shells when they run under ConPTY (the default since Git for Windows 2.47) or directly in a Windows console. ([#7699](#7699))
 * Add the `databricks feedback` command to send feedback about the CLI to Databricks. ([#7724](#7724))
 * Fix shell completion in `databricks fs` commands for local paths typed with a leading `./` or repeated separators, which previously offered no suggestions. ([#7679](#7679))
 * Fix a panic in `databricks labs` commands when a non-string SDK setting such as `DATABRICKS_DEBUG_HEADERS` or `DATABRICKS_RATE_LIMIT` is set in the environment. ([#7673](#7673))
 * Fix a panic in `databricks labs install` for projects whose `labs.yml` has no `install` section. ([#7673](#7673))
 * `NO_COLOR` no longer disables prompts, spinners or the list pager; they run without color. ([#7700](#7700))
 * Add the Beta `databricks pipelines test` command, which runs the tests of a pipeline, and the `testing` property of pipelines in bundles. ([#7429](#7429))
 * Add `databricks sandbox forward`, which serves an app running in a sandbox at a local URL. ([#7395](#7395))
 * Bound the whole telemetry upload at exit, including config resolution and authentication, by its timeout, so a stalled auth or telemetry endpoint no longer keeps a command from exiting. ([#7467](#7467))
 * `databricks version --check` now suggests `databricks aitools install` on stderr when a coding agent is detected without the Databricks plugin or skills. ([#7471](#7471))

### AI Runtime

 * `air get -o json` now reports `PENDING` while the run waits for compute, matching `air list`, and includes the run's `status_message`. ([#7455](#7455))
 * Wrap long failure reasons and log lines in the `air list` info and logs panes, keep the MLflow link (labeled with its retry) when a run's last retry failed before starting, and point `air logs` at earlier retries when the last one has no logs. ([#7456](#7456))
 * `databricks air logs --node` now reports an out-of-range node index when it can determine the run's node count, instead of looking like a successful run with no logs. ([#7516](#7516))
 * Add experiment, duration, accelerator, and dashboard metadata to `air list --output json`. For retried runs, `started_at` now reports the latest attempt, matching `air get`. ([#7568](#7568))
 * `air list` shortens MLflow run names and unnamed-run IDs by keeping their end behind a leading `…`, and its columns no longer overflow on wide (for example CJK) text; `air get` shows an unnamed run's full MLflow run ID. ([#7582](#7582))
 * Shrink the Experiment and User columns of the interactive `air list` table to fit the terminal width, keeping the end of a shortened experiment name. ([#7583](#7583))
 * Show the experiment, accelerators and configuration in the `air list` info pane for runs where it showed `N/A`. ([#7587](#7587))
 * Strip terminal control characters from the MLflow run, experiment and user names shown by `air list` and `air get`, so a run name cannot clear or retitle the terminal of whoever lists it. ([#7601](#7601))
 * `air logs`, `air get`, and `air run --watch` no longer make an extra credential-check request before fetching the run, and `air get` reuses the configured workspace ID instead of looking it up. ([#7613](#7613))
 * `air list` no longer waits on extra current-user requests before listing runs, which makes the default list about 150ms faster. ([#7615](#7615))
 * `air list --all-status` requests larger index pages, so it makes far fewer round trips once the server supports `page_size`. ([#7616](#7616))
 * Fit the interactive `air list` table to narrow terminals: when the Experiment and User columns are at their floors, shorten Started to `MM-DD HH:MM` and size the MLflow column to its labels, then hide Accelerators, User, MLflow and Progress in that order, naming the hidden columns in the hint line. ([#7629](#7629))
 * `air get -o json` now includes `mlflow_run_id` and `mlflow_experiment_id`, so a run can be handed to MLflow-based steps without parsing `mlflow_url`. They identify the MLflow run `mlflow_url` links to, including one from an earlier retry that `mlflow_retry` names. ([#7636](#7636))
 * `air get` and the `air list` info pane now show the environment of runs on the Databricks AI environment (`databricks_ai_v*`) instead of `N/A`. ([#7637](#7637))
 * `air run` now rejects a `code_source.include_paths` path that selects no files instead of uploading a snapshot without it; glob patterns and pathspec magic are left to git. ([#7643](#7643))
 * `air convert-to-dabs` now suggests the `--output-dir` that converts a working-tree workload whose `code_source.root_path` is outside the bundle directory, instead of suggesting `sync.paths`. ([#7644](#7644))
 * `air run` now lists a `code_source.root_path` outside a git repository relative to `root_path`, so running from a subdirectory of `root_path` no longer uploads an empty or partial snapshot. ([#7646](#7646))
 * `air list --all-status` now fills `--limit` past purged or inaccessible indexed runs. ([#7743](#7743))
 * `air run` now warns about missing PyTorch when a pinned snapshot's `include_paths` selects a Python file. ([#7744](#7744))
 * `air cancel JOB_RUN_ID` now rejects run IDs that are not AI Runtime runs instead of cancelling unrelated Jobs runs. In `-o json` output, the `failed[].error` text for a run that does not exist or that you cannot view now starts with `failed to get run <id>:` instead of the cancel API error. ([#7569](#7569))
 * `air get -o json` now reports `mlflow_retry` when the MLflow link comes from an earlier retry because the run's last retry never reached MLflow. ([#7620](#7620))
 * `databricks air run --help` now shows how to install the databricks-ai-runtime coding agent skill. ([#7652](#7652))
 * `air run --watch -o json` now reports each lifecycle `STATUS` transition once and never reports a non-terminal state after the run has ended, including when logs are served from MLflow artifacts. ([#7621](#7621))
 * `air convert-to-dabs` now explains the `--output-dir` workaround when `code_source.root_path` resolves to the bundle root, and notes when the generated job carries the default `max_retries`. ([#7579](#7579))
 * `air run` now refuses to upload a `code_source` snapshot that selects no files (for example when `root_path` is git-ignored) and explains the cause, and `--dry-run` runs the snapshot file selection and reports the file count. ([#7570](#7570))
 * Repeat the Jobs run link after live log streaming ends. ([#7571](#7571))
 * `air get -o json` includes run details including flat `accelerator_type` and `num_accelerators`. Use `--include-config` to include stored config, which may contain plaintext `env_variables` and parameters; downloads over 1 MiB are omitted, and config-dependent `max_retries` is otherwise null. ([#7624](#7624))
 * `air get` and the `air list` info pane no longer show `Max Retries 0` when the Jobs API leaves the task's retry limit out. For a run submitted with `air run`, the limit now comes from the run's uploaded config, shown as `3 (CLI default)` when the config doesn't set `max_retries`; it shows `N/A` when the limit can't be known (job runs, multi-container runs, legacy runs with no explicit value, or an unreadable config). ([#7623](#7623))
 * Reorganize `databricks air` help: subcommands are grouped by task, `air run` has examples, and YAML fields are listed under headings, with pool fields marked optional and `command`, `compute.num_accelerators`, and `compute.accelerator_type` correctly marked required. ([#7512](#7512))
 * `air run -h config` now lists the environment variables AI Runtime sets on every node (such as `MLFLOW_RUN_ID` and `CODE_SOURCE_PATH`), and `air logs --help` notes that `--download-to` cannot be combined with `--tail` or `--minutes`. ([#7655](#7655))
 * Support full workspace accelerator types in `air list` filters while preserving family matching, and reject invalid filter values. ([#7515](#7515))
 * `databricks air list --all-status` now warns when the AI Runtime run index is unavailable and it falls back to scanning Jobs runs. That fallback scan is capped at 250 runs, and a stuck index request fails after 15 seconds instead of retrying for minutes. `--all-status --filter user=<your email>` now uses the run index instead of scanning the workspace's full run history. ([#7619](#7619))
 * Return structured JSON errors for invalid `air list --filter` values when `-o json` is used. ([#7612](#7612))
 * `air list --all-status` no longer fails when a listed run has been purged. ([#7523](#7523))
 * **Behavior change:** `databricks air logs` now prints the logs available now and exits, also for an active run, matching `kubectl logs`, `docker logs` and `databricks apps logs`. Pass `--follow` (`-f`) to stream new lines until the run completes; `--tail N --follow` prints the last N lines first. `databricks air run --watch` still submits and streams. ([#7658](#7658))
 * `databricks air logs -o json` and `databricks air run --watch -o json` now emit a `WAITING` event, for example `{"type":"WAITING","message":"Waiting for accelerator compute capacity..."}`, when the reported waiting status changes. ([#7695](#7695))
 * `databricks air logs` on a run that ended in the last two minutes now waits for the log index to settle before printing, instead of sometimes dropping lines that were indexed late. ([#7663](#7663))
 * `air logs` and `air run --watch` now print the waiting status (for example `Waiting for accelerator compute capacity...`) as a line on stderr when stderr is not a terminal, instead of printing nothing until the run produces logs. ([#7657](#7657))
 * Route AIR log links to the MLflow Logs page instead of the hidden artifact path. ([#7491](#7491))
 * Invalid `compute.accelerator_type` errors and `air run -h config.compute` no longer list the CLI's built-in accelerator types, which could differ from the workspace's. ([#7520](#7520))
 * `databricks air --help` now notes that GPU pools are not required to run workloads. ([#7581](#7581))
 * `air run` now prints the job run URL with the `?o=<workspace-id>` suffix, matching `air get` and `air list`; `dashboard_url` in `air run -o json` and the `--watch` events gains it too. When `air list` cannot resolve the workspace ID, its links now omit `?o=` instead of ending in `?o=0`. ([#7573](#7573))
 * `databricks air run` now reports an unknown workload YAML key by its field path, suggests the closest valid field, and points to `-h config` instead of naming an internal Go type. ([#7574](#7574))
 * `air run` (including `--dry-run`) now warns before submitting when the `code_source` imports `torch` but PyTorch is not declared: the environment is the Standard environment (version 5 or later) with no `torch` dependency, so the run may fail after it waits for a GPU. ([#7656](#7656))

### Bundles

 * Add `isolation_mode` to the `catalogs` resource, so a catalog can be deployed as `OPEN` or `ISOLATED`. ([#7463](#7463))
 * `bundle validate` no longer warns when resource permissions and top-level or target permissions name the same principal. ([#7291](#7291))
 * Retry bundle file uploads, reads and deletes when the server does not respond within the HTTP timeout ("request timed out after ... of inactivity"). ([#7521](#7521))
 * Show how to recover when `bundle deploy` fails because an app's service principal does not exist or was deleted. ([#7533](#7533))
 * Retry transient server errors when creating Lakebase (`postgres_*`) resources in the direct deployment engine. ([#7557](#7557))
 * Fix `bundle plan` reporting the `spark_conf` and `custom_tags` the backend derives from `is_single_node: true` as drift on clusters. ([#7577](#7577))
 * Stop planning a spurious update for Lakeflow Connect pipelines whose `ingestion_definition.data_staging_options` is filled in by the backend. ([#7603](#7603))
 * Retry the root path check in `bundle destroy` on transient errors, so a dropped connection no longer fails the destroy. ([#7597](#7597))
 * Use the Lakebase branch when its create request times out but the branch was created, instead of failing the deploy, in the direct deployment engine. ([#7602](#7602))
 * Retry transient server errors when deleting resources in the direct deployment engine. ([#7708](#7708))
 * Use the Lakebase project when its create request times out but the project was created, instead of failing the deploy with "already exists", in the direct deployment engine. ([#7747](#7747))
 * Use the feature, model serving endpoint or dashboard that a create request created despite timing out, instead of failing the deploy, in the direct deployment engine. ([#7757](#7757))
 * Use the Lakebase role when its create request fails with a transient error but the role was created, instead of failing the deploy, in the direct deployment engine. ([#7767](#7767))
 * Use the MCP service, model service or model provider service that a create request created despite failing with a timeout, a 499 or a reset stream, instead of failing the deploy, in the direct deployment engine. Create recovery for features, serving endpoints and dashboards now also covers 499 and reset streams. ([#7782](#7782))
 * Retry app updates and deletes in the direct deployment engine when they fail with 400 BAD_REQUEST because the app compute is `UPDATING`, after waiting for the compute to settle. ([#7606](#7606))
 * Enable drift detection for `source_code_path` and `git_source` on apps. ([#6399](#6399))
 * `bundle destroy` and `bundle deploy` no longer fail with "internal error, missing in state" when the state holds an empty-ID entry left by an interrupted recreate in an older CLI. ([#7676](#7676))
 * Fix a feature whose `full_name` contains uppercase letters being recreated on every deploy. ([#7398](#7398))
 * Fix `bundle deployment bind` (and `bundle generate --bind`) failing with `no such node "resources.internal_immutable_snapshots.immutable"` when `workspace.sync_mode` is `immutable`, as reported in [#7306](#7306). ([#7329](#7329))
 * Retry creating the deployment lock (without `--force-lock`) when the request fails with a transient server error, times out ("request timed out after ... of inactivity") or loses its connection ("unexpected EOF"). ([#7594](#7594))
 * Fix a materialization set member whose `feature_name` contains uppercase letters failing to deploy, or recreating the set on every deploy. ([#7398](#7398))
 * Delete the old resource when its name follows a renamed schema. ([#7718](#7718))
 * Fix `pipelines dry-run` starting a real run when given a job KEY, and a crash in its shell completion. ([#7672](#7672))
 * Rename schemas in place; schemas and volumes follow a renamed catalog or schema. ([#7343](#7343))
 * Fix a panic when validating or deploying jobs with local libraries and serverless job clusters. ([#7725](#7725))
 * Fix `tgz` artifacts with `git` set producing an empty tarball or failing when the bundle is in a subdirectory of the git repository. ([#7674](#7674))
 * Apply `presets.trigger_pause_status` and the development mode pause default to `triggers[]` entries on jobs. ([#7450](#7450))

### Dependency Updates

 * Bump dependencies with known vulnerabilities. ([#7750](#7750))
 * Update the Go SDK to [v0.198.0](https://github.com/databricks/databricks-sdk-go/releases/tag/v0.198.0). ([#7530](#7530))
 * Update the Go SDK to [v0.199.0](https://github.com/databricks/databricks-sdk-go/releases/tag/v0.199.0). ([#7584](#7584))
 * Update the Go SDK to [v0.200.0](https://github.com/databricks/databricks-sdk-go/releases/tag/v0.200.0). ([#7653](#7653))
 * Update the Go SDK to [v0.201.0](https://github.com/databricks/databricks-sdk-go/releases/tag/v0.201.0). ([#7769](#7769))
idelafuente-oc pushed a commit to idelafuente-oc/cli that referenced this pull request Nov 20, 2026
databricks#7702)

Stacked on databricks#7701, the PR that stores the auto-install state and adds the
opt-out commands and the cli-compat gate.

After a command succeeds, the CLI installs (or updates) Databricks AI
tools for the coding agents on the machine, once per new CLI version.
Ships off: nothing sets the gate yet.

## Summary

```text
root PersistentPostRunE (cmd/cmd.go; cobra skips it when the command failed)
  cmdio.Wait
  aitools.AutoInstall(cmd)                         # cmd/aitools/autoinstall_run.go; recovers panics, returns nothing
    Decide(command, version)                       # libs/aitools/autoinstall/decide.go (pure)
      skipped command | Databricks Runtime
      | cache disabled | development build         -> return (no state read, no log)
    Load state (under auto-install.json.lock)
    Decide again
      settled | retries exhausted
      | older than a CLI that already ran here     -> debug line, return
    TryLock auto-install.lock (busy -> skip); reload state
    Decide with the gate off
      CI                 -> settle, report SKIPPED_CI       # agents.InCI: CI=<anything but false>, or a provider the SDK detects
      opt-out            -> settle, report SKIPPED_OPTOUT   # env var, stored opt-out, or "no" in this process
      gate_off           -> look the gate up (cli-compat auto_install, 3s), Decide again
        still off        -> settle silently
        lookup failed    -> record attempt N, report nothing  # only the embedded manifest was reachable
      holdout (10%)      -> settle, report SKIPPED_HOLDOUT
      run
        record attempt N
        planTools
          global skills on disk, no install state,
            not left by our own unfinished install  -> leave them alone, settle, report KEPT
          no global install state:  mark "installing", buildPlan + executePlan  # as `aitools install --scope=global`,
                                                               # no prompts, agents whose config dir exists
          global install state:     runUpdate(--scope=global)  # as `aitools update`, edited skills kept,
                                                               # no raw-skills-to-plugin migration
          Windows: drop plugin installs; leave an install alone if its update touches plugins -> SKIPPED_PLATFORM
        (10s budget, installer output discarded, warnings demoted to debug)
        installed / changed -> settle, report INSTALLED, stderr: "Installed Databricks AI tools for Claude Code, Cursor. Disable: databricks aitools auto-install disable"
        update, no change -> settle, report UP_TO_DATE
        no agents -> settle, report SKIPPED_NO_AGENTS
        refused downgrade -> keep the installed tools, settle, report KEPT
        error     -> debug line, report FAILED (RETRIES_EXHAUSTED on attempt 10)
```

- "Settle" writes `last_version = current, attempts = 0` and clears
`installing`: each machine reports at most one outcome per version, plus
one per retry. A new version resets the retry budget.
- Locks are OS file locks (`flock` / `LockFileEx`) on files that are
never removed. They are only tried, never waited on. The state lock is
retried for up to 1 s while another process holds it; any other lock
error returns at once. A busy run lock skips the attempt.
- Agent CLIs run in their own process group
(`process.BackgroundInGroup`), so a timeout stops their descendants too.
That takes them out of the terminal's foreground group, so while one
runs, the first SIGINT/SIGTERM is caught, stops the group, and is raised
again in the CLI: Ctrl-C ends `aitools install`/`update` as before,
without orphans. Windows has no such stop, so there auto-install runs no
agent CLI: a fresh install drops its plugin installs (skills are still
installed), and an existing install whose update would touch plugins is
left alone. A Windows machine with only plugin-capable agents settles as
`SKIPPED_NO_AGENTS`.
- Answering "no" at the `apps init` skills prompt opts out, and says so
with the `auto-install enable` command. It is stored, honored in the
process even if the write fails, and passed as
`DATABRICKS_AITOOLS_AUTO_INSTALL=false` to the `apps deploy` / `apps
dev-remote` children that `apps init` starts, next to their
`DATABRICKS_CLI_SELF_EXEC=1`.
- Skipped commands are the version notice's (`version`, `help`,
completion), the credential helpers (`auth token`, `auth docker token`)
and the `aitools` trees. Non-interactive and `-o json` runs are not
skipped, unlike for the notice: coding agents run the CLI that way, and
auto-install writes nothing to stdout. Databricks Runtime is skipped
(ephemeral home, platform-managed CLI).
- The gate is unknown, not off, when only the embedded manifest is
reachable (`clicompat.ResolveAutoInstall` fails): the version is not
settled, and the lookup uses up one of the version's 10 attempts, so an
offline machine stops paying for it.
- The holdout uses a random id stored in the state (the CLI has no
machine id); only the arm (`HOLDOUT`/`TREATMENT`) is reported.
- Development and snapshot builds never auto-install. Acceptance tests
set the undocumented `DATABRICKS_AITOOLS_AUTO_INSTALL_CLI_VERSION` to
simulate releases and upgrades.
- Telemetry: `aitools_install_event.trigger = AUTO_FIRST_RUN` (unset for
the command's own installs, so existing goldens do not change) and a new
`aitools_auto_install_event {outcome, holdout_arm, interactive,
error_category}`, documented in `libs/telemetry/protos/README.md`.
Outcomes: `INSTALLED`, `UP_TO_DATE`, `KEPT`, `SKIPPED_CI`,
`SKIPPED_OPTOUT`, `SKIPPED_HOLDOUT`, `SKIPPED_NO_AGENTS`,
`SKIPPED_PLATFORM`, `FAILED`, `RETRIES_EXHAUSTED`; the lumberjack proto
needs the same values.
- Includes a no-behavior-change refactor: `aitools update`'s RunE body
moves to `runUpdate`; `agents.InCI`, `agents.IsCredentialHelperCommand`
and `versioncheck.IsExemptCommand` are exported for reuse; the
acceptance helper `print_telemetry` moves up a directory.
- No changelog fragment: nothing is user-visible while the gate is off.
The PR that turns it on should add one.

### Known limitations

Both must be fixed before the gate is turned on:

- A global `aitools uninstall` that runs while an automatic install is
in flight can see that attempt recreate the tools. Running uninstall
again removes them.
- A partial install (one agent fails) settles as `INSTALLED`, and later
updates never add the missing agent. The same applies to the agents the
Windows rule above leaves out. One fix is to record the targeted agents
in `auto-install.json`. (An install cut short by the timeout is
different: its `installing` marker makes the next run finish it.)

## Review order

1. `libs/aitools/autoinstall/decide.go`: the decision, pure.
2. `cmd/aitools/autoinstall_run.go`: the hook, `planTools`, reporting.
3. `libs/aitools/autoinstall/run.go`, `lock_unix.go`, `lock_windows.go`,
`state.go`: locks, attempts, `Decline` / `ChildEnv`.
4. `cmd/cmd.go`, `cmd/apps/init.go`, `libs/aitools/agents/recommend.go`:
the wiring.
5. Supporting: `cmd/aitools/update.go` (refactor),
`libs/aitools/installer/update.go` (`KeepModified`,
`HasUntrackedSkills`), `libs/aitools/installer/plugin.go` (process
group), `libs/telemetry/protos/`.

## Evidence

New acceptance tests in `acceptance/cmd/aitools/auto-install/` run
`databricks jobs list` against the fake server and a fake skills source,
with a temporary HOME and agent dirs:

- `first-run`:
  ```text
  >>> [CLI] jobs list
Installed Databricks AI tools for Claude Code, Cursor. Disable:
databricks aitools auto-install disable

{"aitools_install_event":{"agents":["CLAUDE_CODE","CURSOR"],...,"trigger":"AUTO_FIRST_RUN"}}

{"aitools_auto_install_event":{"outcome":"INSTALLED","holdout_arm":"TREATMENT","interactive":false}}
  === second run of the same version: nothing
=== uninstall turns it off: the next version installs nothing ->
SKIPPED_OPTOUT
  ```
- `upgrade`: 1.30.0 installs skills release 0.3.0; 1.31.0 with release
0.4.0 prints `Updated Databricks AI tools for Cursor.`, updates one
skill and keeps a skill the user edited; 1.32.0 while the latest release
is 0.2.0 refuses the downgrade (files unchanged, nothing printed,
settled as `KEPT`, not retried); a 1.31.0 CLI run afterwards does
nothing.
- `skipped`: `CI=true` (reported once per version),
`DATABRICKS_AITOOLS_AUTO_INSTALL=false`, `auto-install disable`,
`version`/`aitools`/`completion`/`__complete`/`help`,
`DATABRICKS_CACHE_ENABLED=false`, gate off (nothing reported, version
settled), holdout machine, no agent config dir.
- `retries`: nine `FAILED` attempts, `RETRIES_EXHAUSTED` on the tenth,
nothing on the eleventh, a fresh install on the next version.
- Unit tests: `TestDecide` (table-driven over every input);
`TestSkipsAutoInstall`;
`TestPlanToolsRunsNoAgentCLIWhereTimeoutsCannotStopThem`,
`TestPlanToolsReportsWhyNothingIsInstalled` and
`TestPlanToolsKeepsSkillsWithoutInstallState` (also: an unfinished
install of ours is finished); `TestChangedAgents`;
`TestTryLockExcludesOtherRuns`, `TestLoadWaitsForStateLock`,
`TestLoadFailsWhenStateLockStaysHeld`,
`TestLockReturnsOtherErrorsAtOnce`, `TestRecordKeepsConcurrentOptOut`,
`TestSetOptedOutWithoutLocks`, `TestRecordClearsInstallingWhenSettled`;
`TestChildEnvCarriesTheRefusal`, `TestSelfExecEnvCarriesBothMarkers`
(the `apps init` children's env);
`TestResolveAutoInstallFailsOnTheEmbeddedFallback`;
`TestBackgroundInGroupForwardsInterrupt` (a helper process interrupted
mid-run dies by SIGINT and its grandchild is reaped);
`TestRunAgentCmdTimeoutStopsDescendants`;
`TestUpdateKeepModifiedKeepsEditedSkill`.
- Unit tests of `cmd/...` and `libs/...`, the aitools and apps
acceptance suites, lint and whitespace checks pass on Linux;
`GOOS=windows`/`darwin` build and vet pass. The gate-lookup failure has
no acceptance test: the manifest URL has no override, so it is covered
by the clicompat and state unit tests.

## Merge Danger

**Door:** two-way while the gate is off

With the gate off it reads one small file and settles the version on the
first run of each release, sends `SKIPPED_CI`/`SKIPPED_OPTOUT` events
when those apply, and does nothing else. Turning the gate on (a
`cli-compat.json` edit on main) is the one-way step: installs it causes
are not rolled back by turning it off again.

**Blast Radius:** every command (post-run)

- Runs after every successful command, except the skipped ones and on
Databricks Runtime. Off the first run of a version it is one state-file
read under a lock (at most 1 s more if another CLI holds the lock); on
the first run, with the gate off, a cli-compat manifest lookup (usually
the 1 h local cache, at most 3 s). A machine that cannot fetch the
manifest repeats the lookup on up to 10 runs of the version.
- Also changes the explicit `aitools install`/`update` today: agent CLIs
run in their own process group, with Ctrl-C forwarded to it.
- Two CLI versions on one machine: only the newest auto-installs; an
older one does nothing.
- With the gate on: up to about 20 s more after the first command of a
version (the 10 s install budget plus up to 10 s for a timed-out agent
CLI to release its output pipes), plus retries after failures; skill
files in global agent dirs; and plugin installs through agent CLIs on
PATH (not on Windows).
- Writes `~/.databricks/aitools/auto-install.json` and two lock files
next to it.
- Windows and macOS behavior is built and vetted, not run.

This pull request and its description were written by Isaac.

---------

Co-authored-by: Isaac <no-reply@databricks.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

aitools AI tools (databricks aitools) related changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants