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

[jwhartley]

Summary

flowctl raw get --help documents a -q short flag in its own usage example, but the parser only accepts the long form --query. The help text is self-contradictory: it tells you to use -q, and -q errors.

Repro

The -q short flag shown in the command's own help example does not exist; it errors as an unknown argument. Using -q alone:

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

The equivalent with the long flag works (repeat --query for multiple params):

flowctl raw get --table data_planes --query select=data_plane_name --query id=eq.<some-id>
[{"data_plane_name":"..."}]

So this is not a "can't combine -q and --query" issue; -q is simply undefined. Workaround: always use --query.

Root cause (confirmed in source)

crates/flowctl/src/raw/mod.rs

The doc comment on the Get variant (which clap renders as the raw get long help) shows -q (lines 43-44):

/// Pass query arguments as multiple `-q key=value` arguments.
/// For example: `-q select=col1,col2 -q col3=eq.MyValue`
Get(Get),

But the query arg on the Get struct is defined long-only, with no short = 'q' (lines 92-94):

/// Optional query parameters.
#[clap(long, value_parser = parse_key_val::<String, String>, number_of_values = 1)]
query: Vec<(String, String)>,

So the documented -q example can never parse. The same long-only query pattern is used by Update (lines 103-105) and Rpc (lines 117-119), whose help refers back to get for query usage, so the inconsistency propagates to those commands too.

Broader observation (open question for maintainers)

This is one instance of a more general thing: flowctl's short-flag conventions vary across subcommands, and help examples don't always match what the parser accepts. A quick scan found only two real short flags in the whole CLI: the global -o/--output (crates/flowctl/src/output.rs:8) and -f/--flows (crates/flowctl/src/catalog/list/mod.rs:10). The one place a short flag appears in a help example is the -q above, which doesn't exist.

Tools and AI agents take help text literally, so a documented-but-unparseable flag costs them disproportionately (they'll emit -q because the help told them to, then fail). Two reasonable directions, leaving the call to you:

1. Add short = 'q' to the query args so the documented example works as written.
2. Or change the help example to use --query so it matches the parser.

No strong opinion on whether flowctl should standardize short aliases more broadly; flagging it as a DX/predictability question for whoever owns the CLI.

Priority

Low. DX papercut with an easy workaround (--query). Noting it mainly because it's a cheap fix and it trips up scripts and agents more than humans.