CLI Reference·v1.x

speclint enforce

Gate your coding agents on spec quality. Block execution until your GitHub issue meets your minimum quality score.

# what it does

speclint enforce fetches a GitHub issue, runs it through the Speclint scoring engine, and exits with a non-zero code if the issue falls below your minimum quality threshold.

Use it as a pre-flight check in CI pipelines, agent harness scripts, or locally before handing a ticket to Cursor, Codex, Claude Code, or any other coding agent. If the spec isn't good enough, the agent never runs.

💡 The rule: No coding agent runs on a spec that scores below 80. Garbage in, garbage out — enforce catches it before the tokens are wasted.

# installation

No install required with npx:

bash

npx speclint enforce --issue 42 --repo myorg/myrepo

Or install globally:

bash

npm install -g speclint

# usage

bash

npx speclint enforce \
  --issue <number> \
  --repo <owner/repo> \
  [--min-score <0-100>] \
  [--key <SPECLINT_KEY>] \
  [--github-token <GITHUB_TOKEN>]

# options

flag	default	description
--issue	required	GitHub issue number to score
--repo	required	Repository in `owner/repo` format
--min-score	80	Minimum passing score (0–100). Exit 1 if below.
--key	$SPECLINT_KEY	Speclint API key. Falls back to env var.
--github-token	$GITHUB_TOKEN	GitHub token for private repos. Falls back to env var.

# environment variables

All flags can be set via environment variables. Flags take precedence over env vars when both are provided.

variable	description
SPECLINT_KEY	Your Speclint API key. Get one at /get-key.
GITHUB_TOKEN	GitHub personal access token or Actions token. Required for private repos; improves rate limits on public repos.

# exit codes

code	meaning
0	Pass — issue score meets or exceeds `--min-score`
1	Fail — issue score is below `--min-score`
2	Error — could not fetch issue, invalid API key, or network failure

# integration examples

1. CLI one-liner (manual gate)

Run before opening a ticket in your agent. If it fails, improve the issue first.

bash

export SPECLINT_KEY=sk-...
export GITHUB_TOKEN=ghp_...

npx speclint enforce --issue 42 --repo myorg/myrepo --min-score 80
# exit 0 → spec is ready, hand off to agent
# exit 1 → spec needs work, see score output

2. GitHub Actions (CI gate)

Block agent-triggered workflows until the linked issue scores high enough. Add this as a required check before any AI-coding job.

.github/workflows/spec-gate.yml

name: Spec Quality Gate

on:
  issues:
    types: [labeled]

jobs:
  enforce:
    if: github.event.label.name == 'agent-ready'
    runs-on: ubuntu-latest
    steps:
      - name: Check spec quality
        run: |
          npx speclint enforce \
            --issue ${{ github.event.issue.number }} \
            --repo ${{ github.repository }} \
            --min-score 80
        env:
          SPECLINT_KEY: ${{ secrets.SPECLINT_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

3. Agent harness script (pre-agent gate)

Gate any coding agent — Codex, Claude Code, Cursor — before it runs. The harness exits early if the spec isn't ready.

run-agent.sh

#!/usr/bin/env bash
set -e

ISSUE=$1
REPO=$2

echo "→ Checking spec quality for issue #$ISSUE..."

npx speclint enforce \
  --issue "$ISSUE" \
  --repo "$REPO" \
  --min-score 80

# Only reaches here if exit code = 0
echo "✓ Spec passed. Launching agent..."
claude --issue "$ISSUE" --repo "$REPO"

Usage: ./run-agent.sh 42 myorg/myrepo

# get an api key

speclint enforce requires a Speclint API key (SPECLINT_KEY). Keys are available on all paid plans.

view pricing →

← speclint.ai