SpecThis

CLI Setup

Install the CLI, run your first scan, and understand your results

Installation

Quick Install

You can run the scanner directly with npx (no global install needed):

npx spec-this scan

Global Install (Optional)

If you prefer a persistent global install:

npm install -g @spec-this/cli

Verify with spec-this --version

Authentication

The CLI uses a secure device login flow. No API keys to manage — just run the login command and authorize in your browser.

Login

spec-this login
  1. The CLI displays an activation code
  2. Your browser opens to the verification page
  3. Enter the code on the web page to authorize
  4. The CLI stores your token locally

Example Output

✓ Device authorization started

Your activation code: ABC123
Visit: https://app.specthis.ai/activate

Waiting for authorization...
✓ Successfully authenticated!

Other Commands

spec-this whoami

Display your current authenticated user

spec-this logout

Clear stored credentials

Token is stored at ~/.spec-this/credentials.json. You only need to log in once per machine.

Running Your First Scan

Scan Command

Navigate to your GitHub repository directory and run:

npx spec-this scan

The CLI detects your repository from git remote origin automatically.

Prerequisites

  • Your repository must be hosted on GitHub
  • The SpecThis GitHub App must be installed on your repository
  • A git remote must be configured (git remote -v to check)

What Happens During a Scan

  1. The CLI identifies your GitHub repository from git remote
  2. Source files are discovered and parsed with tree-sitter
  3. 7 metrics are computed: complexity (avg, max, p95), file count, total LOC, symbol count, and alert count
  4. Results are uploaded to your SpecThis dashboard
  5. Alerts are evaluated against your configured thresholds

Supported Languages

JavaScriptTypeScriptPythonJavaPHPC#

Example Output

✓ Scan completed and uploaded successfully!

Scan Summary:
  Scan Run ID:        550e8400-e29b-41d4-a716-446655440000
  Files processed:    142
  Symbols processed:  1,847
  Edges processed:    5,234
  Metrics processed:  1,847
  Groups processed:   45

  Files scanned:      142
  Symbols extracted:  1,847
  Edges added:        5,234
  Grouping strategy:  directory-based

Rate Limits

Hobby (Free)

  • 10 scans per day
  • 250 MB max repo size
  • 5,000 max files

Pro ($49/mo)

  • 100 scans per day
  • 1 GB max repo size
  • 50,000 max files

GitHub Actions Integration

Automate scanning on every merge to your default branch. The SpecThis GitHub App provides a pre-built workflow you can configure from your repository settings.

Example Workflow

Add this to .github/workflows/spec-this.yml:

name: Code Quality Scan
on:
  push:
    branches: [main]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Run SpecThis Scan
        run: npx spec-this scan
        env:
          SPEC_THIS_TOKEN: ${{ secrets.SPEC_THIS_TOKEN }}

Generate a scan API key from your organization settings and add it as a repository secret named SPEC_THIS_TOKEN.

Understanding Your Results

Dashboard

After scanning, your dashboard shows repository health scores, metric sparklines, and trend indicators. Each metric is displayed with its current value, direction of change, and comparison to previous scans.

Alerts

Alerts fire when any metric exceeds its threshold. Each alert shows the metric name, current value, threshold, file path, and severity level (Critical, Warning, or Info).

Trends

Track how your code quality changes over time. Pro tier includes weekly and monthly aggregates for long-term trend analysis. Hobby tier retains 1 month of raw data.

Troubleshooting

Authentication Failed

  • Run spec-this login to re-authenticate
  • Verify you completed the browser authorization step
  • Try spec-this logout then login again

Repository Not Found

  • Verify you are in a git repository directory
  • Check that a remote is configured: git remote -v
  • Confirm the SpecThis GitHub App is installed on your repository

Rate Limit Exceeded

If you hit your daily scan limit, wait until the next day or upgrade to Pro for 100 scans/day. Scan limits reset at midnight UTC.

Next Steps

Need Help?

Email us at support@specthis.ai if you encounter issues or have questions.