Setup command

Home / Commands / setup

commitbrief setup

Interactive provider + API key + model wizard.

Synopsis

commitbrief setup [--local]
commitbrief setup --alias[=<name>]

setup is the one command users run before they have a repo configured. It tolerates being invoked outside a git repo (when --local is not passed) so a fresh machine can be set up before cloning anything.

With --alias it does something different: it skips the provider wizard and installs a shell alias for commitbrief instead — see Shell alias below.

Flow

1. Pick a provider. Choose from the registered list. Built-in options:
   • Anthropic (Claude) — needs API key
   • OpenAI (GPT) — needs API key
   • Google Gemini — needs API key
   • Ollama (local) — needs base URL, no API key
2. API key. For providers with NeedsKey: true, the wizard prompts for the key with password masking (huh.EchoModePassword). A link to the provider's console (Anthropic / OpenAI / AI Studio) is shown in the help line. If the target config already has a key for the chosen provider, the prompt instead invites you to leave it blank to keep the existing key (and skips the not-empty validation), so re-running setup only to switch provider/model never forces a key re-entry.
3. Base URL. For Ollama only, the wizard asks for the base URL, defaulting to http://localhost:11434.
4. Model. For Anthropic / OpenAI / Gemini the wizard offers the static model list (see each Provider page). For Ollama it queries <base-url>/api/tags and lists the models you have pulled locally; if discovery fails (Ollama not running, wrong URL, etc.) it falls back to a free-text input.
5. Connection test. A fast ping against the chosen provider with the credentials entered. Test failure surfaces the provider error and aborts the wizard without persisting anything.
6. Write config. The resulting config is layered onto the existing file at the target path (user-level or repo-local per --local), preserving API keys for providers other than the one you just configured. First-time runs start from config.Default().

Flags

Flag	Notes
--local	Write to <repo-root>/.commitbrief/config.yml instead of ~/.commitbrief/config.yml. Requires being inside a git repo. The repo-local path is added to the repo's .gitignore on first write. Has no effect together with --alias.
--alias[=<name>]	Skip the wizard and install a shell alias (default cbr) for commitbrief. Bare --alias prompts for the name; --alias=<name> sets it directly. See below.

Shell alias (--alias)

commitbrief setup --alias installs a shell alias so you can type a short name (default cbr) instead of commitbrief. It does not run the provider wizard — it only writes the alias.

commitbrief setup --alias        # prompt: "What would you like to use as the alias? (default: cbr)"
commitbrief setup --alias=cb     # install 'cb' without prompting (good for dotfiles / CI)

When you run bare --alias, you are asked for the name; press Enter to accept the default cbr.

What it writes

The alias expands to the bare commitbrief command (not an absolute path), so it keeps working after an upgrade. The target depends on your shell, which is detected from $SHELL (with an interactive picker fallback; PowerShell is the default on Windows):

Shell	Where	Form
bash	~/.bashrc	alias cbr='commitbrief'
zsh	$ZDOTDIR/.zshrc or ~/.zshrc	alias cbr='commitbrief'
fish	~/.config/fish/config.fish	alias cbr='commitbrief'
PowerShell	$PROFILE	function cbr { commitbrief @args }
cmd.exe	DOSKEY macrofile + AutoRun registry value	cbr=commitbrief $*

For the file-based shells the alias lives inside a managed block:

# >>> commitbrief alias >>>
alias cbr='commitbrief'
# <<< commitbrief alias <<<

Re-running --alias updates that block in place (changing the name removes the old alias) and never touches anything outside the markers, so it is safe to run repeatedly. After it writes, restart your shell or run the printed source command to start using the alias.

Conflicts

The name must be a shell identifier (^[A-Za-z_][A-Za-z0-9_-]*$). If it already shadows a command on your PATH, or is already defined in your startup file, you are warned and asked whether to use it anyway, choose a different name, or cancel. Pass --yes to proceed past a conflict non-interactively; a bare --alias on a non-TTY without --yes errors (pass --alias=<name> instead).

Non-destructive across providers

Re-running setup to add a second provider (or update an existing one) only touches that provider's entry. If you already have providers.anthropic.api_key set and run setup for OpenAI, the Anthropic key stays intact. The active provider field is updated to whatever you picked this round.

Re-running setup for a provider that already has a key lets you leave the key prompt blank to keep it — useful when you only want to change the active provider or model. For a non-interactive path, commitbrief providers use <name> switches the active provider and commitbrief config set providers.<name>.model <model> changes the model, both without touching any API key.

Examples

# First-time setup; writes ~/.commitbrief/config.yml.
commitbrief setup

# Per-repo override; writes <repo>/.commitbrief/config.yml and adds
# the path to .gitignore.
commitbrief setup --local

# Install a shell alias (skips the wizard). Prompts for the name.
commitbrief setup --alias

# Install a specific alias without prompting.
commitbrief setup --alias=cb

See also

• Config command — read / write individual config fields without the interactive wizard.
• Providers command — switch / test / list providers after setup is done.
• Doctor command — verify the new configuration end-to-end.