Usage

Generating a commit

cgen with no subcommand generates a message from the staged diff and creates the commit (after review, if enabled). Any arguments that are not cgen flags are forwarded directly to git commit:

cgen                    # generate message and commit
cgen --no-verify        # forwarded: git commit --no-verify
cgen -S                 # forwarded: git commit -S (signed)

Flags

All flags are global: they may appear before or after a subcommand, and the diff/override flags also apply to cgen alter.

Flag	Effect
`-a`, `--all`	Run `git add --update` first, staging tracked modifications and deletions but never untracked files
`--stdout`	Write exactly one final, templated message and a newline; never commit, push, tag, update, review, or track history
`-g N`, `--generate N`	Generate `N` independently validated candidates and choose one (counts above five require confirmation)
`-p TEXT`, `--prompt TEXT`	Add invocation-only content/style guidance without overriding format, locale, or safety rules
`--dry-run`	Generate and print the message without committing (with `alter`: without rewriting)
`--verbose`	Print the final system prompt sent to the LLM (never the diff payload)
`--tag`	Create the next semantic version tag after a successful commit (details)
`--set KEY=VALUE`	Override any setting for this run only, repeatable (details)
`--diff-include GLOB`	Force-include matching files in the LLM diff, repeatable (details)
`--diff-exclude GLOB`	Exclude additional files from the LLM diff this run, repeatable
`--allow-large-diff`	Allow a payload over the `ACR_MAX_DIFF_BYTES` budget
`--allow-sensitive`	Allow a diff flagged by the sensitive-data guard

Always quote globs so your shell does not expand them: --diff-include "*.xml".

--stdout is explicit: redirecting normal output does not enable it. It works for staged generation and cgen --stdout alter <hash>. It conflicts with --dry-run, --verbose, --tag, forwarded commit arguments, and candidate counts other than one. Diagnostics go to stderr, while the sensitive-content and diff-size guards remain active.

When N > 1, --generate N requires an interactive terminal. Regeneration replaces the entire candidate set. After choosing, the normal review menu still appears when review is enabled; otherwise the selected candidate is committed immediately.

Subcommands

`cgen config`

Open the interactive configuration editor. Inside a git repo it asks whether to edit local (.env) or global settings; outside a repo it opens the global config directly. The menu supports searching (/), per-setting descriptions (?), and managing presets and fallback order.

`cgen alter <hash>` / `cgen alter <old> <new>`

Regenerate a past commit's message and rewrite it. With one hash, the message is generated from that commit's own diff. With two hashes, the old..new net diff is used as LLM input and only the <new> commit's message is rewritten. Rewriting already-pushed commits requires explicit confirmation; see safety & workflow controls.

`cgen undo`

Undo the latest commit with a soft reset, keeping its changes staged. Warns before undoing pushed commits and never pushes anything itself.

`cgen history`

Browse commits previously generated by cgen for the current repository (or pick a repository when run outside one). Requires ACR_TRACK_GENERATED_COMMITS=1 (the default). See Commit History.

`cgen preset` / `cgen fallback`

Manage saved provider presets and the fallback order directly — the same UIs available from the cgen config menu.

`cgen model`

Discover live models for the configured provider, search the returned catalog, and save only the selected model locally or globally. The current and provider default models are placed first. If discovery is unsupported, times out, or fails, cgen explains the problem and offers the current/default values plus manual entry. Cancellation writes nothing.

Perplexity uses manual model entry because its current model-list endpoint describes a different API surface. Custom OpenAI-compatible providers support discovery when ACR_API_URL has a recognizable /chat/completions suffix.

`cgen hook install|uninstall|status`

Manage the current repository's prepare-commit-msg integration. Installation uses Git's effective hooks directory, including core.hooksPath and worktrees. If an existing hook is present, cgen backs it up and runs it first. Uninstall only removes a recognized cgen wrapper and restores that exact backup.

The hook generates only for normal commits whose message is still empty apart from Git comments. Existing-hook failures stop the commit; model or generation failures produce a warning and let Git continue.

`cgen prompt`

Print the full LLM system prompt assembled from the current config, without making any LLM call or git operation. Useful for inspecting the effect of ACR_LLM_SYSTEM_PROMPT, gitmoji, locale, and one-liner settings.

`cgen update`

Update cgen to the latest release, using the install method that produced the running binary. See Updating.