smart-commit CLI

smart-commit CLI is a shell-first tool for AI-assisted commit review, commit-message generation, optional Git execution, and local reporting.

Use it when you want one repeatable workflow that can run from:

• your terminal
• shell scripts
• Git hooks
• IDE hooks
• external agents

It can:

• inspect staged changes
• run AI review and gate on the result
• generate or validate commit messages
• retry malformed review or commit-message responses with configurable correction passes
• use bundled review skills, including c-code-review, with diff-aware generic fallback
• optionally create a commit
• optionally push the current branch
• persist successful run history
• generate daily, yesterday, weekly, monthly, quarterly, or yearly Markdown work reports

Who This Is For

This tool is a good fit if you want to:

• review staged changes before committing
• standardize commit messages
• run the same workflow locally and in automation
• keep a lightweight history of successful review and commit runs
• generate periodic reports from local pass history

If you are using this for the first time, start with review-only mode and keep Git side effects disabled until you trust the workflow.

What Happens In A Typical Run

At a high level, smart-commit bridge does this:

1. loads config from CLI flags, environment variables, config file, and defaults
2. resolves env:VAR_NAME references such as env:SMART_COMMIT_API_KEY
3. verifies the target --repo path is inside a Git repository
4. reads the staged diff, or auto-stages if your config allows it
5. runs AI review
6. generates or validates the commit message
7. optionally commits and pushes
8. optionally records the successful run into pass history

flowchart TD
  InstallCli[InstallCLI] --> PrepareConfig[PrepareConfig]
  PrepareConfig --> ResolveConfig[RunConfigResolve]
  ResolveConfig --> StageChanges[StageChanges]
  StageChanges --> DryRun[RunBridgeDryRun]
  DryRun --> ReviewOnly[RunReviewOnly]
  ReviewOnly --> FullRun[OptionalFullRun]
  FullRun --> ReportGenerate[OptionalReportGenerate]

Prerequisites

Before you run the CLI, make sure you have:

• Node.js >= 20
• git available in your shell
• a Git repository to operate on
• staged changes for bridge, unless auto-stage is enabled
• an OpenAI-compatible API endpoint, model, and API key for AI-backed commands

Important command requirements:

• smart-commit bridge requires --repo
• smart-commit report generate requires --repo
• smart-commit config resolve does not require --repo
• smart-commit config resolve can validate config structure without a complete connection block
• smart-commit bridge requires a valid connection configuration

Install

Install globally:

npm install -g smart-commit-copilot-cli

Then verify:

smart-commit --help

Or use npx without a global install:

npx smart-commit-copilot-cli --help

If you are working from a repository checkout of this project:

npm install
npm run build
node out/cli.js --help

5-Minute Quick Start

This section is the safest first-use path for a real repository.

1. Export your API key

export SMART_COMMIT_API_KEY="your-api-key"

Why this matters:

• the config examples below use env:SMART_COMMIT_API_KEY
• environment references are resolved before validation
• if the variable is missing, bridge cannot start

2. Create a minimal config file

Create smart-commit.json in your target repository:

{
  "smartCommitCli": {
    "connection": {
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "env:SMART_COMMIT_API_KEY",
      "model": "gpt-5"
    },
    "git": {
      "autoCommit": false,
      "autoPush": false
    }
  }
}

The three connection fields are the most important:

• connection.baseUrl: your OpenAI-compatible API base URL
• connection.apiKey: your API key, usually referenced through env:...
• connection.model: the model name sent to that endpoint

This minimal config is intentionally safe:

• autoCommit=false prevents local commits
• autoPush=false prevents remote pushes

3. Validate the merged config first

smart-commit config resolve --config ./smart-commit.json

Why start here:

• it shows the final merged config after CLI args, env vars, file config, and defaults
• it redacts secrets in output
• it catches validation problems before the CLI touches Git or the network

For a more readable terminal view:

smart-commit config resolve --config ./smart-commit.json --output text

What you should expect:

• a valid merged config
• no missing environment variable errors
• no invalid booleans, regex patterns, or protocol settings

4. Stage a change

bridge works on staged content.

git add -A
git status --short

If nothing is staged and autoStageWhenNothingStaged is disabled, bridge will block.

5. Run a safe preflight

smart-commit bridge --repo . --config ./smart-commit.json --dry-run

Why this step matters:

• it verifies the repo path
• it checks whether the repo is inside Git
• it checks whether staged diff input exists
• it validates that commit-message logic can be resolved
• it confirms the bridge input is ready

What you should expect:

• status: "ready" when the bridge can run
• status: "blocked" when the repo is valid but required input is missing
• status: "error" when config or runtime setup is invalid

For a terminal-friendly version:

smart-commit bridge --repo . --config ./smart-commit.json --dry-run --output text

6. Run review-only mode

smart-commit bridge --repo . --config ./smart-commit.json --no-commit --no-push

This is the recommended first real run because it:

• runs review
• runs commit-message logic
• returns structured output
• avoids Git side effects

What you should expect:

• status: "passed" if the review passes
• status: "blocked" if the review blocks or required input is missing
• status: "error" if execution fails

When the review returns a numeric score, the final pass or block result is determined by comparing that score with review.threshold.

Shortest safe path

If you want the shortest sequence to first success:

1. install smart-commit-copilot-cli
2. export SMART_COMMIT_API_KEY
3. create smart-commit.json
4. run smart-commit config resolve
5. run smart-commit bridge --dry-run
6. run smart-commit bridge --no-commit --no-push

Configuration Examples

Minimal practical config

Use this when you want the smallest useful starting point:

{
  "smartCommitCli": {
    "connection": {
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "env:SMART_COMMIT_API_KEY",
      "model": "gpt-5"
    },
    "git": {
      "autoCommit": false,
      "autoPush": false
    }
  }
}

This gives you a safe review-first setup.

Safer team rollout config

Use this when you want a more realistic team default without enabling automatic commit or push:

{
  "smartCommitCli": {
    "connection": {
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "env:SMART_COMMIT_API_KEY",
      "model": "gpt-5",
      "llmResponseCorrectionRetryCount": 1
    },
    "review": {
      "threshold": 6,
      "language": "zh"
    },
    "git": {
      "autoStageWhenNothingStaged": true,
      "autoCommit": false,
      "autoPush": false
    },
    "passHistory": {
      "enabled": true,
      "writeStage": "review_passed",
      "dirPath": ".smart-commit-cli",
      "maxEntries": 3000
    },
    "output": {
      "format": "json",
      "logLevel": "info"
    }
  }
}

This is usually the best starting point for teams because it:

• keeps the workflow review-first
• allows local history for reporting
• stays safe for hooks and automation

Review skills and correction retries

Built-in review skills are bundled with the CLI. The default code-review skill stays generic, while domain skills such as frontend-code-review, python-code-review, c-code-review, cpp-code-review, and csharp-code-review add domain-focused guidance. These built-in review skills share a lightweight diff classifier: if the staged diff does not match the selected domain, the CLI falls back to generic review rules automatically without changing your configured skill id.

If you set review.skill.path, the CLI keeps the current file-based custom-skill behavior and loads that file as custom prompt input instead of the bundled built-in skill assets.

connection.llmResponseCorrectionRetryCount controls how many extra repair or regeneration attempts the CLI may request when a review result or generated commit message fails protocol, JSON-shape, or language validation. The default is 1, the supported range is 0..5, and network, HTTP, timeout, or provider failures are not retried by this setting.

About the example config in this repo

This repository ships a fuller example at examples/config/smart-commit.json.

That example is useful for learning the whole config surface, but note that it enables:

• git.autoCommit = true
• git.autoPush = true

For first use, do not copy those values blindly. Start with false for both and enable them later only if you want the CLI to own those Git side effects.

Choose The Right Command

Instead of memorizing every command, use this section by intent.

I want to verify my config

smart-commit config resolve --config ./smart-commit.json

Use this when you want to:

• inspect the merged config
• confirm env var resolution
• catch validation issues early

Good to know:

• --config is recommended, not required
• if you omit --config, the CLI uses CLI flags, env vars, and built-in defaults
• config resolve is the safest first command

I want to see whether bridge is ready

smart-commit bridge --repo . --config ./smart-commit.json --dry-run

Use this when you want to:

• validate repo and staged diff readiness
• confirm commit-message logic can resolve
• avoid a real AI review or Git side effects

I want review only, with no commit or push

smart-commit bridge --repo . --config ./smart-commit.json --no-commit --no-push

Use this when you want to:

• review staged changes
• generate or validate a commit message
• integrate with hooks safely
• onboard the CLI without touching Git history

I want a full bridge run

smart-commit bridge --repo . --config ./smart-commit.json

Use this only when your config intentionally allows the desired side effects.

Depending on config, the CLI may:

• review only
• review and create a local commit
• review, commit, and push

I want to generate a report

smart-commit report generate --repo . --config ./smart-commit.json --period weekly

Supported --period values:

• daily
• yesterday
• weekly
• monthly
• quarterly
• yearly

If you omit --period, it defaults to weekly. yesterday always means the previous natural local day.

If passHistory.enabled=true, successful bridge runs are written locally and later summarized into a Markdown report.

Optional AI-enhanced reporting:

smart-commit report generate --repo . --config ./smart-commit.json --period weekly --report-ai

If AI report generation fails, the CLI falls back to local Markdown generation automatically.

I want a pull request summary after a passing review

smart-commit bridge --repo . --config ./smart-commit.json --no-commit --enable-pull-request-summary

When enabled, bridge writes a Markdown PR description after the reviewed action succeeds. It runs after review-only success, after local commit success when --no-push is used, or after push success when auto-push is enabled. Review blocks, dry runs, and commit/push failures do not generate a PR summary.

I want machine-readable schemas

smart-commit schema print --target bridge

Supported schema targets:

• config-file
• config-resolve
• bridge
• report-generate

Examples:

smart-commit schema print --target config-file
smart-commit schema print --target config-resolve
smart-commit schema print --target bridge
smart-commit schema print --target report-generate

Core Commands Reference

Help and version

smart-commit --help
smart-commit help
smart-commit --version
smart-commit version

Resolve config

smart-commit config resolve --config ./smart-commit.json

Bridge preflight

smart-commit bridge --repo . --config ./smart-commit.json --dry-run

Review-only bridge

smart-commit bridge --repo . --config ./smart-commit.json --no-commit --no-push

Full bridge execution

smart-commit bridge --repo . --config ./smart-commit.json

Generate a report

smart-commit report generate --repo . --config ./smart-commit.json --period weekly

Print a schema

smart-commit schema print --target bridge

Output Modes

Default output is machine-facing JSON:

smart-commit bridge --repo . --config ./smart-commit.json

For a human-friendly terminal summary:

smart-commit bridge --repo . --config ./smart-commit.json --output text

Recommended usage:

• use json for hooks, agents, and scripts
• use text for local debugging

For machine integrations, the usual pattern is:

• call smart-commit bridge or smart-commit report generate
• consume stdout as JSON
• branch on schemaVersion, status, and error.code

Exit Codes

These are especially useful in shell scripts, hooks, and automation.

bridge

• 0: success
• 2: blocked
• 3: config error
• 4: runtime error

Typical interpretation:

• 0 means the run completed successfully
• 2 means the change set or review result blocked progress
• 3 means your config or CLI input is invalid
• 4 means runtime execution failed

report generate

• 0: success
• 3: config error
• 4: runtime error

Configuration Rules

Config precedence from high to low:

1. CLI arguments
2. environment variables
3. smartCommitCli in a JSON config file
4. legacy smartCommit.* keys
5. built-in defaults

Special rule:

• values like env:SMART_COMMIT_API_KEY are resolved from the current process environment after merge and before validation

Canonical format:

• smartCommitCli is the recommended long-term format
• legacy smartCommit.* is still accepted for migration

Common CLI Flags

Most practical flags for daily use:

--repo
--config
--output
--base-url
--api-key
--model
--threshold
--llm-response-correction-retry-count
--review-language
--code-review-skill-id
--commit-language
--commit-message-structure
--commit-message
--pass-history-write-stage
--enable-pull-request-summary
--pull-request-summary-language
--pull-request-summary-output-dir
--pull-request-summary-prompt
--no-commit
--no-push
--dry-run

Common reporting flags:

--period
--report-language
--report-output-dir
--report-ai

Common Environment Variables

Most practical ones:

SMART_COMMIT_API_KEY
SMART_COMMIT_BASE_URL
SMART_COMMIT_MODEL
SMART_COMMIT_THRESHOLD
SMART_COMMIT_LLM_RESPONSE_CORRECTION_RETRY_COUNT
SMART_COMMIT_REVIEW_LANGUAGE
SMART_COMMIT_CODE_REVIEW_SKILL_ID
SMART_COMMIT_COMMIT_LANGUAGE
SMART_COMMIT_COMMIT_MESSAGE_STRUCTURE
SMART_COMMIT_AUTO_COMMIT
SMART_COMMIT_AUTO_PUSH
SMART_COMMIT_PASS_HISTORY_WRITE_STAGE
SMART_COMMIT_REPORT_LANGUAGE
SMART_COMMIT_REPORT_OUTPUT_DIR
SMART_COMMIT_ENABLE_PULL_REQUEST_SUMMARY
SMART_COMMIT_PULL_REQUEST_SUMMARY_LANGUAGE
SMART_COMMIT_PULL_REQUEST_SUMMARY_OUTPUT_DIR
SMART_COMMIT_PULL_REQUEST_SUMMARY_PROMPT

Reporting

If passHistory.enabled=true, successful bridge runs are written to local history and can be summarized later:

smart-commit report generate --repo . --config ./smart-commit.json --period weekly

passHistory.writeStage controls the earliest successful stage that can create a record. Once a record exists, later successful stages update the same pass-history entry, so eventType always reflects the furthest successful stage reached by that run.

• review_passed writes as soon as review passes. If that same run later reaches a local commit or push, the existing record is upgraded instead of duplicated.
• commit_completed waits until the local commit succeeds. If a later push succeeds, that same record is upgraded to commit_push_completed.
• commit_push_completed writes only after both the local commit and the push succeed.

If a run never reaches the configured write stage, no pass-history record is written. For example:

• with passHistory.writeStage=commit_completed, a successful local commit is still preserved even if the later push cannot start, fails, or times out
• with passHistory.writeStage=commit_push_completed, those same push failures produce no pass-history record

Stored pass-history eventType values mean:

• review_passed: review passed, and no later success stage was reached
• commit_completed: a local commit succeeded, and no later push success stage was reached
• commit_push_completed: both the local commit and the remote push succeeded

Report summaries use these records to show:

• total successful review passes
• local commit completions
• commit and push completions

Common First-Time Mistakes

connection.apiKey references missing environment variable

Your config contains something like:

"apiKey": "env:SMART_COMMIT_API_KEY"

but the environment variable is not set in the current shell.

Fix:

export SMART_COMMIT_API_KEY="your-api-key"

--repo is required

bridge and report generate require a repository path, or a path inside a Git repository.

Typical fix:

smart-commit bridge --repo . --config ./smart-commit.json --dry-run

No staged diff found

Possible causes:

• nothing is staged
• working tree is clean
• auto-stage is disabled

Try:

git add -A
smart-commit bridge --repo . --config ./smart-commit.json --dry-run

I expected the config file to be auto-loaded

If you omit --config, the CLI does not magically discover every possible file name. It uses CLI flags, environment variables, and built-in defaults.

If you want a specific config file to participate in resolution, pass it explicitly:

smart-commit config resolve --config ./smart-commit.json

I accidentally enabled auto-commit or auto-push too early

If your config or env vars enable git.autoCommit or git.autoPush, bridge may create side effects during a full run.

For first rollout, keep these disabled:

{
  "smartCommitCli": {
    "git": {
      "autoCommit": false,
      "autoPush": false
    }
  }
}

Then use:

smart-commit bridge --repo . --config ./smart-commit.json --no-commit --no-push

Recommended First Rollout

For a new team or repository, use this order:

1. create a minimal or safer team config
2. run smart-commit config resolve
3. run smart-commit bridge --dry-run
4. run smart-commit bridge --no-commit --no-push
5. embed the same review-only command into your hook or automation flow
6. enable pass history
7. add reporting
8. only then consider automatic commit or push

This sequence keeps the first rollout safe while still letting you validate the entire workflow.

Where To Go Deeper

For deeper detail after the first successful run:

• getting started from source: docs/getting-started.md
• configuration details: docs/configuration.md
• integration patterns: docs/integrations.md
• machine-facing contracts: docs/contracts.md