SpecWise CLI (command: specwise) - spec-first, minimal diff AI dev tool for managing AI generated changes safely.
specwise)SpecWise helps solo founders and IC developers ship AI-assisted changes safely by forcing spec-first, minimal-diff work with a built-in seatbelt.
Who this is for:
Spec first: every goal becomes a tiny, structured plan.
Minimal diffs: no giant refactors by default.
Seatbelt and metrics: track AI vs human work.
JSON APIs available for dashboards: status, snapshot, seatbelt, metrics, report.
Commands below match the 0.3.x CLI (tag v0.3.1). Check your version with specwise version; behaviour may shift slightly between minor releases. Install from npm for normal use; cloning this repo is only needed if you are contributing to SpecWise itself.
.env: GEMINI_API_KEY or OPENAI_API_KEYnpm install -g specwise
npx specwise init # run inside the project you want to manage with SpecWise
specwise help
specwise init asks which LLM provider you use (Gemini/OpenAI/both/not sure) and warns if required API keys are missing.git init first in new projects.git clone https://github.com/TomekKaszynski/SpecWise.git specwise
cd specwise
npm install
npm run build
npm link # makes the 'specwise' command available globally
After linking, create or switch to a project repo and run specwise init (see Workspace layout below).
specwise version
specwise doctor
specwise help
$ specwise doctor
SpecWise doctor report:
✓ Workspace: .specwise directory found (/path/to/your/project/.specwise)
✓ Config: Loaded .specwise/config.json (llmProvider=gemini, model=gemini-2.0-flash)
✗ Env: Missing environment variables: GEMINI_API_KEY. Required for spec-ai and fix-ai. Next: Add GEMINI_API_KEY or OPENAI_API_KEY to .env or export it.
Seatbelt: mode=warn threshold=1
Use specwise doctor --json if you want other tools to check readiness automatically.
specwise doctor checks local readiness; specwise ci-check prints a CI safety summary (fail-open for now).echo "GEMINI_API_KEY=your_key_here" >> .env
specwise spec-ai "Add a /health endpoint that returns { status: 'ok' }"
specwise specs
specwise view-spec 1
mkdir -p /tmp/specwise-demo-app
cd /tmp/specwise-demo-app
git init
echo 'console.log("hello SpecWise");' > index.js
specwise init # creates .specwise/config.json and workspace
echo "GEMINI_API_KEY=your_key_here" >> .env
specwise doctor # should show green checks when key + workspace are present
specwise spec "add a dark mode toggle" # saves a spec file under .specwise/specs
specwise seatbelt # shows status/mode/threshold (should be ok)
specwise metrics --days 3 # quick AI vs human trend
specwise report # shareable safety snapshot
Copy-paste ready templates below. Add SpecWise to your CI pipeline to enforce AI safety policies.
Create .github/workflows/specwise.yml:
name: SpecWise CI Check
on:
pull_request:
branches: [main, develop]
jobs:
ai-safety:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
with:
fetch-depth: 30 # Needed for AI density metrics
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '18'
- name: Run SpecWise Check
run: npx specwise@latest ci-check --strict
env:
SPECWISE_LICENSE_KEY: ${{ secrets.SPECWISE_LICENSE_KEY }}
Note:
--strictmode requires Pro tier. Omit flag for free tier (fail-open mode).
Add to .gitlab-ci.yml:
specwise_check:
stage: test
image: node:18
before_script:
- npm install -g specwise@latest
script:
- specwise ci-check --strict
only:
- merge_requests
variables:
GIT_DEPTH: 30 # Needed for metrics
Add to .circleci/config.yml:
version: 2.1
jobs:
specwise:
docker:
- image: cimg/node:18.0
steps:
- checkout
- run:
name: Install SpecWise
command: npm install -g specwise@latest
- run:
name: Run AI Safety Check
command: specwise ci-check --strict
workflows:
test:
jobs:
- specwise
pipeline {
agent any
stages {
stage('SpecWise Check') {
steps {
sh 'npx specwise@latest ci-check --strict'
}
}
}
}
In --strict mode (Pro tier), CI fails when:
Exit code 1 blocks the merge. Clear reason printed:
❌ SpecWise CI Seatbelt: BLOCKED
Reason: AI 78% > 60% threshold, no test files changed
Override with --force or adjust thresholds
SpecWise only writes inside .specwise in the current repo and never edits your app code or other config files.
.specwise/config.json - CLI config, including seatbelt mode and threshold..specwise/specs/*.json - saved specs (AI and human)..specwise/fixes/*.json - saved fix plans..specwise/logs/YYYY-MM-DD.log - daily human-friendly log of specs, fixes, and commands.specwise ci-check, activated with SPECWISE_LICENSE_KEY in CI (keys start with sp_; never commit them).ci-check is fail-open (always exits 0) and prints a safety report; Pro will support fail-closed enforcement in CI soon.SpecWise sits in CI as a neutral auditor: it watches AI density and ghost specs so teams can move fast without letting AI wreck the codebase. Think “refactor insurance” for AI-heavy repos.
Enforcement config example (honored only with a Pro license + --strict):
{
"enforcement": {
"enabled": true,
"aiDensityThreshold": 1.5,
"ghostSpecTolerance": 0
}
}
This is beta pricing and may change; early teams will be grandfathered at their agreed rate. Want exact pricing or to join Founders Club? Open an issue at https://github.com/TomekKaszynski/SpecWise/issues.
| Feature | Free (local) | Pro CI seatbelt |
|---|---|---|
| Local specs and fixes | Included | Included |
CI specwise ci-check report | Included | Included |
| AI density and ghost spec metrics | Included | Included |
| Pro enforcement preview signals | Included | Included |
| Fail closed CI enforcement | Not yet | Planned Pro only |
Why Pro: Pro focuses on CI reliability and AI refactor insurance—keeping merges safe when AI work is high or specs are missing. It builds on the same CLI outputs you have locally, but adds enforcement in CI so risky runs can be blocked once enabled.
This is early Founders Club pricing. Standard lifetime pricing will be $249 after the first 50 teams.
Onboarding is manual (Stripe payment + license keys; no automated portal yet). See docs/founders-club.md in this repo and apply via GitHub issues.
SPECWISE_LICENSE_KEY as a repository secret; reference it with env: SPECWISE_LICENSE_KEY: ${{ secrets.SPECWISE_LICENSE_KEY }}.jobs:
ci-seatbelt:
runs-on: ubuntu-latest
env:
SPECWISE_LICENSE_KEY: ${{ secrets.SPECWISE_LICENSE_KEY }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 18
- run: npm install
- run: npm run build
- run: npx specwise ci-check --json # fail-open today; emits a safety report
# In Pro, this step can block based on aiDensity and ghostSpecs thresholds.
- run: npx specwise ci-check --strict
env:
SPECWISE_LICENSE_KEY: ${{ secrets.SPECWISE_LICENSE_KEY }}
Keep license keys out of .specwise/config.json in real teams. Current CI behavior is advisory; Pro will enable blocking rules in CI.
SPECWISE_LICENSE_KEY.sp_; keep them secret.SPECWISE_LICENSE_KEY as a CI secret (e.g., GitHub Actions) and read it via env..specwise/config.json can hold licenseKey for local experiments, but avoid committing it in real teams.specwise ci-check is fail-open today and prints a CI safety report.npm install -D husky && npx husky init (adds "prepare": "husky")..husky/pre-push:
#!/usr/bin/env sh
. "$(dirname "$0")/_/husky.sh"
npm test || exit 1
npx specwise ci-check # fail-open today; surfaces seatbelt signals
specwise snapshot --json and specwise ci-check --json.Run:
npx specwise dashboard
This starts a local dashboard at http://localhost:3000 that shows:
Override the port if needed:
SPECWISE_DASHBOARD_PORT=4000 specwise dashboard
specwise: command not found after npm link — add npm global bin to PATH. macOS/Linux: export PATH="$(npm bin -g):$PATH" (add to your shell rc).GEMINI_API_KEY is not set in specwise doctor — add to .env: echo "GEMINI_API_KEY=your_key" >> .env or export GEMINI_API_KEY=your_key, then rerun specwise doctor.node -v; upgrade via nvm or your package manager if below 18.specwise init - initialise a .specwise workspace.specwise spec "<goal>" - create a deterministic spec template.specwise spec-ai "<goal>" [--dry-run] - ask Gemini to generate a spec with small, safe steps.specwise fix <file> "<error>" - create a deterministic fix plan.specwise fix-ai <file> "<error>" [--dry-run] - ask Gemini to propose a minimal diff fix plan.specwise status - show today’s specs, fixes and commands from logs.specwise status --json - machine-readable status summary (JSON).specwise specs / specwise specs --json - list saved specs (human or JSON).specwise view-spec <index> - view a saved spec.specwise fixes / specwise fixes --json - list saved fix plans (human or JSON).specwise view-fix <index> - view a saved fix plan.specwise history / specwise history --json - show today’s actions from logs (human or JSON).specwise seatbelt [--json] [--set-mode warn|enforce|off] [--set-threshold <n>] - view or tune AI seatbelt.specwise metrics [--days <n>] [--json] - view AI vs human trend over recent days.specwise snapshot --json - one-call JSON summary for dashboards.specwise report [--json] [--days <n>] - shareable AI vs human safety snapshot.specwise ci-check [--json] - CI safety summary (fail-open today; enforcement with Pro later).specwise dashboard - start SpecWise dashboard at http://localhost:3000.--dry-run prints the AI generated plan but does not save a spec or fix JSON file.
SpecWise provides stable JSON shapes for integrations and dashboards:
specwise status --jsonspecwise snapshot --jsonspecwise seatbelt --jsonspecwise metrics --jsonspecwise report --jsonspecwise doctor --jsonExamples:
specwise snapshot --json (top-level fields):
{
"version": "0.3.0",
"workspacePath": "/repo/.specwise",
"configPath": "/repo/.specwise/config.json",
"context": { "date": "2024-08-01", "specs": { "count": 2 } },
"health": { "ok": true },
"aiSpecs": 1,
"humanSpecs": 1,
"aiFixes": 0,
"humanFixes": 1,
"seatbeltStatus": "ok",
"seatbelt": { "mode": "warn", "threshold": 1 }
}
specwise report --json (top-level fields):
{
"daysBack": 7,
"metrics": [
{ "date": "2024-08-01", "aiSpecs": 1, "humanSpecs": 2, "aiFixes": 0, "humanFixes": 1, "seatbeltStatus": "ok" }
],
"seatbelt": { "mode": "warn", "threshold": 1 }
}
specwise status now shows specs, fixes, commands, and a one-line seatbelt summary (mode, threshold, status, AI vs human counts, ratio).specwise status --json instead of parsing human output.SpecWise tracks AI vs human work per day. Seatbelt modes:
warn (default): warn when AI work exceeds your threshold ratio.enforce: block AI calls unless you override when the ratio is too high.off: disable warnings and enforcement.View and tune seatbelt and ratios:
specwise seatbelt / specwise seatbelt --json - see today’s AI/human counts, ratio, mode, threshold, status.specwise seatbelt --set-mode warn|enforce|off - update seatbelt mode in the current workspace.specwise seatbelt --set-threshold <n> - set the ratio threshold (e.g., 2.5).specwise metrics --days 7 / --json - see AI vs human trend over the last N days.specwise report / specwise report --json - shareable AI vs human safety snapshot (today + optional trend).SpecWise is built around a simple idea:
Do not let AI take huge bites out of your codebase.
Always clarify, plan, patch, verify, log.
Keep work small enough that you never get stuck in the washing machine.
GEMINI_API_KEY or OPENAI_API_KEY exported or in .envspecwise doctor
specwise spec-ai "Test the seatbelt line"
specwise seatbelt
specwise metrics --days 3
specwise report
ok to review-first (or stronger if configured).specwise report and specwise metrics summarize AI vs human specs and fixes for recent days so you can see the balance at a glance.For a new SpecWise CLI release:
package.json.npm run buildnpm run test:smokegit tag vX.Y.Zgit push origin maingit push origin vX.Y.Zcd specwise && git pull && npm run build && npm linknpm unlink -g specwise-cli (and optionally remove the cloned repo)FAQs
SpecWise CLI (command: specwise) - spec-first, minimal diff AI dev tool for managing AI generated changes safely.
We found that specwise demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.