From 9ea6408416003ca506a1bb4c842fec0b7aaa5b6c Mon Sep 17 00:00:00 2001 From: Vic Gupta Date: Fri, 30 Oct 2026 20:05:48 -0400 Subject: [PATCH] Help: show task, model and common options in brief help Bare tinyagent and tinyagent --help now show two examples and a Common options block (-t/--task with stdin, -m/--model with providers and its default, -c, --cwd, --resume, --read-only, -o, --json, --check, --update, -V) before the subcommands. --help --verbose is unchanged. The brief-help line cap is raised from 15 to 40, and a new test checks the essentials appear and that every flag they name exists. --- README.md | 4 ++-- cmd/tinyagent/help.go | 34 +++++++++++++++++++++++++++++++--- cmd/tinyagent/help_test.go | 31 +++++++++++++++++++++++++++++-- docs/subcommands.md | 2 +- 4 files changed, 63 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 71b650c..0264a19 100644 --- a/README.md +++ b/README.md @@ -120,7 +120,7 @@ tinyagent --read-only --cwd ~/src/project -t "Review error handling in pkg/api" cat review-task.md | tinyagent --read-only -t - -o review.json ``` -Run `tinyagent --help` (or plain `tinyagent` at a terminal) for the overview and `tinyagent --help --verbose` for every flag. Subcommands are shortcuts for common flags: `tinyagent sandbox`, `tinyagent memory list`, `tinyagent ratchet list`, `tinyagent planner --first`, `tinyagent plugins list`, `tinyagent tinygo status` (see [CLI reference](docs/subcommands.md)); each one alone, such as `tinyagent sandbox`, prints its help. +Run `tinyagent --help` (or plain `tinyagent` at a terminal) for the overview: usage, two examples, the common options (`-t/--task`, including `-t -` for stdin; `-m/--model` with its providers and default; `-c`, `--cwd`, `--resume`, `--read-only`, `-o`, `--json`, `--check`, `--update`, `-V`) and the subcommands, and `tinyagent --help --verbose` for every flag. Subcommands are shortcuts for common flags: `tinyagent sandbox`, `tinyagent memory list`, `tinyagent ratchet list`, `tinyagent planner --first`, `tinyagent plugins list`, `tinyagent tinygo status` (see [CLI reference](docs/subcommands.md)); each one alone, such as `tinyagent sandbox`, prints its help. ## Features @@ -133,7 +133,7 @@ Run `tinyagent --help` (or plain `tinyagent` at a terminal) for the overview and - A task planner that can require a plan before any change. - Run budgets: turn cap, cost limit and token limit (`--token-limit`), with an 80% warning to the model; delegates, workers and `--attempts` share the budget, and a run that hits it can be resumed. - Verify before stop (`--verify-on-stop`): a run that changed files isn't accepted until a test or build command passes; otherwise it is marked unverified. Optional computational checks (`--verify-check`, e.g. lint, type check, tests) run in order, cheapest first, before the run may finish; see [Computational checks](docs/verify.md#computational-checks). An optional inferential review (`--verify-review`) runs last, once every check passes, and reports the model's findings; see [Inferential review](docs/verify.md#inferential-review). -- Help everywhere: `tinyagent` or `tinyagent ` alone at a terminal prints help; `--help --verbose` lists every flag by section. +- Help everywhere: `tinyagent` or `tinyagent ` alone at a terminal prints help (the top-level one shows how to pass the task, pick the model and the common options); `--help --verbose` lists every flag by section. - `tinyagent --update`: checksum-verified self-update with step-by-step progress and a `#` download bar. - Undo for file edits, workspace rewind, resume and follow-up runs. - Sandboxed commands with a network allowlist, permission rules, hooks, untrusted-content lockdown and file-access rules. diff --git a/cmd/tinyagent/help.go b/cmd/tinyagent/help.go index aa7bf53..23854af 100644 --- a/cmd/tinyagent/help.go +++ b/cmd/tinyagent/help.go @@ -23,16 +23,44 @@ tinyagent --help --verbose for every flag, or see docs/subcommands.md. // helpBrief is the default --help output: usage, one sentence, every // subcommand with a one-line description (built from subcommands, so none // can be left out), and pointers to the detailed views. -var helpBrief = helpHeader + "\n" + helpFooter +var helpBrief = helpIntro + "\n" + helpEssentials + helpSubcommands() + "\n" + helpFooter + +// helpEssentials is the brief help's Examples and Common options: how to +// pass the task, pick the model and provider, and the most-used flags. +// TestBriefHelpShowsEssentials checks each flag named here exists. +var helpEssentials = `Examples: + tinyagent -t "fix the failing test in ./pkg" + git diff | tinyagent -t - -m anthropic/claude-sonnet-4-5 --read-only + +Common options: + -t, --task string the task/prompt; "-" reads it from stdin + -m, --model string provider/model: openai, anthropic, openrouter or ollama + (default $AGENT_MODEL, else config model, else ` + builtinModel + `) + -c, --config path YAML config (default: user config if present) + --cwd dir working directory (default .) + --resume path continue or follow up a run saved with -o + --read-only only read files; no edits or commands + -o, --output path write the trajectory JSON + --json write run events as JSONL to stdout + --check show resolved config, model and key status; no model call + --update update to the latest release, showing each step + -V, --version print the version + +` // helpHeader is helpIntro plus the Subcommands section; --help --verbose // prints it before the flag sections and helpFooter after them. var helpHeader = buildHelpHeader() func buildHelpHeader() string { + return helpIntro + "\n" + helpSubcommands() +} + +// helpSubcommands is the Subcommands section: every subcommand with its +// one-line description. +func helpSubcommands() string { var b strings.Builder - b.WriteString(helpIntro) - b.WriteString("\nSubcommands:\n") + b.WriteString("Subcommands:\n") width := 0 for _, s := range subcommands { width = max(width, len(s.name)) diff --git a/cmd/tinyagent/help_test.go b/cmd/tinyagent/help_test.go index 4dd5a74..2383fee 100644 --- a/cmd/tinyagent/help_test.go +++ b/cmd/tinyagent/help_test.go @@ -5,6 +5,7 @@ import ( "fmt" "os" "reflect" + "regexp" "sort" "strings" "testing" @@ -21,8 +22,8 @@ func TestDefaultHelpIsBrief(t *testing.T) { t.Fatalf("%v exit = %d", args, code) } lines := strings.Split(strings.TrimSuffix(got, "\n"), "\n") - if len(lines) > 15 { - t.Errorf("%v: %d lines, want <= 15:\n%s", args, len(lines), got) + if len(lines) > 40 { + t.Errorf("%v: %d lines, want <= 40:\n%s", args, len(lines), got) } for _, l := range lines { if len(l) > helpWidth { @@ -38,6 +39,32 @@ func TestDefaultHelpIsBrief(t *testing.T) { } } +// TestBriefHelpShowsEssentials checks the brief help shows how to pass the +// task (including stdin), the model/provider and its default, and the +// common options, and that every flag it names is a real flag. +func TestBriefHelpShowsEssentials(t *testing.T) { + _, got, _ := runWith(t, "--help") + for _, want := range []string{ + "Examples:\n", "Common options:\n", "-t, --task", `"-" reads it from stdin`, + "-m, --model", "openai, anthropic, openrouter or ollama", "$AGENT_MODEL", builtinModel, + "-c, --config", "--cwd", "--resume", "--read-only", "-o, --output", "--json", + "--check", "--update", "-V, --version", + } { + if !strings.Contains(got, want) { + t.Errorf("brief help lacks %q:\n%s", want, got) + } + } + if strings.Index(got, "Common options:") > strings.Index(got, "Subcommands:") { + t.Errorf("want Common options before Subcommands:\n%s", got) + } + fs := newFlagSet(&options{}) + for _, name := range regexp.MustCompile(`(?:^|[\s|(/])--?([a-zA-Z][a-z-]*)`).FindAllStringSubmatch(helpEssentials, -1) { + if fs.Lookup(name[1]) == nil { + t.Errorf("brief help names unknown flag -%s", name[1]) + } + } +} + // TestHelpListsEverySubcommand checks --help names every registered // subcommand (including tinygo) on its own line with a description, and no // subcommand that doesn't exist. diff --git a/docs/subcommands.md b/docs/subcommands.md index 27b8f11..bbc5555 100644 --- a/docs/subcommands.md +++ b/docs/subcommands.md @@ -23,7 +23,7 @@ Six subcommands are shortcuts for existing flags. They rewrite the command line - Any other flag (`-t`, `-m`, `--cwd`, ...) can follow. `--` followed by words is the task: `tinyagent planner --first -- fix the bug`. - The first word counts as a subcommand only when it is exactly the name and is alone or followed by an option, `--`, a known action or `help`. So `tinyagent memory leaks in parser` is not a subcommand; it fails as before with "pass the task with -t". To start a task with one of these words, use `-t "memory ..."`. - An unknown option exits 2 with `unknown option --x (see tinyagent --help)`. -- Help: `tinyagent --help`, `-h`, `tinyagent help` or `tinyagent help `. A bare `tinyagent ` with nothing after it prints the same help. For `ratchet`, `plugins` and `tinygo` that's always so; for `sandbox`, `memory` and `planner` it's so at an interactive terminal, and with stdin piped or redirected they still run with their flags (so without `-t` they exit 2 with `--task is required`, as before). Plain `tinyagent --help` (or `tinyagent` with no arguments at a terminal; with stdin piped and no arguments it still exits 2 with `--task is required`) shows the usage line and every subcommand (`sandbox`, `memory`, `ratchet`, `planner`, `plugins`, `tinygo`) with a one-line description; `tinyagent --help --verbose` lists every flag, grouped into sections (task, model and provider, run control, verify before stop, attempts, review, output and logging, sandbox and permissions, context and tools, project rules (ratchet), memory and planner, plugins and TinyGo, rewind, workflow and eval, setup and info). +- Help: `tinyagent --help`, `-h`, `tinyagent help` or `tinyagent help `. A bare `tinyagent ` with nothing after it prints the same help. For `ratchet`, `plugins` and `tinygo` that's always so; for `sandbox`, `memory` and `planner` it's so at an interactive terminal, and with stdin piped or redirected they still run with their flags (so without `-t` they exit 2 with `--task is required`, as before). Plain `tinyagent --help` (or `tinyagent` with no arguments at a terminal; with stdin piped and no arguments it still exits 2 with `--task is required`) shows the usage line, two examples, a Common options block (`-t/--task` with `-t -` for stdin, `-m/--model` with the providers `openai`, `anthropic`, `openrouter`, `ollama` and its default — `$AGENT_MODEL`, else the config's model, else `openai/gpt-4o` — then `-c/--config`, `--cwd`, `--resume`, `--read-only`, `-o/--output`, `--json`, `--check`, `--update`, `-V/--version`), and every subcommand (`sandbox`, `memory`, `ratchet`, `planner`, `plugins`, `tinygo`) with a one-line description; `tinyagent --help --verbose` lists every flag, grouped into sections (task, model and provider, run control, verify before stop, attempts, review, output and logging, sandbox and permissions, context and tools, project rules (ratchet), memory and planner, plugins and TinyGo, rewind, workflow and eval, setup and info). - `ratchet` records [project rules](ratchet.md) learned from agent failures. - `plugins rollback` and `plugins prune` manage the plugin module version store; see [Plugins](plugins.md#webassembly-plugin-modules). - `tinygo` manages the TinyGo compiler used to build Go plugin modules. **TinyGo is an external dependency, not part of tinyagent:** it is never embedded in the tinyagent binary or repository. tinyagent downloads a pinned TinyGo release on first use (or with `tinygo install`), verifies its SHA-256 checksum and caches it locally; `tinygo update` moves to the version pinned in the current build.