Truthful help and exit codes; grouped global flags; examples

johnpmitsch · johnpmitsch · commit 00ad0b33f18e · 2026-06-10T16:16:46.000-04:00
- Required flags are now clap-enforced and shown in usage lines:
  endpoint create (--chain/--network), endpoint update (--label), and
  the six stream create flags via required_unless_present(config_file).
  Missing-flag errors now list everything missing at once instead of
  failing one runtime check at a time.
- clap usage errors (typo'd subcommand, missing required flag) exit 1,
  matching runtime argument errors, so exit 2 always and only means
  "the API returned an error". --help/--version still exit 0.
- Global flags are grouped under a "Global options" heading in every
  subcommand's --help, so command-specific flags surface first.
- after_help examples on the top level and on endpoint/stream/webhook/
  kv/auth.
- README exit-code table updated.
diff --git a/README.md b/README.md
@@ -240,7 +240,7 @@ re-running it.
 | Code | Meaning |
 |---|---|
 | 0 | Success |
-| 1 | CLI error (bad argument, IO, decode) |
+| 1 | CLI error (usage/bad argument, IO, decode) |
 | 2 | API error (server returned 4xx/5xx) |
 | 3 | Network failure (timeout, connect, transport) |
 | 4 | Missing or invalid API key / config |
diff --git a/src/cli.rs b/src/cli.rs
@@ -25,7 +25,16 @@ use crate::output::Format;
                   (--config-file path if given, else ~/.config/qn/config.toml). Run `qn auth login`\n\
                   to save a key the first time.",
     propagate_version = true,
-    disable_help_subcommand = true
+    disable_help_subcommand = true,
+    after_help = "Examples:\n  \
+        qn auth login\n  \
+        qn endpoint create --chain ethereum --network mainnet\n  \
+        qn endpoint list -o json\n  \
+        qn endpoint logs ep-1234 --from 1h\n  \
+        qn chain list",
+    // Group the global flags under their own heading in every subcommand's
+    // --help, so command-specific flags surface first under "Options".
+    next_help_heading = "Global options"
 )]
 pub struct Cli {
     /// API key. Overrides the config file.
diff --git a/src/commands/auth.rs b/src/commands/auth.rs
@@ -16,6 +16,11 @@ use crate::context::GlobalArgs;
 use crate::errors::CliError;
 
 #[derive(Debug, ClapArgs)]
+#[command(after_help = "Examples:\n  \
+    qn auth login                       # prompts for the key (hidden input)\n  \
+    qn auth login --api-key <KEY>       # non-interactive (e.g. CI)\n  \
+    qn auth whoami                      # verify the key against the API\n  \
+    qn --config-file ./ci.toml auth status")]
 pub struct Args {
     #[command(subcommand)]
     pub cmd: AuthCmd,
diff --git a/src/commands/endpoint/mod.rs b/src/commands/endpoint/mod.rs
@@ -24,6 +24,12 @@ pub use security::SecurityCmd;
 pub use tag::TagCmd;
 
 #[derive(Debug, ClapArgs)]
+#[command(after_help = "Examples:\n  \
+    qn endpoint create --chain ethereum --network mainnet\n  \
+    qn endpoint list -o json\n  \
+    qn endpoint logs ep-1234 --from 1h --details\n  \
+    qn endpoint pause ep-1234\n  \
+    qn endpoint bulk pause ep-1 ep-2 --yes")]
 pub struct Args {
     #[command(subcommand)]
     pub cmd: EndpointCmd,
@@ -123,12 +129,12 @@ pub struct ListArgs {
 
 #[derive(Debug, ClapArgs)]
 pub struct CreateArgs {
-    /// Blockchain (e.g. `ethereum`, `solana`).
+    /// Blockchain (e.g. `ethereum`, `solana`; run `qn chain list` to see all).
     #[arg(long)]
-    pub chain: Option<String>,
+    pub chain: String,
     /// Network (e.g. `mainnet`).
     #[arg(long)]
-    pub network: Option<String>,
+    pub network: String,
 }
 
 #[derive(Debug, ClapArgs)]
@@ -137,7 +143,7 @@ pub struct UpdateArgs {
     pub id: String,
     /// New label.
     #[arg(long)]
-    pub label: Option<String>,
+    pub label: String,
 }
 
 #[derive(Debug, ClapArgs)]
@@ -232,22 +238,9 @@ async fn list(a: ListArgs, ctx: Ctx) -> Result<(), CliError> {
 }
 
 async fn create(a: CreateArgs, ctx: Ctx) -> Result<(), CliError> {
-    let missing: Vec<&str> = [
-        ("--chain", a.chain.is_none()),
-        ("--network", a.network.is_none()),
-    ]
-    .iter()
-    .filter_map(|(name, missing)| if *missing { Some(*name) } else { None })
-    .collect();
-    if !missing.is_empty() {
-        return Err(CliError::Arg(format!(
-            "'endpoint create' requires {}. Run 'qn chain list' to see available chains.",
-            missing.join(" and "),
-        )));
-    }
     let req = CreateEndpointRequest {
-        chain: a.chain,
-        network: a.network,
+        chain: Some(a.chain),
+        network: Some(a.network),
     };
     let resp = ctx.sdk.admin.create_endpoint(&req).await?;
     ctx.out
@@ -264,10 +257,9 @@ async fn show(id: &str, ctx: Ctx) -> Result<(), CliError> {
 }
 
 async fn update(a: UpdateArgs, ctx: Ctx) -> Result<(), CliError> {
-    if a.label.is_none() {
-        return Err(CliError::Arg("'endpoint update' requires --label.".into()));
-    }
-    let req = UpdateEndpointRequest { label: a.label };
+    let req = UpdateEndpointRequest {
+        label: Some(a.label),
+    };
     ctx.sdk.admin.update_endpoint(&a.id, &req).await?;
     ctx.out.note(&format!("✓ Updated endpoint {}", a.id));
     Ok(())
diff --git a/src/commands/kv/mod.rs b/src/commands/kv/mod.rs
@@ -11,6 +11,11 @@ use crate::context::Ctx;
 use crate::errors::CliError;
 
 #[derive(Debug, ClapArgs)]
+#[command(after_help = "Examples:\n  \
+    qn kv set put mykey myvalue\n  \
+    qn kv set get mykey\n  \
+    qn kv list create mylist item1 item2\n  \
+    qn kv list contains mylist item1")]
 pub struct Args {
     #[command(subcommand)]
     pub cmd: KvCmd,
diff --git a/src/commands/stream/actions.rs b/src/commands/stream/actions.rs
@@ -39,27 +39,16 @@ pub(super) async fn create(a: CreateArgs, ctx: Ctx) -> Result<(), CliError> {
 }
 
 fn build_create_params(a: CreateArgs) -> Result<CreateStreamParams, CliError> {
-    let name = a
-        .name
-        .ok_or_else(|| CliError::Arg("--name is required".into()))?;
-    let network = a
-        .network
-        .ok_or_else(|| CliError::Arg("--network is required".into()))?;
-    let dataset = a
-        .dataset
-        .ok_or_else(|| CliError::Arg("--dataset is required".into()))?;
-    let start = a
-        .start
-        .ok_or_else(|| CliError::Arg("--start is required".into()))?;
-    let end = a
-        .end
-        .ok_or_else(|| CliError::Arg("--end is required (-1 for continuous)".into()))?;
-    let region = a
-        .region
-        .ok_or_else(|| CliError::Arg("--region is required".into()))?;
-    let url = a.webhook.ok_or_else(|| {
-        CliError::Arg("--webhook is required (or use --config-file for other destinations)".into())
-    })?;
+    // These flags are `required_unless_present = "config_file"` in clap, and
+    // this function is only reached when --config-file was NOT supplied.
+    const ENFORCED: &str = "enforced by clap unless --config-file is present";
+    let name = a.name.expect(ENFORCED);
+    let network = a.network.expect(ENFORCED);
+    let dataset = a.dataset.expect(ENFORCED);
+    let start = a.start.expect(ENFORCED);
+    let end = a.end.expect(ENFORCED);
+    let region = a.region.expect(ENFORCED);
+    let url = a.webhook.expect(ENFORCED);
 
     let filter_function = match (a.filter, a.filter_file) {
         (Some(s), None) => Some(STANDARD.encode(s)),
diff --git a/src/commands/stream/mod.rs b/src/commands/stream/mod.rs
@@ -18,6 +18,12 @@ use crate::context::Ctx;
 use crate::errors::CliError;
 
 #[derive(Debug, ClapArgs)]
+#[command(after_help = "Examples:\n  \
+    qn stream list --limit 20\n  \
+    qn stream create --name blocks --network ethereum-mainnet --dataset block \\\n      \
+        --start 24691804 --end=-1 --region usa-east --webhook https://hook.example.com\n  \
+    qn stream create --config-file stream.json\n  \
+    qn stream pause s-1234")]
 pub struct Args {
     #[command(subcommand)]
     pub cmd: StreamCmd,
@@ -72,28 +78,33 @@ pub struct CreateArgs {
     pub config_file: Option<PathBuf>,
 
     /// Stream name.
-    #[arg(long)]
+    #[arg(long, required_unless_present = "config_file")]
     pub name: Option<String>,
     /// Network (e.g. `ethereum-mainnet`).
-    #[arg(long)]
+    #[arg(long, required_unless_present = "config_file")]
     pub network: Option<String>,
     /// Dataset (snake_case).
-    #[arg(long, value_enum)]
+    #[arg(long, value_enum, required_unless_present = "config_file")]
     pub dataset: Option<DatasetArg>,
     /// Start block.
-    #[arg(long)]
+    #[arg(long, required_unless_present = "config_file")]
     pub start: Option<i64>,
     /// End block (`-1` for continuous).
-    #[arg(long, allow_hyphen_values = true)]
+    #[arg(
+        long,
+        allow_hyphen_values = true,
+        required_unless_present = "config_file"
+    )]
     pub end: Option<i64>,
     /// Region.
-    #[arg(long, value_enum)]
+    #[arg(long, value_enum, required_unless_present = "config_file")]
     pub region: Option<RegionArg>,
     /// Billing plan slug (optional).
     #[arg(long)]
     pub plan: Option<String>,
-    /// Webhook URL for the primary destination.
-    #[arg(long)]
+    /// Webhook URL for the primary destination (use `--config-file` for other
+    /// destination types).
+    #[arg(long, required_unless_present = "config_file")]
     pub webhook: Option<String>,
     /// Webhook security token (32-byte minimum). Optional.
     #[arg(long)]
diff --git a/src/commands/webhook/mod.rs b/src/commands/webhook/mod.rs
@@ -12,6 +12,11 @@ use crate::context::Ctx;
 use crate::errors::CliError;
 
 #[derive(Debug, ClapArgs)]
+#[command(after_help = "Examples:\n  \
+    qn webhook list\n  \
+    qn webhook create --name alerts --network ethereum-mainnet \\\n      \
+        --url https://hook.example.com --template evmWalletFilter --wallet 0xabc\n  \
+    qn webhook pause wh-1234")]
 pub struct Args {
     #[command(subcommand)]
     pub cmd: WebhookCmd,
diff --git a/src/errors.rs b/src/errors.rs
@@ -53,7 +53,8 @@ pub enum CliError {
 /// Maps a [`CliError`] to a process exit code per the plan.
 ///
 /// - 0: success (never produced here)
-/// - 1: generic CLI failure (arg parse, IO, decode)
+/// - 1: generic CLI failure (arg parse, IO, decode). clap usage errors are
+///   mapped to 1 in main.rs too, so 2 always and only means an API error.
 /// - 2: SdkError::Api (server returned a non-2xx)
 /// - 3: SdkError::Http (network failure)
 /// - 4: NoApiKey / BadConfig
diff --git a/src/main.rs b/src/main.rs
@@ -8,7 +8,21 @@ use qn::errors::{exit_code_for, render};
 
 #[tokio::main]
 async fn main() -> ExitCode {
-    let cli = Cli::parse();
+    // Map clap usage errors to exit 1 — the same bucket as runtime argument
+    // errors — so exit 2 always and only means "the API returned an error".
+    // (clap's own Error::exit would use 2 for both.)
+    let cli = match Cli::try_parse() {
+        Ok(cli) => cli,
+        Err(e) => {
+            // --help/--version print to stdout and are not errors.
+            let _ = e.print();
+            return if e.use_stderr() {
+                ExitCode::from(1)
+            } else {
+                ExitCode::SUCCESS
+            };
+        }
+    };
     let verbose = cli.verbose;
     match cli.run().await {
         Ok(()) => ExitCode::SUCCESS,
diff --git a/tests/common/mod.rs b/tests/common/mod.rs
@@ -54,7 +54,8 @@ async fn run_qn_inner(base_url: &str, extra_args: &[&str], inject_key: bool) ->
     let cli = match Cli::try_parse_from(&argv) {
         Ok(c) => c,
         Err(e) => {
-            let exit = if e.use_stderr() { 2 } else { 0 };
+            // Mirrors main.rs: usage errors are exit 1, help/version exit 0.
+            let exit = if e.use_stderr() { 1 } else { 0 };
             return RunOutput {
                 stdout: String::new(),
                 stderr: e.to_string(),
diff --git a/tests/endpoint.rs b/tests/endpoint.rs
@@ -566,12 +566,12 @@ async fn endpoint_ratelimit_set_omits_unset_fields() {
     assert_eq!(out.exit_code, 0, "stderr={}", out.stderr);
 }
 
-// ---- Stage B: required-args pre-flight checks ---- //
+// ---- Required-args enforcement (clap-level, exits 1 before any HTTP) ---- //
 
 #[tokio::test]
 async fn endpoint_create_no_flags_fails_before_api_call() {
     // No mocks mounted; if the CLI tries to make a request, wiremock would 404.
-    // We assert that the pre-flight check fires *before* any HTTP call.
+    // clap rejects the invocation *before* any HTTP call.
     let server = MockServer::start().await;
     let out = run_qn(&server.uri(), &["endpoint", "create"]).await;
     assert_eq!(out.exit_code, 1, "stderr={}", out.stderr);
@@ -593,8 +593,8 @@ async fn endpoint_create_only_chain_fails_before_api_call() {
     .await;
     assert_eq!(out.exit_code, 1, "stderr={}", out.stderr);
     assert!(
-        out.stderr.contains("--network") && !out.stderr.contains("--chain "),
-        "should call out --network specifically; stderr={}",
+        out.stderr.contains("--network <NETWORK>"),
+        "should call out --network; stderr={}",
         out.stderr
     );
     assert_eq!(server.received_requests().await.unwrap().len(), 0);
@@ -609,6 +609,19 @@ async fn endpoint_update_no_flags_fails_before_api_call() {
     assert_eq!(server.received_requests().await.unwrap().len(), 0);
 }
 
+#[tokio::test]
+async fn stream_create_missing_flags_fails_before_api_call() {
+    let server = MockServer::start().await;
+    let out = run_qn(&server.uri(), &["stream", "create", "--name", "x"]).await;
+    assert_eq!(out.exit_code, 1, "stderr={}", out.stderr);
+    assert!(
+        out.stderr.contains("--network") && out.stderr.contains("--webhook"),
+        "stderr={}",
+        out.stderr
+    );
+    assert_eq!(server.received_requests().await.unwrap().len(), 0);
+}
+
 #[tokio::test]
 async fn endpoint_security_set_options_no_flags_fails_before_api_call() {
     let server = MockServer::start().await;
