Add support for URL completions in buf curl

[stefanvanburen]

First mentioned in #2044, which is long something I've wanted. This adds support for completing URLs based on the available RPCs, which either comes from the existing --schema flag or gRPC reflection.

The completion itself works somewhat similar to LSP completion, in that it attempts to complete as far as it can before giving the user an option between the remaining values to disambiguate. It will complete up to the entire service URL, and then provide completions for RPCs within the service (if there are multiple).

This requires one fix upstream in app-go so that subcommands that define ModifyCobra actually run: bufbuild/app-go#5. We'll want to land upstream to main before landing this.

Open to suggestions on the completion UX. It feels fairly natural to me currently, but I'm sure there are edge cases.

Future work here could include better completions for --schema values, either using local directories or BSR modules, and completions for --data values (if we know the schema and the specific RPC targeted by the URL, we know the shape of the JSON for the --data flag). Also, following this pattern of using ModifyCobra, other commands could be made to have better contextual completion.

Also fixes the buf curl help examples to have consistent indentation.

Resolves #2044.

[github-actions]

The latest Buf updates on your PR. Results from workflow Buf CI / buf (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	✅ passed	✅ passed	✅ passed	Mar 31, 2026, 5:30 PM

[stefanvanburen]

ok, as a quick demo gif:

using the following vhs tape:

Output curl-completion.gif

Set Shell fish
Set FontSize 14
Set Width 900
Set Height 400
Set Padding 16
Set Theme "Catppuccin Mocha"

Env PATH "/Users/stefanvanburen/.cache/buf/Darwin/arm64/gobin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"

Hide
Sleep 1s
Type "source ~/.config/fish/completions/buf.fish"
Enter
Sleep 200ms
Show
Ctrl+L
Sleep 200ms

# --protocol flag: static completions (connect, grpc, grpcweb)
Type "buf curl --protocol "
Sleep 500ms
Tab
Sleep 2s
Ctrl+C
Sleep 1s

# --reflect-protocol flag: static completions (grpc-v1, grpc-v1alpha)
Type "buf curl --reflect-protocol "
Sleep 500ms
Tab
Sleep 2s
Ctrl+C
Sleep 1s

# URL via reflection — Tab 1: unambiguous prefix collapses to full service name
Type "buf curl https://demo.connectrpc.com/"
Sleep 500ms
Tab
Sleep 4s

# Tab 2: method completions (Converse, Introduce, Say)
Tab
Sleep 2s

# Select a method by typing a prefix and completing
Type "Say"
Tab
Sleep 2s
Ctrl+C
Sleep 1s

# Same via --schema (no running server needed) — Tab 1: service name
Type "buf curl --schema buf.build/connectrpc/eliza https://demo.connectrpc.com/"
Sleep 500ms
Tab
Sleep 4s

# Tab 2: method completions
Tab
Sleep 2s
Ctrl+C

[stefanvanburen]

Quick UX update: in 20a16ea I added descriptions to the RPC completions about where the schema is coming from (local module, reflection, --schema flag), and also added some basic error handling.

Updated gif:

via this tape:

Output curl-completion.gif

Set Shell fish
Set FontSize 14
Set Width 900
Set Height 400
Set Padding 16
Set Theme "Catppuccin Mocha"

Env PATH "/Users/stefanvanburen/.cache/buf/Darwin/arm64/gobin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"

Hide
Sleep 1s
Type "source ~/.config/fish/completions/buf.fish"
Enter
Sleep 200ms
Show
Ctrl+L
Sleep 200ms

# --protocol flag: static completions (connect, grpc, grpcweb)
Type "buf curl --protocol "
Sleep 500ms
Tab
Sleep 2s
Ctrl+C
Sleep 1s

# --reflect-protocol flag: static completions (grpc-v1, grpc-v1alpha)
Type "buf curl --reflect-protocol "
Sleep 500ms
Tab
Sleep 2s
Ctrl+C
Sleep 1s

# URL via reflection — Tab 1: unambiguous prefix collapses to full service name
Type "buf curl https://demo.connectrpc.com/"
Sleep 500ms
Tab
Sleep 4s

# Tab 2: method completions (Converse, Introduce, Say)
Tab
Sleep 2s

# Select a method by typing a prefix and completing
Type "Say"
Tab
Sleep 2s
Ctrl+C
Sleep 1s

# Same via --schema (no running server needed) — Tab 1: service name
Type "buf curl --schema buf.build/connectrpc/eliza https://demo.connectrpc.com/"
Sleep 500ms
Tab
Sleep 4s

# Tab 2: method completions
Tab
Sleep 2s
Ctrl+C

[doriable]

Overall, this is reasonable, and thank you for updating the cobra helpers, etc. I do think that this should work off the existing resolvers, so I suggested a refactor, but let me know if the suggestion doesn't work ^^"

[doriable]

Would we be instantiating a new httpClient each time we are resolving a completion? When using reflection to resolve schemas at the top-level, we reuse the same transport as the invoker.

[stefanvanburen]

yes, we'd be instantiating a new client each time the user presses tab (or whatever their keyboard shortcut for invoking completions is)?

[doriable]

So this pattern makes sense to me, and mirrors the way buf curl works in general, but I wonder if we can leverage and refactor the existing code paths to support this.

Basically, the command does some validation upfront, sets up the URL, and then sets up the client + resolvers for the schema. I wonder if we can refactor a little bit so that we set up the resolvers for the schema after the validation, and then use that for completions for the URL.

That way, we have a single, consistent code path, and also uses the same container, client, transport, etc.

[stefanvanburen]

added in c48c0a6 if I'm understanding properly!