CLI UX: hard to list supported formats; no compression/decompression distinction; CLI hint list out of date

[Else00]

While using ouch, I ran into three related CLI UX issues around “supported formats.” They all seem to stem from the lack of a straightforward, authoritative way to list formats and their capabilities.

1) There’s no obvious way to list supported formats from the CLI

• There’s no subcommand/flag to print the supported formats.
• --format cannot be queried (e.g. -f ?), and the only way I found to see a list was to intentionally pass an unsupported value and also provide other required args to reach the parsing stage.

Examples

❯ ouch -h
# (no subcommand to list formats)

❯ ouch -f
error: a value is required for '--format <FORMAT>' but none was supplied

❯ ouch -f asd
error: 'ouch' requires a subcommand but one was not provided
  [subcommands: compress, c, decompress, d, list, l, ls, help]

❯ ouch c -f asd file.txt output
[ERROR] Failed to parse `--format asd`
 - Unsupported extension 'asd'

hint: Supported extensions are: tar, zip, bz, bz2, bz3, gz, lz4, xz, lzma, sz, zst, rar, 7z
hint: Supported aliases are: tgz, tbz, tlz4, txz, tzlma, tsz, tzst

Note: the alias tzlma looks like a typo for tlzma.

2) Hints don’t distinguish capabilities (compress vs. decompress)

The hint list shows formats regardless of whether they are compression-capable, decompression-only, or unsupported for creation due to licensing. This leads to a confusing flow: a format appears in the hint, but then fails later when actually attempting to compress.

Examples

❯ ouch d -f asd file.compressed
[ERROR] Failed to parse `--format asd`
 - Unsupported extension 'asd'

hint: Supported extensions are: tar, zip, bz, bz2, bz3, gz, lz4, xz, lzma, sz, zst, rar, 7z
# (RAR appears here but creation is not allowed)

❯ ouch c -f rar file.txt file.compressed
Do you want to overwrite file.compressed? [y/n/r]
y
[ERROR] Recognised but unsupported format
 - Creating RAR archives is not allowed due to licensing restrictions.

What would help

• In compress, only show formats that can be created.
• In decompress, only show formats that can be extracted (including D-only).
• If you prefer a single list, annotate each format with its capability: C (compress), D (decompress), or C/D.

3) The CLI hint list is out of date vs. actual supported formats

Some formats supported by the tool (and documented in the README) are missing from the CLI’s hint list.

Examples

• br (Brotli) is not shown in the hints but compression succeeds:

❯ ouch c -f INVALID file.txt file.compressed
[ERROR] Failed to parse `--format INVALID`
 - Unsupported extension 'INVALID'

hint: Supported extensions are: tar, zip, bz, bz2, bz3, gz, lz4, xz, lzma, sz, zst, rar, 7z
# 'br' not listed above

❯ ouch c -f br file.txt file.compressed
[INFO] Successfully compressed 'file.compressed'

• lz is also missing from the CLI list (README shows it as supported for decompression-only).

---

Why these feel connected

All three issues look like symptoms of there being no single, authoritative “registry” driving:

• the README table,
• CLI help/hints,
• and context-aware format suggestions.

A small restructuring to make formats + capabilities a single source of truth would likely fix everything at once.

Proposed solutions (any one or a mix)

1. Add a dedicated command/flag to list formats

   • ouch formats or ouch list-formats
   • ouch --list-formats
   • Subcommand-scoped variants: ouch compress --list-formats, ouch decompress --list-formats

2. Annotate capabilities clearly

   Format  Aliases        Compress  Decompress  Notes
   ------  -------------  --------  ----------  -------------------------
   tar     tgz,tbz,...    yes       yes
   rar                    no        yes         creation restricted
   br                      yes       yes
   lz                      no        yes
   

   Optional: include per-format notes (streaming limits, parallelism, license constraints).

3. Make hints context-aware

   • In compress, list only compressible formats (plus aliases).
   • In decompress, list only extractable formats (plus aliases).
   • Ensure alias list is typo-free (tlzma).

4. Generate all lists from a single internal registry

   • Use the same data to render README, CLI help/hints, shell completions, and machine-readable output (e.g., --list-formats=json) to avoid drift.

5. Optional niceties

   • Provide shell completion for --format based on that registry.
   • Add ouch help formats describing chaining rules and examples.

Environment

• ouch version: 0.6.1
• OS: macOS 15.6.1
• Shell: zsh 5.9 (arm64-apple-darwin24.0)
• Install method: Homebrew

Thanks

Thanks for considering these UX improvements! A small change here would make discovery smoother and prevent confusion, especially around formats that are decompression-only or restricted for creation.