Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .agents/skills/bump-cli-compat/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@ Write the updated `internal/build/cli-compat.json` and `internal/build/clicompat

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.


Write the updated `internal/build/cli-compat.json` and `internal/build/clicompat.go`.

Expand Down
1 change: 1 addition & 0 deletions .nextchanges/cli/aitools-auto-install-opt-out.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
* 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](https://github.com/databricks/cli/pull/7701))
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Cloud = false
77 changes: 77 additions & 0 deletions acceptance/cmd/aitools/auto-install/enable-disable/output.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@

=== nothing stored yet

>>> auto_install_state
(no auto-install state)

=== disable stores the opt-out

>>> [CLI] aitools auto-install disable
Automatic installation of Databricks AI tools is disabled.

>>> auto_install_state
{
"opted_out": true
}

=== enable clears it

>>> [CLI] aitools auto-install enable
Automatic installation of Databricks AI tools is enabled.

>>> auto_install_state
{}

=== enable says when the environment still turns it off

>>> 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.

=== disable replaces a state file it cannot read

>>> [CLI] aitools auto-install disable
Automatic installation of Databricks AI tools is disabled.

>>> auto_install_state
{
"opted_out": true
}

=== a global uninstall that removes nothing leaves it on

>>> [CLI] aitools uninstall --scope=global
Error: no skills or plugins installed

Exit code: 1

>>> auto_install_state
{}

=== a global uninstall of a mistyped skill leaves it on

>>> [CLI] aitools uninstall --scope=global --skills databricks-tset
Error: skill "databricks-tset" is not installed

Exit code: 1

>>> auto_install_state
{}

=== a global uninstall turns it off

>>> [CLI] aitools uninstall --scope=global
Uninstalled 1 skill.

>>> auto_install_state
{
"opted_out": true
}

=== a project uninstall leaves it on

>>> [CLI] aitools uninstall --scope=project
Uninstalled 1 skill.

>>> auto_install_state
{}
43 changes: 43 additions & 0 deletions acceptance/cmd/aitools/auto-install/enable-disable/script
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
sethome home
mkdir -p "${USERPROFILE:-$HOME}/.cursor"

title "nothing stored yet"
trace auto_install_state

title "disable stores the opt-out"
trace $CLI aitools auto-install disable
trace auto_install_state

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

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.

trace auto_install_state

title "enable says when the environment still turns it off"
trace DATABRICKS_AITOOLS_AUTO_INSTALL=false $CLI aitools auto-install enable

title "disable replaces a state file it cannot read"
echo "not json" > "${USERPROFILE:-$HOME}/.databricks/aitools/auto-install.json"
trace $CLI aitools auto-install disable
trace auto_install_state
$CLI aitools auto-install enable &> LOG.enable-reset-1

title "a global uninstall that removes nothing leaves it on"
errcode trace $CLI aitools uninstall --scope=global
trace auto_install_state

title "a global uninstall of a mistyped skill leaves it on"
$CLI aitools install --skills-only --scope=global --agents=cursor &> LOG.install-global
errcode trace $CLI aitools uninstall --scope=global --skills databricks-tset
trace auto_install_state

title "a global uninstall turns it off"
trace $CLI aitools uninstall --scope=global
trace auto_install_state
$CLI aitools auto-install enable &> LOG.enable-reset-2

title "a project uninstall leaves it on"
mkdir -p "${USERPROFILE:-$HOME}/project"
cd "${USERPROFILE:-$HOME}/project"
$CLI aitools install --skills-only --scope=project --agents=claude-code &> LOG.install-project
trace $CLI aitools uninstall --scope=project
trace auto_install_state
5 changes: 5 additions & 0 deletions acceptance/cmd/aitools/auto-install/script.prepare
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# auto_install_state prints the persisted auto-install state.
auto_install_state() {
local path="${USERPROFILE:-$HOME}/.databricks/aitools/auto-install.json"
if [ -f "$path" ]; then cat "$path"; else echo "(no auto-install state)"; fi
}
37 changes: 37 additions & 0 deletions acceptance/cmd/aitools/auto-install/test.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
# Automatic installation of Databricks AI tools on the first run of a new CLI
# version. The mock server replaces raw.githubusercontent.com (skills manifest
# and files).
Env.DATABRICKS_SKILLS_BASE_URL = "$DATABRICKS_HOST"
Env.DATABRICKS_SKILLS_REF = "test-ref"
# Pin it so an opt-out exported in the developer's shell does not change the output.
Env.DATABRICKS_AITOOLS_AUTO_INSTALL = "true"

Ignore = [
"home",
]

[[Server]]
Pattern = "GET /test-ref/manifest.json"
Response.Body = '''
{
"version": "2",
"updated_at": "2026-01-01T00:00:00Z",
"skills": {
"databricks-test": {
"version": "1.0.0",
"description": "Test skill",
"files": ["SKILL.md"],
"repo_dir": "skills"
}
}
}
'''

[[Server]]
Pattern = "GET /test-ref/skills/databricks-test/SKILL.md"
Response.Body = '''---
name: databricks-test
---

# Test skill
'''
1 change: 1 addition & 0 deletions cmd/aitools/aitools.go
Original file line number Diff line number Diff line change
Expand Up @@ -31,4 +31,5 @@ https://github.com/databricks/databricks-agent-skills`
cmd.AddCommand(NewUninstallCmd())
cmd.AddCommand(NewListCmd())
cmd.AddCommand(NewVersionCmd())
cmd.AddCommand(newAutoInstallCmd())
}
68 changes: 68 additions & 0 deletions cmd/aitools/autoinstall.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
package aitools

import (
"context"
"fmt"

"github.com/databricks/cli/cmd/root"
"github.com/databricks/cli/libs/aitools/autoinstall"
"github.com/databricks/cli/libs/cmdio"
"github.com/spf13/cobra"
)

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.

Short: "Turn the automatic installation of Databricks AI tools on or off",
Long: `Turn the automatic installation of Databricks AI tools on or off.

On the first run of a new CLI version, the CLI can install the Databricks AI
tools (skills and plugins) for the coding agents already on this machine, as
'databricks aitools install --scope=global' does, or update an existing
installation, as 'databricks aitools update' does. It never runs in CI and only
touches the global scope.

It stays off after 'databricks aitools auto-install disable' or a global-scope
'databricks aitools uninstall', until 'databricks aitools auto-install enable'.
Setting ` + autoinstall.EnvVar + ` to anything but a true value (true, 1, yes,
on) turns it off in that environment.`,
RunE: root.ReportUnknownSubcommand,
}
cmd.AddCommand(newAutoInstallToggleCmd(true))
cmd.AddCommand(newAutoInstallToggleCmd(false))
return cmd
}

// newAutoInstallToggleCmd returns `auto-install enable` or `auto-install disable`.
func newAutoInstallToggleCmd(enable bool) *cobra.Command {
use, short := "disable", "Turn off the automatic installation of Databricks AI tools"
if enable {
use, short = "enable", "Turn the automatic installation of Databricks AI tools back on"
}
return &cobra.Command{
Use: use,
Short: short,
Args: cobra.NoArgs,
RunE: func(cmd *cobra.Command, args []string) error {
ctx := cmd.Context()
if err := autoinstall.SetOptedOut(ctx, !enable); err != nil {
return fmt.Errorf("failed to save the auto-install setting: %w", err)
}
printAutoInstallSetting(ctx, enable)
return nil
},
}
}

// printAutoInstallSetting confirms the stored setting. An enable that the
// environment still overrides says so, rather than looking like it worked.
func printAutoInstallSetting(ctx context.Context, enabled bool) {
if !enabled {
cmdio.LogString(ctx, "Automatic installation of Databricks AI tools is disabled.")
return
}
cmdio.LogString(ctx, "Automatic installation of Databricks AI tools is enabled.")
if autoinstall.EnvOptedOut(ctx) {
cmdio.LogString(ctx, cmdio.Yellow(ctx, autoinstall.EnvVar+" still disables it in this environment; unset it to let it run."))
}
}
15 changes: 15 additions & 0 deletions cmd/aitools/uninstall.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,10 @@ import (
"slices"
"strings"

"github.com/databricks/cli/libs/aitools/autoinstall"
"github.com/databricks/cli/libs/aitools/installer"
"github.com/databricks/cli/libs/cmdio"
"github.com/databricks/cli/libs/log"
"github.com/databricks/cli/libs/telemetry/protos"
"github.com/spf13/cobra"
)
Expand All @@ -27,6 +29,10 @@ func NewUninstallCmd() *cobra.Command {

By default, removes all skills. Use --skills to remove specific skills only.

A global-scope uninstall that removes anything also turns off the automatic
installation of Databricks AI tools on CLI upgrades; 'databricks aitools auto-install enable'
turns it back on.

The command exits with code 1 when every removal it attempts fails.`,
Args: cobra.NoArgs,
RunE: func(cmd *cobra.Command, args []string) error {
Expand Down Expand Up @@ -107,6 +113,15 @@ The command exits with code 1 when every removal it attempts fails.`,
if err != nil {
return err
}
// 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. A run
// that removed nothing (a mistyped skill, nothing installed) does not.
if scope == installer.ScopeGlobal && (result.PluginsRemoved > 0 || result.SkillsChanged > 0) {
if err := autoinstall.SetOptedOut(ctx, true); err != nil {
log.Warnf(ctx, "Could not turn off the automatic installation of Databricks AI tools: %v", err)
}
}
Comment on lines +116 to +124

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.

// A plugin or skill that could not be removed is only a warning, unless
// no copy of any skill and no plugin was removed at all. A plugin record
// for an agent this CLI does not know is not an attempt: no command can
Expand Down
6 changes: 4 additions & 2 deletions internal/build/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ Each key is a CLI version in semver format. Each entry defines a **range floor**

`skills` is an exact pin for its CLI range or `"latest"` to install the skills repository's latest published GitHub release. When the latest-release lookup fails or the selected skills manifest is missing, ranges tracking latest use `AgentSkillsFallbackVersion` from `internal/build/clicompat.go`. Pinned ranges use their embedded manifest's skills version as the fallback. Changing either fallback takes effect in the next CLI build. Released binaries keep the fallback they shipped with.

An entry can also set `"auto_install": true` to turn on the automatic installation of Databricks AI tools on the first run of a new CLI version in its range (`aitools auto-install`). It is off when absent. A change reaches a machine on its first run of a CLI version after the change; machines that resolve to a cached or embedded manifest keep the value they have.

This skills fallback only applies to raw-file delivery. Version checks omit update availability when latest is unknown, and plugin operations don't substitute the fallback version.

Raw-skills updates and reinstalls reject automatic downgrades, including with `--force`: the fallback must be at least as new as the installed release. Existing installs without a comparable release require a successful latest-release fetch. Explicit `DATABRICKS_SKILLS_REF` overrides and compatibility pins can still select an older release.
Expand Down Expand Up @@ -62,7 +64,7 @@ When updating AppKit or recording a tested skills fallback:
1. **Run evals** on the new AppKit version. If there is no regression, proceed.
2. **Open a PR** to update `cli-compat.json`. The change depends on the type of release:
- **No breaking changes**: update the highest entry's `appkit` in-place, keeping `"skills": "latest"`. To record a tested skills fallback, update `AgentSkillsFallbackVersion` in `internal/build/clicompat.go`. Do NOT add a new versioned key.
- **Breaking changes** (the new AppKit templates require specific `apps init` features, or the new skills version requires CLI commands that older CLIs lack): add a new entry keyed to the **minimum CLI version** that supports the new features. Set `"skills": "latest"` on the new entry and update the compiled skills fallback to a tested release. If skills compatibility changed, replace `"latest"` in the affected older ranges with the last compatible release. Preserve unrelated AppKit and skills compatibility boundaries.
- **Breaking changes** (the new AppKit templates require specific `apps init` features, or the new skills version requires CLI commands that older CLIs lack): add a new entry keyed to the **minimum CLI version** that supports the new features. Set `"skills": "latest"` on the new entry and update the compiled skills fallback to a tested release. If skills compatibility changed, replace `"latest"` in the affected older ranges with the last compatible release. Preserve unrelated AppKit and skills compatibility boundaries. If the previous highest entry sets `"auto_install": true`, copy it to the new entry: a new entry without it turns auto-install off for every newer CLI.

This process is manual for now but can be automated as part of the release workflow in the future. Use the `/bump-cli-compat` Claude Code skill to automate the update and PR creation.

Expand All @@ -82,4 +84,4 @@ Entries MUST NOT be removed from the manifest. Older CLI binaries use the lowest

## Trust model

The live manifest is fetched over HTTPS from GitHub (`raw.githubusercontent.com`). The trust boundary is: TLS certificate validation + GitHub's access controls + write access to the `main` branch of `databricks/cli`. A compromised manifest can only steer clients to existing published tags (AppKit or skills); it cannot inject arbitrary code. The CLI binary always ships an embedded fallback manifest that limits exposure to cache-TTL windows (1 hour). The local cache (`~/.cache/databricks/compat-manifest.json`) is trust-on-disk: an attacker with user-level write access to the cache directory could swap in a malicious manifest pointing to different tags.
The live manifest is fetched over HTTPS from GitHub (`raw.githubusercontent.com`). The trust boundary is: TLS certificate validation + GitHub's access controls + write access to the `main` branch of `databricks/cli`. A compromised manifest can steer clients to existing published tags (AppKit or skills), and through `auto_install` make them install those published skills and plugins without a command from the user; it cannot inject arbitrary code. The CLI binary always ships an embedded fallback manifest that limits exposure to cache-TTL windows (1 hour). The local cache (`~/.cache/databricks/compat-manifest.json`) is trust-on-disk: an attacker with user-level write access to the cache directory could swap in a malicious manifest pointing to different tags.
Loading
Loading