Skip to content

The command line

This page walks through the commands by task. The CLI reference lists every flag, generated from verlato --help. Run every command from inside the repository; JSON goes to stdout, and diagnostics and progress go to stderr.

verlato --help

Find what changed

verlato scan --from-latest-tag            # change items not in state yet (JSON array)
verlato reconcile --from-latest-tag       # unpublished items in the range, with a count
verlato generate --from-latest-tag        # detect items and save the new ones to state

scan and reconcile never change anything; generate saves new items to .verlato_state.json. Items already in state are recognised by checksum and never duplicated. All three accept the range options and the model options below.

Draft release notes

verlato draft preview --from-latest-tag --version v1.1.0    # GitHub release notes (Markdown)
verlato draft json --from-latest-tag --version v1.1.0       # the full draft document (JSON)

--version sets the release heading (default Unreleased). --include-confidence and --include-provenance add each item's confidence score, PR and commits to the rendered Markdown. Hidden items are left out of the Markdown but stay in the JSON. The JSON shape is described in Output formats.

Without a model, each entry is a release-note sentence written from the title and the semantic review:

### Changed
- Big change across areas (frontend). Changed the signature of `render` (possible breaking change) (PR #12).
- Updated app helpers. Removed `gone` (possible breaking change); added optional parameters to `greet`; added `fresh`.

See Summaries for how the sentence is written, and summary_style to get the diagnostic evidence summary instead.

To render notes from the items saved in state, rather than a range, use verlato render --format changelog|github-release --version v1.1.0.

Review items

verlato draft review --from-latest-tag --id ci_972e95f9aba2 --status accepted --reviewer alice
verlato draft review --from-latest-tag --id ci_972e95f9aba2 --summary "Export a board as CSV."
verlato draft review --from-latest-tag --id ci_6dfa7357c7f6 --status hidden

--status takes needs-review, ready, accepted, edited or hidden. Saving a --summary marks the item edited (unless you also pass a status) and keeps the original generated summary for reference. Decisions are saved in state and apply to every later run over a range containing the item.

Apply notes to files

verlato draft apply --from-latest-tag --version v1.1.0                          # CHANGELOG.md
verlato draft apply --from-latest-tag --version v1.1.0 --target github-release  # .github/release.md
verlato draft apply --from-latest-tag --version v1.1.0 --file docs/releases/v1.1.0.md

The answer says which file was written and whether it was created or updated. Configure the target paths in verlato.json.

Record a release

git tag -a v1.1.0 -m v1.1.0
verlato generate --base v1.0.0 --head v1.1.0
verlato state mark-published --version v1.1.0 --all-unpublished    # or --ids ci_... ci_...

After this, --from-latest-published starts at v1.1.0, and the items carry published_in: v1.1.0. Other state commands:

verlato state show                     # the saved state as JSON
verlato state clear-working            # drop unpublished items (and their feedback); keep history
verlato state clear-suggestion-cache   # delete the model suggestion cache

Improve wording with a model

These commands need a model provider; the default is a local Ollama model.

# Look before you change anything: suggestions for every visible item, as JSON.
verlato draft suggest --from-latest-tag --all-visible --preview

# Apply the suggestion for one item (saved as its summary, with provenance).
verlato draft suggest --from-latest-tag --id ci_715c52ad2c02 --reviewer alice

# The exact prompt, evidence and audit record a suggestion would send; calls no model.
verlato draft prompt --from-latest-tag --id ci_715c52ad2c02

# The planned requests without calling the provider.
verlato draft suggest --from-latest-tag --all-visible --preflight

Useful options: --count (up to 5 suggestions per item), --tone release-note|concise|technical|customer-facing, --strategy auto|single|paired|full-diff-json|tool-retrieval, --parallelism, --batch-size, --suggest-model (a smaller model just for suggestions), --prompt-profile, --no-cache / --refresh-cache, and --trace-suggestions (diagnostics on stderr). Strategies are explained in Models and providers and the wording controls in Writing style and vocabulary.

Model options shared by most commands

Option Effect
--model-provider <name> provider for this run (stub, mock, ollama, litellm, plugin, github-copilot, codex-cli, claude-code)
--privacy <mode> metadata-only, local-summary-then-ai or trusted-provider-patch (Privacy modes)
--allow-remote-patches allow trusted-provider-patch for a remote provider
--infer-commit-intents / --no-infer-commit-intents turn commit intent inference on or off for this run
--diff-engine intentumdiff\|git the evidence engine (a global option, accepted anywhere)

Conventional Commit messages

Draft a full Conventional Commit message for an existing commit, from its diff:

verlato commit conventional --base v1.0.0 --sha 249231a
{
  "header": "chore(general): update commit diff",
  "message": "chore(general): update commit diff\n\n- Updated files according to the commit-scoped diff evidence.",
  "type": "chore",
  "scope": "general",
  "breaking": false,
  "confidence": 0.84,
  "privacy": { "mode": "metadata-only", "raw_patch_chars_sent": 0 },
  "...": "..."
}

(That draft is from the deterministic mock provider; a real model writes a real description.) By default the model does not see the commit's own message (--evidence-mode diff-only), so a vague wip gets an honest description; pass --evidence-mode subject-hint to include it.

Feedback

Review actions and suggestion outcomes are recorded as feedback events in state. You can also record your own, and learn from them:

verlato feedback record --event useful --item-id ci_715c52ad2c02
verlato feedback export --output feedback.json        # or --format jsonl, --event <name>
verlato feedback recommend                            # prompt and style advice from the aggregates

See Writing style and vocabulary.

Health checks and logs

verlato doctor engine        # is the IntentumDiff engine and its parser bundle available?
verlato doctor ollama        # load, queue and generation timing of a local Ollama model
verlato doctor model         # probe the configured suggestion model with a tiny request
verlato model-logs export --file model-debug.jsonl --output model-export.json

See Troubleshooting and Model telemetry.

Long-running servers

verlato serve      # the MCP server on stdio, for MCP clients (same as verlato-mcp)
verlato service    # the JSON-lines editor service on stdio, used by the VS Code extension

See The MCP server and Service and MCP protocol.

Exit codes

0 on success, 1 when a command fails (the reason is on stderr), and 2 for usage errors such as an unknown command or a missing required option.