dbt-labs / dbt-labs/dbt

CLI help output: organize flags into sections (Global vs subcommand-specific)

Open
#15,234 0 comments 0 reactions 0 assignees View on GitHub
type:feature
Dominant language
Rust
Stars
13.8k
Forks
2.6k
Avg merge
21h 31m
Merged PRs (30d)
56

Description

## Summary

The `--help` output for dbt v2 subcommands (e.g. `dbt show`, `dbt run`, `dbt compile`, `dbt list`, `dbt seed`) is extremely verbose and hard to navigate because all flags — global project settings, logging knobs, selection filters, and subcommand-specific options — appear in a single undifferentiated list.

## Current behavior

Running `dbt show --help` produces ~70 flags in one flat block. There is no visual distinction between:

- **Global project flags** (apply to every command): `--target`, `--project-dir`, `--profile`, `--profiles-dir`, `--vars`, `--threads`, ...
- **Selection flags** (shared run-time filters): `--select`, `--exclude`, `--selector`, `--indirect-selection`, `--resource-type`, ...
- **Logging / output flags**: `--debug`, `--quiet`, `--log-level`, `--log-format`, `--log-path`, ...
- **Subcommand-specific flags**: `--inline`, `--limit`, `--output`, `--with-sample`, `--sampled`, ... (show only)

As a result, users scanning for the flag they need have to read 70+ lines before finding anything relevant.

## Proposed solution

Two complementary clap features, both single-file changes to `CommonArgs`:

### 1. Group flags under labelled sections (`help_heading`)

Add `help_heading = "Global Options"` (and sub-headings like `"Selection"`, `"Logging"`) to fields in `CommonArgs`. Subcommand-specific fields stay under the default `"Options"` heading. A first-cut grouping for `dbt show`:

```
Options:
--inline Show the given query
--limit Limiting number of shown rows [default: 10]
--output Display rows in different formats
--resource-type <...> Select nodes of a specific type
--exclude-resource-type Exclude nodes of a specific type
--static-analysis Enable/disable SQL analysis
--unchecked Skip local type checking
--with-sample / --sampled Sample configuration

Selection:
-s, --select Select nodes to run
--exclude Select nodes to exclude
--selector Named YAML selector
--indirect-selection Test selection adjacency mode

Global Options:
-t, --target The target to execute
--project-dir The directory to load the project from
--profile The profile to use
--profiles-dir The directory to load profiles from
--vars Supply var bindings
--threads Number of threads to use
--defer / --state State-based deferral
...

Logging:
--debug / -d Display debug logging
--quiet / -q Suppress non-error output
--log-level Minimum severity for console/log file
--log-format Logging format
--log-path Override log output path
...
```

### 2. Hide global flags from `-h`, show them in `--help` (`hide_short_help`)

Add `hide_short_help = true` to every field in `CommonArgs` so that:

- `dbt show -h` → brief help, **subcommand-specific flags only** (fast lookup for the flag you actually care about)
- `dbt show --help` → full help, **all sections including Global Options and Logging**

This is a well-established convention (git, cargo, ripgrep all use it) and requires no custom flag parsing. Users already know that `--help` is more thorough than `-h`.

```rust
// CommonArgs fields get both attributes:
#[arg(global = true, hide_short_help = true, help_heading = "Global Options", long, env = "DBT_TARGET")]
pub target: Option,
```

## Implementation

Both changes live entirely in `CommonArgs` in `dbt-clap-core/src/lib.rs` and propagate automatically to every subcommand via `#[clap(flatten)]`. No behaviour is affected — this is purely cosmetic.

## Why this matters

- New users trying `dbt run --help` to discover the right flag have to scroll through ~70 entries
- Power users know the flags but still have to visually search through unrelated global options to find `--full-refresh` or similar
- The split between "things you set once in a profile/env var" and "things you pass per-run" is completely invisible

Both changes together give you a fast `-h` for the common case and a well-organized `--help` for when you need the full picture.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.