# Getting Started

This guide is the fastest safe path from a fresh setup to a successful `smart-commit bridge` run.

It is written for first-time users who want to:

- get the CLI working quickly
- understand what each step proves
- avoid accidental commit or push side effects

## What You Will Accomplish

By the end of this guide, you will:

1. choose how you want to run the CLI
2. prepare a minimal config
3. validate the final merged config
4. run a safe bridge preflight
5. run review-only mode
6. optionally enable pass history and reporting

## Prerequisites

Before you start, make sure you have:

- `Node.js >= 20`
- `git` available in your shell
- a Git repository to operate on
- staged changes, or a config that allows auto-stage
- an OpenAI-compatible API endpoint, model, and API key

Important command requirements:

- `bridge` requires `--repo`
- `report generate` requires `--repo`
- `config resolve` does not require `--repo`
- `bridge` requires a valid connection config

## Choose How To Run The CLI

You have three common options.

### Option 1: Use the published package

Install globally:

```bash
npm install -g smart-commit-copilot-cli
smart-commit --help
```

Or use `npx` directly:

```bash
npx smart-commit-copilot-cli --help
```

### Option 2: Run from a local checkout

From the repository root:

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

If you want the `smart-commit` command in your shell while developing locally:

```bash
npm link
smart-commit --help
```

### Option 3: Decide once, use one command form everywhere

All examples below use:

```bash
smart-commit
```

If you did not install or link the binary, replace it with:

```bash
node out/cli.js
```

## Step 1: Export Your API Key

```bash
export SMART_COMMIT_API_KEY="your-api-key"
```

Why this matters:

- the config examples in this guide reference `env:SMART_COMMIT_API_KEY`
- environment references are resolved before validation
- if the variable is missing, `bridge` cannot start

## Step 2: Create A Minimal Config File

In your target repository, create `smart-commit.json`:

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

The three most important fields are:

- `connection.baseUrl`
- `connection.apiKey`
- `connection.model`

This config is intentionally conservative:

- `autoCommit=false` prevents creating a local commit
- `autoPush=false` prevents pushing to remote

The built-in default for `connection.llmResponseCorrectionRetryCount` is already `1`, which means the CLI will allow one extra repair or regeneration pass when a review result or generated commit message fails local protocol validation. Set it to `0` later if you want to disable that behavior.

If you want a fuller example, see `examples/config/smart-commit.json`, but do not copy its side-effect settings blindly for first use.

## Step 3: Validate The Final Config

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

This is the recommended first real command because it shows:

- merged config after CLI args, env vars, file config, and defaults
- secret redaction
- validation errors before execution

For a more readable terminal view:

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

You should expect:

- a valid merged config
- no missing environment variable errors
- no invalid numbers, booleans, regex patterns, or protocol values

## Step 4: Prepare Some Staged Changes

Inside your target repository:

```bash
git add -A
git status --short
```

`bridge` works on staged content, so this step matters.

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

## Step 5: Run A Safe Preflight

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

This checks:

- repository path is valid
- current path is inside Git
- staged diff input exists, or whether auto-stage would apply
- commit-message logic can resolve
- bridge input is ready for execution

Expected result:

- `status: "ready"` if everything is prepared
- `status: "blocked"` if input is missing or staging rules prevent execution
- `status: "error"` if config or runtime setup is invalid

Human-readable version:

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

## Step 6: Run Review-Only Mode

This is the safest way to onboard the CLI into a real workflow:

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

This lets you verify:

- review execution
- commit-message generation or validation
- threshold behavior
- structured JSON output

without creating a commit or pushing to remote.

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

If your repository is mainly C code, you can switch the built-in review skill with `--code-review-skill-id c-code-review` or `review.skill.id = "c-code-review"`. Built-in `*-code-review` skills load bundled guidance and automatically fall back to generic review rules when the staged diff does not actually match the selected domain.

## Step 7: Enable Pass History When You Are Ready

If you want reporting later, enable pass history in config or with flags.

Example:

```bash
smart-commit bridge \
  --repo . \
  --config ./smart-commit.json \
  --enable-pass-history=true \
  --pass-history-write-stage=review_passed \
  --no-commit \
  --no-push
```

This writes local JSONL history for successful bridge runs.

`passHistory.writeStage` controls the earliest successful stage that is allowed to create a record. After that point, the same run updates the same record if it later reaches commit or push success, so the stored `eventType` always reflects the furthest successful stage reached by that run.

- `review_passed` writes as soon as review succeeds
- `commit_completed` waits until the local commit succeeds
- `commit_push_completed` waits until both the local commit and push succeed

If you set `commit_completed`, a successful local commit is still preserved even if a later push cannot start, fails, or times out. If you set `commit_push_completed`, those same push failures write nothing.

Stored event types mean:

- `review_passed` when review succeeds and no later success stage is reached
- `commit_completed` when a local commit succeeds and no later push success stage is reached
- `commit_push_completed` when both local commit and push succeed

## Step 8: Generate A Report

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

Supported periods:

- `daily`
- `yesterday`
- `weekly`
- `monthly`
- `quarterly`
- `yearly`

If `--period` is omitted, the CLI defaults to `weekly`. `yesterday` always uses the previous natural local day in local time.

Useful follow-up checks:

- confirm `outputFilePath`
- confirm `renderMode`
- inspect the generated Markdown
- inspect summary facts in the JSON payload

Optional AI-enhanced reporting:

```bash
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.

## Suggested First Rollout

For a new repository or team, use this order:

1. validate config with `config resolve`
2. run `bridge --dry-run`
3. run `bridge --no-commit --no-push`
4. wire the same review-only command into Husky, Cursor hooks, or scripts
5. enable pass history
6. add reporting
7. only then consider automatic commit or push

This rollout keeps the first adoption phase safe while still validating the full workflow.

## Troubleshooting Checklist

If your first run fails, check these in order:

1. Is `SMART_COMMIT_API_KEY` exported in the current shell?
2. Did you pass `--repo` for `bridge` or `report generate`?
3. Are there staged changes?
4. Does `smart-commit config resolve --config ./smart-commit.json` succeed?
5. Are `autoCommit` and `autoPush` still disabled while you test?

## Where To Go Next

- broader overview and safe rollout guidance: [`../README.md`](../README.md)
- configuration details: [`configuration.md`](./configuration.md)
- integration patterns: [`integrations.md`](./integrations.md)
- machine-facing contracts: [`contracts.md`](./contracts.md)