Skip to content

Build commands only when an invocation needs them - #7487

Merged
pietern merged 1 commit into
mainfrom
lazy-cmd
Nov 16, 2026
Merged

pietern merged 1 commit into
mainfrom
lazy-cmd

Conversation

@pietern

@pietern pietern commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Changes

Every invocation builds the whole command tree (~1,750 commands and ~3,300 flags) before parsing args. That takes about 4ms of every run, including databricks version.

Top-level commands are now declared as a root.CommandSpec. The spec holds the fields the root shows in help, completion, and suggestions, plus a Build function. A root.Tree adds a placeholder for each spec. Tree.Execute resolves the args and builds only the command they resolve to before running cobra. help and shell completion still build the full tree.

This is enforced by the API:

  • root.Tree owns the root command. The functions that create and run a bare root command are now private, so commands can only be added as specs and the CLI can only run through Tree.Execute.
  • root.NewCommand panics if Build changes a field the spec declares, so a placeholder always matches its command.

databricks version drops from ~11ms to ~6ms (1,000 runs, Linux).

Tests

  • New unit tests for the tree: which commands get built for given args (aliases, flags, help, completion), that the spec fields match the built command (checked by reflection), and that root help is identical before and after building.
  • The existing whole-tree tests (unique names, no underscores, fuzz) now build the full tree explicitly.
  • Full acceptance suite passes. I also compared the output of 965 invocations against an eager build, and the only difference was the version hash.

This pull request and its description were written by Isaac.

@pietern
pietern requested a review from a team as a code owner November 11, 2026 16:37
@pietern
pietern added this pull request to stack #7488 November 11, 2026 16:37
@github-actions github-actions Bot added DABs DABs related issues AIR Databricks AI Runtime CLI labels Nov 11, 2026
@eng-dev-ecosystem-bot

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

Copy link
Copy Markdown
Collaborator

✅ Integration test report

Commit: 4bf8228

Run: 43945355139

Env 💚​RECOVERED ✅​pass 🙈​skip Time
💚​ aws linux-2core-8gb 1 270 15 10:02
💚​ aws-windows-latest-4core-16gb 1 272 13 11:38
💚​ azure linux-2core-8gb 1 269 15 11:47
💚​ azure-windows-latest-4core-16gb 1 271 13 7:35
💚​ gcp linux-2core-8gb 1 270 15 11:41
💚​ gcp-windows-latest-4core-16gb 1 272 13 8:43
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 17 slowest tests (at least 2 minutes):
duration env testname
5:17 gcp linux-2core-8gb TestFilerWorkspaceFilesExtensionsDelete
4:39 azure-windows-latest-4core-16gb TestSyncIncrementalFileSync
3:58 azure linux-2core-8gb TestFilerWorkspaceNotebook/sqlJupyterNotebook.ipynb
3:50 azure linux-2core-8gb TestFilerRecursiveDelete/workspace_files
3:47 azure-windows-latest-4core-16gb TestAccept
3:46 gcp-windows-latest-4core-16gb TestAccept
3:32 aws-windows-latest-4core-16gb TestImportDirDoesNotOverwrite
3:22 aws-windows-latest-4core-16gb TestAccept
2:44 aws linux-2core-8gb TestFilerRecursiveDelete/workspace_files_extensions
2:33 gcp linux-2core-8gb TestFilerReadWrite/workspace_files_extensions
2:32 aws-windows-latest-4core-16gb TestImportDirWithOverwriteFlag
2:32 gcp-windows-latest-4core-16gb TestFilerRecursiveDelete/workspace_files_extensions
2:21 gcp-windows-latest-4core-16gb TestFilerWorkspaceFilesExtensionsReadDir
2:14 aws linux-2core-8gb TestFilerWorkspaceFilesExtensionsStat
2:11 azure linux-2core-8gb TestFilerWorkspaceFilesExtensionsReadDir
2:10 gcp-windows-latest-4core-16gb TestSyncFullFileSync
2:03 gcp-windows-latest-4core-16gb TestFilerWorkspaceFilesExtensionsDelete

@pietern
pietern force-pushed the lazy-cmd branch 8 times, most recently from 631f0c9 to 134e5bc Compare November 16, 2026 08:00
@pietern pietern added auth aitools AI tools (databricks aitools) related changes labels Nov 16, 2026

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

Can you add a .nextchanges/cli/ fragment for the reduced CLI startup time?

Comment thread cmd/completion/completion.go Resolved
@pietern

pietern commented Nov 16, 2026

Copy link
Copy Markdown
Contributor Author

@simonfaltum I figured this is not user facing so doesn't deserve a changelog entry.

We had a regression a while back that added 20ms and nobody noticed... :D

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

LGTM. Rechecked the full stack and the completion rationale fix. CI and the focused root/sync/bundle tests pass, and 22 before/after CLI checks matched apart from build-version metadata. The changelog explanation makes sense.


This review was generated with GitHub MCP.

Comment thread cmd/cmd.go Outdated
// Hand-written commands that replace a generated workspace command of the
// same name. Cobra resolves duplicate names by position after an unstable
// sort, so the generated command must not be added at all.
name := func(spec root.CommandSpec) string { return strings.Fields(spec.Use)[0] }

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] Could this be a named helper or a CommandSpec.Name() method, as the Go style guide requests, instead of an inline function for a repeated operation? A follow-up is fine.

@pietern
pietern force-pushed the lazy-cmd branch 2 times, most recently from 18c2d3d to bb9eeca Compare November 16, 2026 16:39
@pietern
pietern added this pull request to the merge queue Nov 16, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to a conflict with the base branch Nov 16, 2026
Base automatically changed from execute-args to main November 16, 2026 19:43
Every invocation built the whole command tree (~1,750 commands and
~3,300 flags) before parsing its args, which took about 4 ms per run.

Top-level commands are now declared as root.CommandSpec values. A
root.Tree holds a placeholder built from each spec's fields, which are
all its parent shows in help, completion, and suggestions, and Tree.Execute
builds the commands that the args resolve to before running cobra.
The tree owns the root command, and the functions that create and run
a bare root command are now unexported, so commands can only be added
as specs and the CLI can only run through Tree.Execute.
root.NewCommand panics if building a command changes the fields its
spec declares.

Co-authored-by: Isaac <no-reply@databricks.com>
@pietern
pietern enabled stacked auto-merge November 16, 2026 20:02
@pietern
pietern added this pull request to the merge queue Nov 16, 2026
Merged via the queue into main with commit 731fdaf Nov 16, 2026
32 checks passed
@pietern
pietern deleted the lazy-cmd branch November 16, 2026 20:36
idelafuente-oc pushed a commit to idelafuente-oc/cli that referenced this pull request Nov 20, 2026
## Changes
`root.Execute` now takes the args to run instead of reading them from
the command, where cobra falls back to `os.Args` if they were never set.
`nil` means no arguments. `main` passes `os.Args[1:]`, and tests pass
their args directly instead of calling `SetArgs` first.

## Why
databricks#7487 builds top-level commands lazily, so it has to resolve the command
from the args before cobra runs. That requires `Execute` to receive the
args.

## Tests
New unit test `TestExecuteWithNilArgsRunsWithoutArgs` checks that nil
means no arguments; existing unit and acceptance tests cover the
callers.

This pull request and its description were written by Isaac.

Co-authored-by: Isaac <no-reply@databricks.com>
idelafuente-oc pushed a commit to idelafuente-oc/cli that referenced this pull request Nov 20, 2026
## Changes
Users, and agents acting for them, can't report a CLI problem from the
CLI. This adds `databricks feedback [--command "<command>"] MESSAGE`,
which sends the message to Databricks from the authenticated workspace.
It supersedes databricks#7567 and keeps its behavior.

- `--command` names the command the feedback is about, as a free string.
Its first word picks the owning team: `air` goes to
`ModelTraining.AIRuntime`, `bundle` to `DeveloperEcosystem.CoreDabs`,
anything else to `DeveloperEcosystem.DatabricksCLI`. Its words may only
use command-name characters, which rejects flags and paths, and it is at
most 200 characters. `origin` is the words joined with underscores
(`bundle_deploy`).
- Each submission is one `fast_feedback_log` event (the in-product
feedback widget's) posted to `/telemetry-ext`, using existing fields
only; the agent and `--run-id` ride in the user agent.
- A detected AI agent needs the user's approval: a prompt when stdin and
stderr are terminals, or `--yes` otherwise. The prompt shows the message
with invisible characters escaped, the workspace, and every choice sent
with it. Declining, including Ctrl-D, prints "Feedback not sent." and
exits 1. Humans are not prompted.
- The message, flags and approval are checked before authenticating.
`--target` is rejected, because the bundle is never loaded. An unquoted
message or `--command` gets an error that says what to quote.
- The send makes one attempt with SDK retries off and is bounded by 30
s, including a token refresh; the login before it works as for any
command. Success prints a reference ID (JSON with `-o json`). A failure
names the ID and says whether the feedback was definitely not sent: it
failed before a connection was set up or while authenticating, or the
server answered 4xx or accepted none of it.
- Feedback is sent even with `DATABRICKS_CLI_DISABLE_TELEMETRY` set; the
help says so.
- `telemetry.Send`, `telemetry.NotSent` and `cmdio.IsErrorTTY` are new,
and `DatabricksCliLog` is tagged `omitzero` so a feedback entry carries
only `fast_feedback_log` (existing events always set it).

## Why
Feedback text is retained centrally, so an agent's text needs the user's
approval before it is sent. A retry after an ambiguous failure could
file the feedback twice, so the command makes one attempt and reports
the ID on failure.

## Decisions to review
- `--command` is not looked up in the command tree, which would mean
building every command (the tree is lazy since databricks#7487). A typo, an
argument or a `databricks` prefix reaches `origin` as typed, and a
misspelled `bundle` goes to the CLI team. Keeping only the first word
would drop details like `bundle_deploy`.
- `Text` is user-authored, which telemetry normally never carries. That
is the point of the event, and an agent's text needs the user's approval
first.
- The prompt reads a plain line and needs only stdin and stderr to be
terminals, not `cmdio.IsPromptSupported`, so it also works with
`TERM=dumb` and MSYS2 pipes. It escapes invisible characters instead of
stripping them like `cmd/air`'s `stripControl`, so the user sees exactly
what is sent.
- `feedback` is exempt from the aitools install hint, like other
one-shot commands.
- The single-attempt client repeats the setup in
`cmd/air/validateconfig.go`; sharing it would touch `cmd/air` and
`experimental/ssh`.

## Tests
- `acceptance/cmd/feedback`: routing, the JSON receipt, agent refusal
and `--yes`, input errors (including without a login), telemetry
disabled, and a broken bundle.
- `TestSendMakesOneAttempt`: one request each for success,
`numProtoSuccess: 0`, HTTP 403, 500 and 503, and a TCP reset.
`TestSendFailingBeforeConnectingIsNotSent`: a refused connection and an
untrusted certificate count as not sent.
`TestSendTimeoutBoundsTokenAcquisition`: a blocked token source stops at
the deadline.
- Unit tests cover input checks and quoting hints, approval with
`NO_COLOR`, `TERM=dumb` and stderr redirected, escaping, and that a
declined or ended prompt sends nothing. The full unit and acceptance
suites, `./task lint` and `./task checks` pass locally.
- One real submission to a Databricks staging workspace was stored with
every field as sent. The acceptance test stays local, because a cloud
run would file real feedback on every CI 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

AIR Databricks AI Runtime CLI aitools AI tools (databricks aitools) related changes auth DABs DABs related issues

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants