Summary
The --help output for every opentaint command lacks usage examples, and the command descriptions are inconsistent in style, structure, and level of detail. Users and AI agents reaching for --help should be able to understand what a command does, how to invoke it, and what a realistic workflow looks like — without reading docs or guessing at flag combinations.
Problem
Today the help output has several friction points that make the CLI harder to learn and use:
-
No usage examples on any command. None of the seven subcommands (scan, compile, project, summary, pull, update, prune) show a dedicated Examples: section in their help output. The project command has one example, but it appears inline in the description paragraph rather than in a separate examples section. Every other command has zero examples. A user running opentaint scan --help gets a list of flags but no concrete invocation to start from.
-
Inconsistent description structure. Some commands show their positional arguments in an Arguments: block in the description. Others use bullet-point lists. The project command mixes description prose, argument docs, and examples all in one block. There is no shared convention, so the help output feels ad hoc across commands.
-
Short descriptions vary in quality and length. summary says "Print summary of your sarif" — terse and unclear about what a SARIF file is or why you would use the command. project has a 20-word Short that is too long to scan in the Available Commands list. pull says "Download autobuilder, analyzer binaries, rules and Java runtime" — accurate but reads like an internal inventory rather than a user-facing action.
-
No examples for common flag combinations. Commands like scan and summary have multiple flags that interact (--severity, --ruleset, --output, --timeout, --show-findings, --group-by, etc.), but users have no guidance on which combinations are useful or how to compose them for real tasks.
Summary
The
--helpoutput for everyopentaintcommand lacks usage examples, and the command descriptions are inconsistent in style, structure, and level of detail. Users and AI agents reaching for--helpshould be able to understand what a command does, how to invoke it, and what a realistic workflow looks like — without reading docs or guessing at flag combinations.Problem
Today the help output has several friction points that make the CLI harder to learn and use:
No usage examples on any command. None of the seven subcommands (
scan,compile,project,summary,pull,update,prune) show a dedicatedExamples:section in their help output. Theprojectcommand has one example, but it appears inline in the description paragraph rather than in a separate examples section. Every other command has zero examples. A user runningopentaint scan --helpgets a list of flags but no concrete invocation to start from.Inconsistent description structure. Some commands show their positional arguments in an
Arguments:block in the description. Others use bullet-point lists. Theprojectcommand mixes description prose, argument docs, and examples all in one block. There is no shared convention, so the help output feels ad hoc across commands.Short descriptions vary in quality and length.
summarysays"Print summary of your sarif"— terse and unclear about what a SARIF file is or why you would use the command.projecthas a 20-wordShortthat is too long to scan in theAvailable Commandslist.pullsays"Download autobuilder, analyzer binaries, rules and Java runtime"— accurate but reads like an internal inventory rather than a user-facing action.No examples for common flag combinations. Commands like
scanandsummaryhave multiple flags that interact (--severity,--ruleset,--output,--timeout,--show-findings,--group-by, etc.), but users have no guidance on which combinations are useful or how to compose them for real tasks.