smart-commit CLI

smart-commit CLI is a shell-first tool for AI-assisted commit review, commit-message generation, optional Git execution, staged change summaries, PR/MR creation, 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
• review existing GitHub pull requests or GitLab merge requests by URL
• list and batch-review your related open pull requests or merge requests
• 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
• generate staged change summaries after successful review, commit, or push flows
• auto-create GitHub PRs or GitLab MRs after a successful push when configured
• create or dry-run PR/MR content through standalone pull-request create
• review existing PR/MR URLs through standalone pull-request review (single URL or comma-separated multi-URL)
• list your related open PRs/MRs through my-pull-request list
• serially review your related open PRs/MRs through my-pull-request batch-review
• persist successful run history in pass history
• generate local or AI-enhanced daily, yesterday, weekly, last-week, monthly, last-month, quarterly, last-quarter, 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
• automate review-to-PR/MR flows from the CLI, hooks, or agents
• generate staged-change or PR/MR-ready summaries without opening another tool
• keep a lightweight pass history for successful automation 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. Enable commit, push, staged summaries, and PR/MR creation gradually after you trust the workflow.

What Happens In A Typical Run

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

1. resolves config and env:VAR_NAME references
2. verifies --repo and reads the staged diff, auto-staging only if configured
3. generates or validates the commit message, unless --review-only is used
4. runs AI review and applies the score threshold
5. optionally creates a local commit, pushes, writes a staged change summary, and creates a PR/MR
6. optionally records the furthest successful stage into pass history

| Step | When it runs | What it does | Output / side effect | | --- | --- | --- | --- | | Resolve config | Every bridge run | Merges CLI flags, environment variables, config file values, and defaults; resolves env:... references. | Validated runtime config with secrets redacted from output. | | Prepare Git input | Every bridge run | Verifies --repo is inside a Git repository and reads the staged diff. If the index is empty and git.autoStageWhenNothingStaged=true, it can run git add -A. | A staged diff snapshot for review and commit-message generation. | | Commit message | Main bridge workflow only | Uses commitMessage.input, generates a message, or refines a draft depending on config. Validation can enforce structure, protocol, ticket IDs, and regex rules. --review-only skips this step and uses any provided commit message only as review context. | Final commit message, review-only context, or a blocked result before review. | | AI review | Every non-dry-run bridge execution | Reviews the staged diff and compares the final score with review.threshold. | passed, blocked, or error bridge output. | | Commit | Only when review passes and git.autoCommit=true | Creates a local Git commit with the final commit message. | New local commit. | | Push | Only when commit succeeds and git.autoPush=true | Pushes the current branch to its configured upstream. | Remote branch update, or a push-phase runtime error. | | Staged change summary | Only after a successful review-only, commit-only, or push run when stagedChangeSummary.enabled=true | Writes a Markdown summary for the reviewed staged change. | Markdown file under the configured summary directory. | | PR/MR auto-create | Only after a successful push when pullRequestCreation.autoCreateAfterPush=true | Creates or detects an existing GitHub pull request or GitLab merge request. | pullRequestCreation details in bridge JSON output. | | Pass history | Only when passHistory.enabled=true and the configured passHistory.writeStage is reached | Records or upgrades the successful run to the furthest completed stage. | Local pass-history record for later reporting. |

Optional follow-up commands:

smart-commit commit-message generate --repo . --config ./smart-commit.json
smart-commit pull-request create --repo . --config ./smart-commit.json --pull-request-creation-target-branch main --dry-run
smart-commit pull-request create --repo . --config ./smart-commit.json --pull-request-creation-target-branch main
smart-commit pull-request review https://github.com/org/repo/pull/123 --config ./smart-commit.json --dry-run
smart-commit pull-request review https://github.com/org/repo/pull/123,https://github.com/org/repo/pull/456 --config ./smart-commit.json
smart-commit my-pull-request list --config ./smart-commit.json
smart-commit my-pull-request batch-review --config ./smart-commit.json
smart-commit report generate --repo . --config ./smart-commit.json --period weekly
smart-commit report generate --repo . --config ./smart-commit.json --period custom --start-date 2026-04-01 --end-date 2026-04-09

smart-commit commit-message generate resolves only the commit-message portion of the workflow. smart-commit pull-request create is an independent PR/MR command. smart-commit pull-request review reviews one or more existing PR/MR URLs (comma-separated) and can publish comments, approve, or merge based on config. smart-commit my-pull-request list fetches your related open PRs/MRs. smart-commit my-pull-request batch-review lists then serially reviews them. smart-commit report generate summarizes existing pass-history records; it is not part of every bridge run.

For PR/MR commands, set pullRequest.authToken in the config file (recommended: "authToken": "env:SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN") or export SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN. Prefer that over passing --pull-request-auth-token on the command line.

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 LLM API endpoint, model, and API key for AI-backed commands (OpenAI-compatible, Anthropic-compatible, or Cursor Agent depending on connection.llmProvider)

Important command requirements:

• smart-commit bridge requires --repo
• smart-commit commit-message generate requires --repo
• smart-commit report generate requires --repo
• smart-commit pull-request review requires a pull request or merge request URL (comma-separated for multi-URL review)
• smart-commit my-pull-request list requires pullRequest.authToken but not an LLM connection
• smart-commit my-pull-request batch-review requires pullRequest.authToken and a valid LLM connection
• 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.llmProvider: openaiCompatible (default), anthropicCompatible, or cursorAgent
• connection.baseUrl: API base URL for the selected provider (see configuration guide for per-provider meaning)
• 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 --review-only

This is the recommended first real run because it:

• runs review
• skips commit-message generation and validation
• 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 --review-only

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",
      "llmProvider": "openaiCompatible",
      "llmResponseCorrectionRetryCount": 3
    },
    "review": {
      "threshold": 6,
      "language": "zh-cn"
    },
    "git": {
      "autoStageWhenNothingStaged": true,
      "autoCommit": false,
      "autoPush": false
    },
    "passHistory": {
      "enabled": true,
      "writeStage": "review_passed",
      "outputDirPath": ".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 3, the supported range is 0..10, and network, HTTP, timeout, or provider failures are not retried by this setting.

Full Configuration Example

This example shows the complete smartCommitCli config surface in one place.

It is useful for learning all available config fields, 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.

{
  "smartCommitCli": {
    "connection": {
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "env:SMART_COMMIT_API_KEY",
      "model": "gpt-5",
      "llmProvider": "openaiCompatible",
      "extraHeaders": {
        "X-Client": "smart-commit-cli"
      },
      "requestTimeoutMs": 1000000,
      "llmResponseCorrectionRetryCount": 3
    },
    "review": {
      "threshold": 6,
      "language": "zh-cn",
      "maxDiffChars": 100000,
      "skill": {
        "id": "code-review",
        "path": "",
        "promptTuning": "Ignore findings that only complain about the project's required logging wrapper."
      }
    },
    "commitMessage": {
      "input": "",
      "language": "zh-cn",
      "maxDiffChars": 150000,
      "structure": "subjectOnly",
      "scope": "auto",
      "autoGenerate": true,
      "hybridGenerate": false,
      "skill": {
        "id": "conventional",
        "path": "",
        "promptTuning": "Prefer the feat type for user-visible behavior changes when it still matches the staged diff."
      },
      "validation": {
        "protocol": "none",
        "pattern": "",
        "extractTicketIdFromBranch": true,
        "requireTicketIdInMessage": false
      }
    },
    "git": {
      "autoStageWhenNothingStaged": true,
      "autoCommit": true,
      "autoPush": true,
      "pushTimeoutMs": 180000
    },
    "passHistory": {
      "enabled": true,
      "writeStage": "review_passed",
      "outputDirPath": ".smart-commit-cli",
      "maxEntries": 3000
    },
    "reporting": {
      "language": "zh-cn",
      "weekStartsOn": "monday",
      "outputDirPath": ".smart-commit-cli/reports",
      "maxInputChars": 200000,
      "prompt": "",
      "ai": {
        "enabled": false
      }
    },
    "stagedChangeSummary": {
      "enabled": false,
      "language": "zh-cn",
      "maxDiffChars": 200000,
      "outputDirPath": ".smart-commit-cli/staged-change-summaries",
      "prompt": ""
    },
    "pullRequest": {
      "provider": "auto",
      "apiBaseUrl": "",
      "authToken": "env:SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN"
    },
    "myPullRequest": {
      "listScope": "account",
      "listKinds": ["created", "assigned", "reviewer"],
      "batchReviewKinds": ["reviewer", "assigned"],
      "remoteHost": ""
    },
    "pullRequestCreation": {
      "autoCreateAfterPush": false,
      "configFilePath": "",
      "targetBranch": "",
      "titlePrompt": "",
      "descriptionPrompt": "",
      "maxDiffChars": 200000,
      "assignees": [],
      "reviewers": [],
      "labels": [],
      "milestone": "",
      "draft": false,
      "removeSourceBranch": false,
      "skipBranches": ["main", "master", "develop"]
    },
    "pullRequestReview": {
      "configFilePath": "",
      "threshold": 6,
      "autoApprove": true,
      "autoMerge": false,
      "summarySeverities": ["P0", "P1", "P2"],
      "commentSeverities": ["P0", "P1"],
      "skillPromptTuning": "",
      "skipSummaryOnPass": true,
      "skipCommentOnPass": true
    },
    "output": {
      "format": "json",
      "logLevel": "info"
    }
  }
}

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 --review-only

Use this when you want to:

• review staged changes
• skip commit-message generation, validation, ticket checks, local commit, and push
• integrate with hooks safely
• onboard the CLI without touching Git history

If you want the main bridge workflow to still generate or validate the commit message but stop before creating a local commit, use --no-commit instead.

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
• last-week
• monthly
• last-month
• quarterly
• last-quarter
• 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 staged change summary after a passing review

smart-commit bridge --repo . --config ./smart-commit.json --no-commit --enable-staged-change-summary

When enabled, bridge writes a Markdown staged change summary 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 staged change summary.

I want to create a PR or MR from the CLI

smart-commit pull-request create --repo . --config ./smart-commit.json --pull-request-creation-target-branch main --pull-request-provider auto

Use --dry-run to compare branches and generate PR/MR content without creating it. Provide pullRequest.authToken in the config file (often env:SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN) or set that environment variable; the token is only used for GitHub/GitLab API headers and is redacted from config output and error text.

I want to review an existing PR or MR

smart-commit pull-request review https://github.com/org/repo/pull/123 --config ./smart-commit.json

This command reads the remote PR/MR, runs review against its diff, and can publish inline comments, approve, or merge when configured. Pass comma-separated URLs to review multiple items serially in one run. Use --dry-run to keep it read-only for platform actions. Auth comes from pullRequest.authToken in config or SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN.

I want to list my related open PRs or MRs

smart-commit my-pull-request list --config ./smart-commit.json

This command fetches open PRs/MRs related to the authenticated account. It requires pullRequest.authToken (config file or environment) but does not call the LLM. Use --my-pull-request-list-scope workspace with repeated --repo paths to scope the list to specific local repositories. With listScope=account and myPullRequest.remoteHost set, the command does not require a local git repository.

I want to batch-review my related open PRs or MRs

smart-commit my-pull-request batch-review --config ./smart-commit.json

This command lists PRs/MRs using myPullRequest.batchReviewKinds, then serially runs full review for each item and prints an aggregate summary. It requires both PR auth (pullRequest.authToken from config or environment) and a valid LLM connection. With listScope=account and myPullRequest.remoteHost set, the command does not require a local git repository.

For a readable terminal report, use --output text. Default JSON keeps a one-line summary plus structured outcomes; the same pretty report is also written to stderr at info level.

I want machine-readable schemas

smart-commit schema print --target bridge

Supported schema targets:

• config-file
• config-resolve
• bridge
• commit-message-generate
• report-generate
• pull-request-create
• pull-request-review
• my-pull-request-list
• my-pull-request-batch-review

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 commit-message-generate
smart-commit schema print --target report-generate
smart-commit schema print --target pull-request-create
smart-commit schema print --target pull-request-review
smart-commit schema print --target my-pull-request-list
smart-commit schema print --target my-pull-request-batch-review

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 --review-only

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

Review an existing PR or MR

smart-commit pull-request review https://github.com/org/repo/pull/123 --config ./smart-commit.json

List my related open PRs or MRs

smart-commit my-pull-request list --config ./smart-commit.json

Batch-review my related open PRs or MRs

smart-commit my-pull-request batch-review --config ./smart-commit.json

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

commit-message generate

• 0: success
• 2: blocked preflight, such as no changes or no staged diff with auto-stage disabled
• 3: config error
• 4: runtime error

my-pull-request list

• 0: success, including an empty list
• 3: config error, such as missing pullRequest.authToken or invalid myPullRequest.* values
• 4: runtime error, such as list fetch failure or invalid repository path

my-pull-request batch-review

• 0: success, including an empty list with no reviews invoked
• 2: at least one listed item finished with not_passed
• 3: config error, such as missing PR auth, invalid review config, or mixed platforms during list fetch
• 4: any listed item finished with error, or the run was interrupted with remaining items cancelled (cancelledRemaining > 0)

When multiple items are reviewed, per-item failures are recorded in the batch summary and the run continues unless interrupted. Exit 2 takes precedence over exit 0 when any item did not pass; exit 4 takes precedence when any item errored or the run was cancelled mid-batch.

pull-request review

Single URL (one valid segment, no skipped segments):

• 0: review passed
• 2: review finished but did not pass the threshold
• 3: config error, such as missing URL, missing PR auth, invalid review config, or mixed GitHub/GitLab URLs in one comma-separated argument
• 4: runtime error during review execution

Multi-URL (comma-separated; two or more segments, or one valid URL with skipped invalid segments):

• 0: all valid URLs finished and every reviewed item passed
• 2: all valid URLs finished and at least one reviewed item did not pass
• 3: config error before review starts, including mixed GitHub/GitLab URLs, missing auth, invalid review config, or all comma-separated segments invalid with zero valid URLs
• 4: any reviewed item finished with error, or the run was interrupted with remaining items cancelled

Multi-URL edge cases:

• invalid segments are skipped and recorded in the batch summary; the run continues when at least one URL is valid
• if every comma-separated segment is invalid, the command exits 3 with No valid pull request / merge request URLs to review.
• a single valid URL with no skipped segments keeps the existing single-URL JSON output shape

Configuration Rules

Config precedence from high to low:

1. CLI arguments
2. environment variables
3. smartCommitCli in a JSON config file
4. 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 only supported JSON config object
• legacy top-level smartCommit.* keys are rejected

CLI Flags Reference

Runtime and output:

--repo <path>
--config <path>
--output <json|text>
--log-level <debug|info|warn|error>
--dry-run

Repeat --repo to pass multiple workspace repositories for my-pull-request list and my-pull-request batch-review when myPullRequest.listScope=workspace.

--dry-run is used by bridge preflight and pull-request create; it is not a config field.

Connection:

--base-url <url>
--api-key <key>
--model <model-id>
--llm-provider <openaiCompatible|anthropicCompatible|cursorAgent>
--request-timeout-ms <number>
--llm-response-correction-retry-count <0-10>

Review:

--threshold <number>
--review-max-diff-chars <number>
--review-language <zh-cn|zh-tw|en|...>
--code-review-skill-id <skill-id>
--code-review-skill-path <path>
--code-review-skill-prompt-tuning <text>

Commit message:

--commit-message <text>
--commit-language <zh-cn|zh-tw|en|...>
--commit-message-max-diff-chars <number>
--commit-message-structure <subjectOnly|subjectBody|subjectBodyFooter>
--commit-message-scope <auto|required|forbidden>
--auto-generate-commit-message <true|false>
--hybrid-generate-commit-message <true|false>
--validation-protocol <none|conventional|semantic|gitmoji>
--validation-pattern <regex>
--extract-ticket-id-from-branch <true|false>
--require-ticket-id <true|false>
--commit-skill-id <skill-id>
--commit-skill-path <path>
--commit-skill-prompt-tuning <text>

Git:

--auto-stage
--no-auto-stage
--review-only
--auto-commit
--no-commit
--auto-push
--no-push
--push-timeout-ms <number>

--review-only is a per-run bridge mode that reviews staged changes without commit-message generation, validation, local commit, or push. --no-commit keeps the normal commit-message flow and only skips creating a local commit after review passes.

Pass history:

--enable-pass-history <true|false>
--pass-history-write-stage <review_passed|commit_completed|commit_push_completed>
--pass-history-dir <path>
--pass-history-output-dir <path>
--pass-history-max-entries <number>

Reporting:

--period <daily|yesterday|weekly|last-week|monthly|last-month|quarterly|last-quarter|yearly|custom>
--start-date <YYYY-MM-DD>
--end-date <YYYY-MM-DD>
--report-language <zh-cn|zh-tw|en|...>
--report-week-starts-on <monday|sunday>
--report-output-dir <path>
--report-max-input-chars <number>
--report-prompt <text>
--report-ai
--no-report-ai

--period belongs to report generate; it is not a global config override for bridge. Use --period custom --start-date YYYY-MM-DD --end-date YYYY-MM-DD for an inclusive natural-day range.

Staged change summary:

--enable-staged-change-summary <true|false>
--staged-change-summary-language <zh-cn|zh-tw|en|...>
--staged-change-summary-max-diff-chars <number>
--staged-change-summary-output-dir <path>
--staged-change-summary-prompt <text>

Pull request / merge request:

--pull-request-creation-auto-create-after-push <true|false>
--pull-request-creation-config-file-path <path1,path2,...>
--pull-request-creation-target-branch <branch>
--pull-request-provider <auto|github|gitlab>
--pull-request-api-base-url <url>
--pull-request-auth-token <token>
--pull-request-creation-title-prompt <text>
--pull-request-creation-description-prompt <text>
--pull-request-creation-max-diff-chars <number>
--pull-request-creation-assignee <user>
--pull-request-creation-reviewer <user-or-team>
--pull-request-creation-label <label>
--pull-request-creation-milestone <milestone>
--pull-request-creation-draft <true|false>
--pull-request-creation-remove-source-branch <true|false>
--pull-request-creation-skip-branch <branch>

Pull request review:

--pull-request-review-config-file-path <path1,path2,...>
--pull-request-review-threshold <number>
--pull-request-review-auto-approve <true|false>
--pull-request-review-auto-merge <true|false>
--pull-request-review-summary-severities <P0,P1,P2,P3>
--pull-request-review-comment-severities <P0,P1,P2,P3>
--pull-request-review-skill-prompt-tuning <text>
--pull-request-review-skip-summary-on-pass <true|false>
--pull-request-review-skip-comment-on-pass <true|false>

My pull request list and batch review:

--my-pull-request-list-scope <account|workspace>
--my-pull-request-list-kinds <created,assigned,reviewer>
--my-pull-request-batch-review-kinds <created,assigned,reviewer>
--my-pull-request-remote-host <host-or-url>

Repeat --pull-request-creation-assignee, --pull-request-creation-reviewer, --pull-request-creation-label, or --pull-request-creation-skip-branch to pass multiple values.

Environment Variables Reference

Boolean environment variables accept true, false, 1, or 0. Pull request array variables use comma-separated values. Secrets such as API keys and PR/MR auth tokens are redacted from config output and error text.

Connection and output:

SMART_COMMIT_BASE_URL
SMART_COMMIT_API_KEY
SMART_COMMIT_MODEL
SMART_COMMIT_LLM_PROVIDER
SMART_COMMIT_REQUEST_TIMEOUT_MS
SMART_COMMIT_LLM_RESPONSE_CORRECTION_RETRY_COUNT
SMART_COMMIT_OUTPUT_FORMAT
SMART_COMMIT_LOG_LEVEL

Review:

SMART_COMMIT_THRESHOLD
SMART_COMMIT_REVIEW_LANGUAGE
SMART_COMMIT_REVIEW_MAX_DIFF_CHARS
SMART_COMMIT_CODE_REVIEW_SKILL_ID
SMART_COMMIT_CODE_REVIEW_SKILL_PATH
SMART_COMMIT_CODE_REVIEW_SKILL_PROMPT_TUNING

Commit message:

SMART_COMMIT_COMMIT_LANGUAGE
SMART_COMMIT_COMMIT_MESSAGE_STRUCTURE
SMART_COMMIT_COMMIT_MESSAGE_SCOPE
SMART_COMMIT_COMMIT_MESSAGE_MAX_DIFF_CHARS
SMART_COMMIT_AUTO_GENERATE_COMMIT_MESSAGE
SMART_COMMIT_HYBRID_GENERATE_COMMIT_MESSAGE
SMART_COMMIT_VALIDATION_PROTOCOL
SMART_COMMIT_VALIDATION_PATTERN
SMART_COMMIT_EXTRACT_TICKET_ID_FROM_BRANCH
SMART_COMMIT_REQUIRE_TICKET_ID
SMART_COMMIT_COMMIT_SKILL_ID
SMART_COMMIT_COMMIT_SKILL_PATH
SMART_COMMIT_COMMIT_SKILL_PROMPT_TUNING

Git and pass history:

SMART_COMMIT_AUTO_STAGE
SMART_COMMIT_AUTO_COMMIT
SMART_COMMIT_AUTO_PUSH
SMART_COMMIT_PUSH_TIMEOUT_MS
SMART_COMMIT_ENABLE_PASS_HISTORY
SMART_COMMIT_PASS_HISTORY_WRITE_STAGE
SMART_COMMIT_PASS_HISTORY_DIR
SMART_COMMIT_PASS_HISTORY_OUTPUT_DIR
SMART_COMMIT_PASS_HISTORY_MAX_ENTRIES

Reporting:

SMART_COMMIT_REPORT_LANGUAGE
SMART_COMMIT_REPORT_WEEK_STARTS_ON
SMART_COMMIT_REPORT_OUTPUT_DIR
SMART_COMMIT_REPORT_MAX_INPUT_CHARS
SMART_COMMIT_REPORT_PROMPT
SMART_COMMIT_REPORT_USE_AI

Staged change summary:

SMART_COMMIT_ENABLE_STAGED_CHANGE_SUMMARY
SMART_COMMIT_STAGED_CHANGE_SUMMARY_LANGUAGE
SMART_COMMIT_STAGED_CHANGE_SUMMARY_MAX_DIFF_CHARS
SMART_COMMIT_STAGED_CHANGE_SUMMARY_OUTPUT_DIR
SMART_COMMIT_STAGED_CHANGE_SUMMARY_PROMPT

Pull request / merge request:

SMART_COMMIT_PULL_REQUEST_PROVIDER
SMART_COMMIT_PULL_REQUEST_API_BASE_URL
SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN

My pull request list and batch review:

SMART_COMMIT_MY_PULL_REQUEST_LIST_SCOPE
SMART_COMMIT_MY_PULL_REQUEST_LIST_KINDS
SMART_COMMIT_MY_PULL_REQUEST_BATCH_REVIEW_KINDS
SMART_COMMIT_MY_PULL_REQUEST_REMOTE_HOST

Pull request creation:

SMART_COMMIT_PULL_REQUEST_CREATION_AUTO_CREATE_AFTER_PUSH
SMART_COMMIT_PULL_REQUEST_CREATION_CONFIG_FILE_PATH
SMART_COMMIT_PULL_REQUEST_CREATION_TARGET_BRANCH
SMART_COMMIT_PULL_REQUEST_CREATION_TITLE_PROMPT
SMART_COMMIT_PULL_REQUEST_CREATION_DESCRIPTION_PROMPT
SMART_COMMIT_PULL_REQUEST_CREATION_MAX_DIFF_CHARS
SMART_COMMIT_PULL_REQUEST_CREATION_ASSIGNEES
SMART_COMMIT_PULL_REQUEST_CREATION_REVIEWERS
SMART_COMMIT_PULL_REQUEST_CREATION_LABELS
SMART_COMMIT_PULL_REQUEST_CREATION_MILESTONE
SMART_COMMIT_PULL_REQUEST_CREATION_DRAFT
SMART_COMMIT_PULL_REQUEST_CREATION_REMOVE_SOURCE_BRANCH
SMART_COMMIT_PULL_REQUEST_CREATION_SKIP_BRANCHES

Pull request review:

SMART_COMMIT_PULL_REQUEST_REVIEW_CONFIG_FILE_PATH
SMART_COMMIT_PULL_REQUEST_REVIEW_THRESHOLD
SMART_COMMIT_PULL_REQUEST_REVIEW_AUTO_APPROVE
SMART_COMMIT_PULL_REQUEST_REVIEW_AUTO_MERGE
SMART_COMMIT_PULL_REQUEST_REVIEW_SUMMARY_SEVERITIES
SMART_COMMIT_PULL_REQUEST_REVIEW_COMMENT_SEVERITIES
SMART_COMMIT_PULL_REQUEST_REVIEW_SKILL_PROMPT_TUNING
SMART_COMMIT_PULL_REQUEST_REVIEW_SKIP_SUMMARY_ON_PASS
SMART_COMMIT_PULL_REQUEST_REVIEW_SKIP_COMMENT_ON_PASS

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 --review-only

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 --review-only
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