# @earlyai/cli

AI-powered CLI tool that generates unit tests for TypeScript/JavaScript codebases.

Requires Node.js >= 20.19.0.

Installed as the `early` command (ISC licensed).

```bash
npm install -g @earlyai/cli
```

## Commands

### `gather-stats`

Gathers adoption statistics for EarlyAI-generated test files in merged PRs. Analyzes which `.early.test.*` files were added, modified, or deleted, and reports adoption metrics to the EarlyAI backend.

**Alias:** `stats`

```bash
early gather-stats [options]
```

#### Options

| Option | Env Var | Default | Description |
|---|---|---|---|
| `--api-key <key>` | `API_KEY` | — | EarlyAI API key (required) |
| `--token <token>` | `TOKEN` | — | GitHub/Bitbucket token (required) |
| `--git-org <org>` | `GIT_ORG` | auto-detected | Git organization name |
| `--git-repo <repo>` | `GIT_REPO` | auto-detected | Git repository name |
| `--scm-provider <provider>` | `SCM_PROVIDER` | `github` | SCM provider (`github` or `bitbucket`) |
| `--ref-name <ref>` | `REF_NAME` | — | Head branch name (required) |
| `--backfill [value]` | `BACKFILL` | `false` | Ignore last run timestamp and reprocess recent PRs |
| `--max-prs <number>` | `MAX_PRS` | `5` | Maximum PRs to process on first run or backfill |
| `--pr-number <number>` | `PR_NUMBER` | — | Process a single PR by number |
| `--summary-only [value]` | `SUMMARY_ONLY` | `true` | Report only the adoption summary per PR. When `false`, also includes per-file details (file paths, change types) and per-commit breakdowns |

#### How it works

**Incremental by default.** On each run, gather-stats records a timestamp. The next run only processes PRs merged after that timestamp — no cap on how many.

**First run.** When no previous run exists, there is no timestamp to start from. Instead, it processes the most recent merged PRs up to `--max-prs` (default: 5).

**Backfill mode (`--backfill`).** Resets the "since" timestamp and reprocesses the most recent merged PRs up to `--max-prs`. Use this to reprocess PRs that were missed or to refresh data after a bug fix.

**Single PR mode (`--pr-number`).** Fetches and processes only the specified PR. Bypasses the timestamp check, `--backfill`, and `--max-prs`. Use this to refresh data for a specific PR.

**What gets reported.** A merged or closed PR is included in the report if:
1. Its diff contains `.early.test.*` files (added, modified, or deleted), OR
2. Any of its commits contain `.early.test.*` files, OR
3. It has an EarlyAI workflow run (Early ran on it, even if no test files were committed)

Open PRs and PRs with no EarlyAI involvement are skipped.

**PR state tracking.** Each reported PR includes its state (`MERGED` or `CLOSED`). This is sent as `prState` in the adoption entry, allowing the backend to store it in `pr_change_type` for the SUMMARY record. The UI can use this to distinguish between merged PRs (green dot) and closed-without-merge PRs.

**Summary-only mode (`--summary-only`, default: `true`).** By default, only the adoption summary is reported for each PR (how many tests were added, modified, deleted, or unchanged). This creates a single SUMMARY record per PR on the backend. Set `--summary-only false` to also include per-file details (file paths, change types) and per-commit breakdowns — useful for debugging or detailed auditing.

#### Examples

```bash
# Normal incremental run
early gather-stats --api-key $KEY --token $TOKEN --ref-name master

# First run or backfill with more PRs
early gather-stats --api-key $KEY --token $TOKEN --ref-name master --backfill --max-prs 50

# Refresh data for a specific PR
early gather-stats --api-key $KEY --token $TOKEN --ref-name master --pr-number 1419
```