Skip to content

Argue from what survives, now that the official CLI is conversational - #37

Closed
ivanvyd wants to merge 1 commit into
fix/complete-results-and-docs-contractfrom
docs/positioning-after-cli-ask
Closed

Argue from what survives, now that the official CLI is conversational#37
ivanvyd wants to merge 1 commit into
fix/complete-results-and-docs-contractfrom
docs/positioning-after-cli-ask

Conversation

@ivanvyd

@ivanvyd ivanvyd commented Aug 5, 2026

Copy link
Copy Markdown
Owner

Stacked on #36. Base is fix/complete-results-and-docs-contract; GitHub will retarget this to
main when #36 merges. Review #36 first.

The fact

Databricks CLI v1.10.0 — the version docs/compatibility.md already records as tested — ships:

databricks genie ask QUESTION [flags]
  -s, --session string    Session id (any string) to continue a conversation across calls
      --include-sql       Show SQL queries executed by the agent
  -o, --output type       text or json

Read from databricks genie ask --help on the installed binary, not from documentation.

ROADMAP.md named this event in advance: "The official CLI becoming conversational. The
differentiator would narrow to Question Packs and the .NET library, and the roadmap would follow."

It happened. This PR is the roadmap following.

What changes

README.md "Why this exists" is rewritten. It argued that this project exists because the
official CLI makes you manage six identifiers, a polling loop and a two-step download by hand. That
argument is now losable, so it is gone. What replaces it is the two claims that survive scrutiny:
Databricks publishes SDKs for Python, Java, Go and R but not .NET, and Question Packs have no
equivalent
. The section now opens by pointing readers at databricks genie ask if a terminal
answer is all they want.

docs/decisions/0001 gains a dated correction, not a rewrite. The decision stands — still no
MCP server — but two premises do not:

  • It claimed an MCP server would duplicate Databricks' managed endpoints. Those endpoints are
    stateless, so a stateful one would do the thing theirs cannot.
  • It used that same statelessness as an argument against MCP, which confuses Databricks'
    implementation with the protocol.

The honest reason was always scope, and that is what the decision now rests on. GOVERNANCE.md and
ROADMAP.md are updated to say the same thing as the ADR rather than the superseded version.

ROADMAP.md moves the prediction into a dated statement that it occurred, rather than deleting
it. A project that predicts something, is right, and then says nothing has stopped paying attention.

NuGet version badges for both packages. Version only — a downloads badge on a package published
four days ago advertises a small number.

One claim I deliberately hedged

The official ask exposes no flag naming which Genie Agent answers — no space id argument, no
--space or --agent. The README says it "exposes no flag for" targeting a named Agent rather
than "you cannot choose the Agent", because its help text does not say how it resolves one and I
have not verified that behaviour.

Verification

223 tests pass. The docs-contract test added in #36 parses every lakespeak … example in the
rewritten README against the real command tree. All 40+ relative markdown links across the
repository resolve. Documentation-only otherwise — no source changes.

Databricks CLI v1.10.0 ships `databricks genie ask`: stateful across calls
with -s, SQL with --include-sql, JSON with -o json. Read from the installed
binary's help, not from documentation.

The README's "Why this exists" argued that this project exists because the
official CLI makes you manage six identifiers and a polling loop by hand.
That argument is now losable, so it is gone. What replaces it is the two
claims that survive: Databricks publishes SDKs for Python, Java, Go and R
but not .NET, and Question Packs have no equivalent anywhere. The README
now points readers at `databricks genie ask` first if a terminal answer is
all they want.

ROADMAP.md predicted this exact event under "things that would change the
plan". It is moved to a dated statement that it happened and the plan
followed, rather than deleted -- a project that predicts something, is
right, and then says nothing has stopped paying attention.

ADR 0001 gains a correction rather than a rewrite. Its decision stands:
still no MCP server. Two of its premises do not. It claimed an MCP server
would duplicate Databricks' managed endpoints, and those endpoints are
stateless, so a stateful one would do the thing theirs cannot. It also used
that statelessness as an argument against MCP, which confuses Databricks'
implementation with the protocol. The real reason was always scope, and
that is what the decision now rests on. GOVERNANCE.md and ROADMAP.md say
the same thing as the ADR rather than the old version of it.

NuGet version badges, so the README shows what is actually published.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant