changescribe

CLI to generate Conventional Commit messages and PR summaries using Cerebras or Groq.

Install

Pick the install command that matches your repo's package manager:

# npm
npm install -g cli-changescribe
# or in a repo
npm install cli-changescribe

# pnpm
pnpm add -g cli-changescribe
# or in a repo
pnpm add cli-changescribe

# yarn
yarn global add cli-changescribe
# or in a repo
yarn add cli-changescribe

Setup

Create a .env.local file in the repo where you run the CLI:

# Pick one (Cerebras is preferred for higher throughput)
CEREBRAS_API_KEY="your-key-here"
# or
GROQ_API_KEY="your-key-here"

Provider priority: if both keys are set, Cerebras is used.

If your repo uses pnpm or yarn, make sure you install cli-changescribe with the same package manager so the correct lockfile is updated (Vercel uses frozen-lockfile by default).

Setup process (recommended)

1. Install cli-changescribe (global or per repo).
2. Add .env.local with CEREBRAS_API_KEY or GROQ_API_KEY.
3. Run npx changescribe init to add npm scripts.
4. If you plan to use --create-pr, install and auth GitHub CLI: gh auth login.
5. Run a dry run to validate:
   • changescribe commit --dry-run
   • changescribe pr --dry-run

Optional environment variables for PR summaries:

• PR_SUMMARY_BASE (default: main)
• PR_SUMMARY_OUT (default: .pr-summaries/PR_SUMMARY.md)
• PR_SUMMARY_LIMIT (default: 400)
• PR_SUMMARY_ISSUE (default: empty)
• CHANGESCRIBE_MODEL (override model name for any provider)
• GROQ_PR_MODEL / GROQ_MODEL (legacy overrides, still supported)

Usage

Init scripts in a repo

npx changescribe init

Commit message

changescribe commit --dry-run
changescribe commit

PR summary

changescribe pr --base main --mode release
changescribe pr --base main --create-pr --mode release
changescribe pr --dry-run
changescribe pr --create-pr --skip-format

Npm script parity aliases

These match the npm scripts in your repo:

changescribe pr:summary
changescribe feature:pr
changescribe staging:pr

Notes

• changescribe commit stages changes if nothing is staged and commits/pushes by default.
• changescribe pr can create or update a GitHub PR when --create-pr is passed (requires gh).
• feature:pr and staging:pr aliases accept overrides (e.g., --base main).
• --skip-format (or --no-format) skips the format step during --create-pr.
• The CLI must be run inside a git repo.

Branching and CI/CD recommendation

We recommend a simple main/staging/feature flow:

• feature/* branches merge into staging via PRs (changescribe feature:pr).
• staging merges into main for releases (changescribe staging:pr).
• Use --base main or --base staging to override if your repo differs.

Recommended CI checks on PRs:

• feature/* → staging: lint/test/build (or your standard checks).
• staging → main: lint/test/build + any release verification.

Formatting recommendation

We use Biome via Ultracite. If your project matches our setup, add a format script like:

ultracite format

You can also pair it with a lint check:

ultracite lint || (ultracite format && ultracite lint)