Skip to content

fix(flowctl): honor -q short flag on raw get (#3084)#3172

Open
0xfandom wants to merge 2 commits into
estuary:masterfrom
0xfandom:fix/flowctl-raw-q-short-flag
Open

fix(flowctl): honor -q short flag on raw get (#3084)#3172
0xfandom wants to merge 2 commits into
estuary:masterfrom
0xfandom:fix/flowctl-raw-q-short-flag

Conversation

@0xfandom

Copy link
Copy Markdown

Description:

flowctl raw get documents a -q short flag in its own long help, but the parser only ever accepted --query, so the documented invocation fails:

$ flowctl raw get --table data_planes -q select=data_plane_name
error: unexpected argument '-q' found

The help text comes from the Get variant's doc comment ("Pass query arguments as multiple -q key=value arguments. For example: -q select=col1,col2 -q col3=eq.MyValue"), while Get::query was declared #[clap(long, ...)] — long-only. This adds short = 'q', making the parser match what the help has always promised.

I took the add-the-flag route rather than amending the help text: the documented spelling is the friendlier one, and -q is unused across flowctl — the only short flags are the global -o/--output and catalog list's -f/--flows — so it was free to take.

A second commit extends -q to raw rpc and raw update, which take the same query parameters and whose help defers to get ("As with get, you may pass optional query parameters"). It's split out so it can be dropped if you'd rather keep this strictly to #3084.

Fixes #3084

Workflow steps:

-q now works anywhere --query did, and is repeatable:

# Previously failed; now works:
flowctl raw get --table data_planes -q select=data_plane_name

# Repeatable, and mixable with the global -o:
flowctl raw get --table data_planes -o json -q select=id,name -q id=eq.42

# Same short flag now on rpc and update:
flowctl raw rpc --function my_fn -q key=value --body '{}'
flowctl raw update --table my_table -q id=eq.42 --body '{}'

--query is unchanged and keeps working; this is purely additive, so no existing invocation breaks. raw get --help now renders -q, --query <QUERY>, matching the prose above it.

Documentation links affected:

None. The only place -q is documented is the command's own long help, which this change makes accurate rather than requiring an edit. Nothing under site/docs/ references raw get's query flag.

Notes for reviewers:

  • Two commits: the first is the get fix for flowctl: raw get help documents -q short flag but only --query is accepted #3084, the second extends -q to rpc/update for consistency. Drop the second if it's out of scope for you.
  • On verification: I couldn't complete cargo build -p flowctl locally — simd-doc's C++ build fails on my machine with rust::Slice<const unsigned char>::iterator failing the contiguous_iterator concept check against my SDK's libc++ headers. That's a pre-existing local toolchain issue on a clean tree, unrelated to this change, and I didn't want to bundle a toolchain fix into a one-line CLI fix.
  • So I verified the parsing behavior against clap 4.5.48 with the Get/Rpc/Update structs replicated exactly: the issue's invocation is rejected before the change and accepted after; -q and --query produce identical parses; repeated -q accumulates; -q doesn't collide with the global -o; and invalid values still fail through parse_key_val (-q no-equalsinvalid KEY=value: no `=` found in `no-equals` ). Relying on CI for the full build.
  • No tests or snapshots currently cover raw's arg parsing, so I didn't add any — happy to if you'd like coverage here.

0xfandom added 2 commits July 15, 2026 16:09
The long help for `raw get` tells users to pass query arguments as
`-q key=value`, but `Get::query` was declared `#[clap(long, ...)]`, so
the parser only accepted `--query` and rejected the documented form:

    $ flowctl raw get --table data_planes -q select=data_plane_name
    error: unexpected argument '-q' found

Add the short flag rather than amend the help text: the documented
spelling is the friendlier one, and `-q` is unused elsewhere in flowctl
(the only short flags are the global `-o/--output` and `catalog list`'s
`-f/--flows`), so it is free to take.

Fixes estuary#3084
`raw rpc` and `raw update` take the same optional query parameters as
`raw get`, and rpc's help defers to it ("As with `get`, you may pass
optional query parameters"), so a user who learns `-q` from `get` will
reasonably expect it on both. Give them the same short flag.
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.

flowctl: raw get help documents -q short flag but only --query is accepted

1 participant