Getting started

This guide walks through installing the CLI, creating commit.config.ts, and running your first interactive commit.

Install

Add better-commit as a dev dependency:

npm install -D @better-commit/cli

The bc binary is available after install. You can also invoke better-commit directly.

Initialize your config

Run bc init to create a starter commit.config.ts at your repository root:

bc init

Non-interactive mode is available with -q. Add -f to replace an existing config file.

The default template includes conventional commit types and optional AI suggestions:

import {
  aiSuggest,
  conventionalCommits,
  defineConfig,
} from "@better-commit/cli/config";

export default defineConfig({
  plugins: [
    conventionalCommits({
      types: [
        "feat",
        "fix",
        "docs",
        "style",
        "refactor",
        "test",
        "chore",
        "perf",
        "ci",
        "build",
      ],
    }),
    aiSuggest({ provider: "auto" }),
  ],
});

Omit aiSuggest if you want offline-only, manual commits. See Configuration for plugin options.

Verify setup

Run the doctor command to confirm config loading, plugins, and AI providers:

bc doctor

Doctor checks Node version, config discovery, resolved plugins, and available AI providers.

Create your first commit

Run the interactive commit flow:

bc

If you haven't staged any files yet, better-commit will automatically scan your repository and prompt you to stage them interactively. Once staged, the CLI prompts for commit type, scope, and subject based on your configuration rules. With aiSuggest enabled, it will also propose a message from your staged diff.

What you get

After setup, you have:

• One config file — commit.config.ts is the contract for types, scopes, plugins, and AI
• Interactive commits — bc guides you through conventional message format
• Shared validation — bc check uses the same rules as the interactive flow
• Optional AI — suggest messages from staged diffs when aiSuggest is configured
• Git hook support — bc init --hooks installs a Husky prepare-commit-msg hook

Next steps

• Configuration — customize plugins, scopes, and AI
• Commands — full CLI reference
• CI and hooks — enforce rules in pipelines and Git hooks