Skip to content

docs(cli): populate --help text for every command and flag across all CLI modules - #55

Merged
aarambh-darshan merged 2 commits into
mainfrom
docs/cli-help-text
Aug 17, 2026
Merged

docs(cli): populate --help text for every command and flag across all CLI modules#55
aarambh-darshan merged 2 commits into
mainfrom
docs/cli-help-text

Conversation

@aarambh-darshan

Copy link
Copy Markdown
Member

Summary

Before this PR, running aarambh-studio --help listed 7 of 10 subcommands
with blank descriptions
(train, infer, eval, quantise, convert,
distill, finetune, selflearn), and most flags across the CLI showed no
description at all
in their --help output. The only commands with help text
were agent (added in Phase 47) and serve, and the Phase 46 finetune rlaif
subcommand.

This PR adds human-readable help = "..." text and /// doc comments (which
clap renders as about) to every command struct and every flag across
all 9 CLI command modules, so <command> --help is now self-explanatory β€” a new
user can run any --help and understand what the command does and what each
flag means, without reading separate docs.

No behavior, flag names, types, defaults, or logic changed. This is a
documentation/UX-only change to the clap definitions.

What changed

All edits are under aarambh-studio/aarambh-studio/src/cmd/. Each file got a
/// doc comment on its command struct (rendered as the command about) and a
help = "..." string on every #[arg(...)]:

File What was added
cmd/train.rs TrainArgs about + --config help
cmd/infer.rs InferArgs about + help on all ~40 flags (config, model, tokenizer, image/video/document/audio, pages, dpi, frames, frame-sampling, prompt, sampling, thinking, speculative, tools, safety, self-learn, forgetting, best-of-N, selection, ground-truth, …)
cmd/eval.rs EvalArgs about + help on all ~20 flags (tasks, limit, kv-cache-report, forgetting-*, …)
cmd/quantise.rs QuantiseArgs about + help on all 8 flags (format, output, calibration-samples, group-size, …)
cmd/convert.rs ConvertArgs about + help on all 10 flags (from/to layouts, tokenizer, …)
cmd/serve.rs help on all 15 flags (host, port, batch, prefill, api-key-env, cors-origin, …) β€” about was already present
cmd/distill.rs DistillArgs about + help on every flag of TrainArgs/PrepareOfflineArgs/TrainOfflineArgs/EvaluateArgs
cmd/finetune.rs FinetuneArgs about + doc comments on all 18 FinetuneCommand variants + help on every flag of FinetuneRunArgs/MergeArgs/GrpoArgs/DpoArgs/VlmFinetuneArgs (Phase 46 rlaif help left as-is)
cmd/selflearn.rs SelflearnArgs about + doc comments on all 6 SelflearnCommand variants + help on every flag of StartArgs/SelflearnRunArgs/StatsArgs/ResetArgs/ForgettingReportArgs/ForgettingArgs

cmd/agent.rs was already complete (Phase 47) β€” verified and left untouched.
main.rs was not modified: clap already inherits each subcommand's about
from the wrapped Args struct's doc comment (the existing pattern), so
populating the Args struct doc comments in cmd/*.rs is sufficient to surface
every subcommand in the top-level --help list.

The verbatim --help reference snapshot at docs/cli-commands-raw-help.txt was
regenerated from the rebuilt binary (1130 β†’ 1946 lines, reflecting the newly
populated descriptions).

Style followed (matches the existing agent command)

  • One short, clear sentence per flag, no trailing period in help= (clap appends [default: ...] automatically β€” not duplicated).
  • Enum-like flags list allowed values, e.g. Thinking budget: none, low, medium, high, or max.
  • Repeatable flags note (repeatable).
  • Phase references kept where relevant (e.g. best-of-n β†’ "(Phase 45)").
  • No TODO/FIXME/HACK/todo!()/unimplemented!() markers added (release-audit clean).

Proof it renders

Top-level --help (every subcommand now described; previously 7 were blank):

Commands:
  agent      Run a bounded caller-executed long-horizon tool-use chain
  train      Train a model checkpoint from a TOML training configuration
  infer      Generate text, multimodal, tool-use, speculative, best-of-N, or self-learning completions from a trained checkpoint
  eval       Evaluate a checkpoint on capability, forgetting, or KV-cache probes
  quantise   Quantise a trained checkpoint into a smaller GGUF format
  convert    Convert checkpoints between HF SafeTensors and GGUF, or expand vocabularies
  distill    Distil a smaller student model from a frozen local or dataset teacher
  finetune   Fine-tune adapters with SFT, DoRA, GRPO, DPO, RLAIF, or merge
  selflearn  Self-learning loop operator: start, flush, replay, stats, or reset
  serve      Start the local OpenAI-compatible inference server

train --help (was blank):

Train a model checkpoint from a TOML training configuration
Usage: aarambh-studio train --config <CONFIG>
Options:
      --config <CONFIG>  Training/model TOML configuration path

infer --help now describes every one of its ~40 flags, e.g.:

      --video <VIDEO>          Video file path for temporal video inference (mutually exclusive with --image)
      --thinking <THINKING>   Thinking budget: none, low, medium, high, or max [default: none]
      --best-of-n <BEST_OF_N> Generate N independent candidates and select the best (Phase 45)

Verification

  • cargo fmt --all --check β€” clean
  • cargo check -p aarambh-studio --all-targets --locked β€” passes
  • cargo clippy -p aarambh-studio --all-targets --locked -- -D warnings -D clippy::undocumented_unsafe_blocks β€” zero warnings
  • Rebuilt the debug binary and re-captured --help for every command and subcommand; previously-blank descriptions are now populated.
  • No new dependencies; no flag names, types, defaults, or logic changed.

Scope/non-goals

  • This PR is docs/UX only β€” it does not change any runtime behavior.
  • The Phase 47 sandboxed-execution flags (--execute-tools, --allow-tool, --exec-*) already had help text and are unchanged here.
  • The Phase 46 finetune rlaif help text was already complete and is unchanged.

Related

  • Builds on Phase 47 (feat: Phase 47 β€” sandboxed tool execution) which established the help-text style in cmd/agent.rs.
  • Reference snapshot: docs/cli-commands-raw-help.txt (regenerated for 4.0.0-alpha.7).

… html-tag lint

Wrap the forgetting curves store path in an inline code span in infer.rs and selflearn.rs so rustdoc's invalid_html_tags lint stops treating <state-dir> as an unclosed HTML tag; cargo doc -D warnings now passes.
@aarambh-darshan
aarambh-darshan merged commit 21f7ef4 into main Aug 17, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant