fix(cli): wrap help output on narrow terminals

[claude]

Requested by Katie Schilling · Slack thread

Before: tigris --help in a 37-column terminal. Every command description runs off the right edge on a single line — the longest is 192 characters, so the output is unreadable and unscrollable. This is not a browser-only problem: it happens in any real terminal narrower than about 75 columns (a split tmux pane, a side-by-side editor terminal, a phone SSH client). It surfaced via the browser shell at tigrisdata.com/try-cli, which reports ~37 columns; packages/cli-shell was already passing the true width through to the CLI's process shim correctly, so the CLI was seeing 37 and still emitting 192-character lines.

Usage: tigris [options] [command]

Command line interface for Tigris

Options:
  -V, --version                   output the version number
  -h, --help                      display help for command

Commands:
  init|start [options]            Connect Tigris to your AI coding agent — MCP server config and agent skills
  configure|c [options]           Save access-key credentials to ~/.tigris/config.json for persistent use across all commands
  login|l [options]               Start a session via OAuth (default) or temporary credentials. Session state is cleared on logout
…(21 more commands, same shape)

After: below the readable-column threshold each description is stacked under its own term and wrapped to the terminal width. Nothing exceeds the terminal width at 37, 46 or 60 columns.

Usage: tigris [options] [command]

Command line interface for Tigris

Options:
  -V, --version
      output the version number
  -h, --help
      display help for command

Commands:
  init|start [options]
      Connect Tigris to your AI
      coding agent — MCP server
      config and agent skills
  configure|c [options]
      Save access-key credentials to
      ~/.tigris/config.json for
      persistent use across all
      commands
  login|l [options]
      Start a session via OAuth
      (default) or temporary
      credentials. Session state is
      cleared on logout
…

Longest line in tigris --help, measured in a real pty against a fresh build:

columns	before	after
37	192	37
46	192	46
60	192	60
80	80	80 (byte-identical)
120	120	120 (byte-identical)

How

Commander aligns every description in a column to the right of the command/option terms, and only wraps a description when that column is at least minWidthToWrap (40) characters wide. Our widest term, cp|copy [options] <src> <dest>, is 30 characters, so the column is only columns - 34 wide and the check fails below ~75 columns. Crucially, when it fails Commander does not fall back to a narrower column — Help.formatItem skips wrapping altogether and emits the description as one unwrapped line. That is why narrow terminals rendered worse than the 80-column default rather than better.

createProgram now passes a small configureHelp override (narrowHelpConfiguration in packages/cli/src/cli-core.ts). It keeps Commander's aligned two-column layout whenever the inline column would be at least 34 characters, and otherwise stacks the description under its term and wraps it to columns - 6. It also lowers minWidthToWrap so Commander will perform that full-width wrap. The override is applied before registerCommands, so every subcommand inherits it via Commander's copyInheritedSettings — tigris buckets --help at 37 columns drops from 182 characters to 43 (the unwrapped Usage: line, which Commander never wraps).

No specs.yaml descriptions were touched.

Alternative, if you'd prefer it: the one-line version is program.configureHelp({ minWidthToWrap: 12 }). I tried it first and it isn't enough — at 37 columns the inline column is only 3 characters wide, so Commander's own floor still vetoes the wrap and the output stays at 192 characters; at 46 columns it does wrap, but into a 12-character ribbon that blows tigris --help up to 233 lines. Happy to swap to any variant of the threshold (34) or indent (6) you prefer.

Checks run

• pnpm install --frozen-lockfile — clean
• pnpm run lint (Biome, 434 files) — clean
• pnpm -r run build — clean
• pnpm -r run publint — clean
• packages/cli vitest run — 40 files, 1036 passed, 224 skipped (integration tests needing bucket credentials)
• Added three unit tests for the formatter in packages/cli/test/cli-core.test.ts
• Changeset added (patch for @tigrisdata/cli), which also switches CI's gated test job on for this PR

🤖 Generated with Claude Code

https://claude.ai/code/session_01RXrAPPY3ZWz7k3E73V6c6M

---

Generated by Claude Code

---

Note

Low Risk
Help formatting only; no command execution, auth, or data-path changes, and wide-terminal output is intended to stay the same.

Overview
Fixes unreadable tigris --help (and inherited subcommand --help) when the terminal is narrower than ~75 columns, where Commander stopped wrapping descriptions and emitted lines up to ~192 characters.

createProgram now calls configureHelp with narrowHelpConfiguration: when the inline description column would be too narrow, each term’s description is stacked underneath and wrapped to the terminal width (with a lower minWidthToWrap so wrapping actually runs). Wider terminals (roughly 80+ columns) keep Commander’s usual two-column layout.

Adds a patch changeset for @tigrisdata/cli and three unit tests that assert line length, stacked layout at 37 columns, and aligned layout at 100 columns.

^{Reviewed by Cursor Bugbot for commit 5bff7fd. Bugbot is set up for automated code reviews on this repo. Configure here.}

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; the formatter addresses narrow-terminal overflow while retaining the expected wider layout.

Summary

• Adds a reusable narrow-terminal help formatter before command registration so subcommands inherit it.
• Adds tests for width bounds, stacked formatting, and wide-terminal alignment.
• Adds a patch changeset for @tigrisdata/cli.