CLI Setup and Installation

Installation

Install via npm

Install the Spec This CLI globally using npm:

npm install -g @spec-this/cli

Verify Installation

Check that the CLI is installed correctly:

spec-this --version

Authentication

Spec This uses a secure device login flow to authenticate your CLI. No API keys needed!

Login Command

Run the login command to authenticate:

spec-this login

What Happens During Login

The CLI displays an activation code (e.g., ABC123)
Your browser automatically opens to the verification page
Enter the activation code on the web page to authorize the CLI
The CLI receives and stores your authentication token

Example Login Output

✓ Device authorization started

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

Waiting for authorization...
✓ Successfully authenticated!

Token Storage

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

Other Auth Commands

spec-this whoami

Display your current authenticated user

spec-this logout

Clear stored credentials

Running Your First Scan

Basic Scan Command

Navigate to your GitHub repository directory and run:

cd /path/to/your/project
spec-this scan

The CLI will automatically detect your repository from git remote origin.

Prerequisites

Your repository must be hosted on GitHub
The Spec This GitHub App must be installed on your repository
You must have a git remote configured (checks git remote origin)

What Happens During a Scan

The CLI detects your GitHub repository from git remote
All source files are discovered and analyzed
Complexity metrics are calculated for each function and file
Scan data is uploaded to your Spec This dashboard
Alerts are generated based on your configured thresholds

Supported Languages

The scanner analyzes code in:

JavaScript
TypeScript
Python
Java
PHP
C#

Scan Output Example

✓ 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

Understanding Your Results

After scanning, you can view detailed results in your dashboard.

Repository Overview

See high-level metrics for your entire codebase, including total files scanned, average complexity scores, and trend analysis over time.

Code Alerts

Review specific functions, files, or patterns that exceed your thresholds. Each alert includes:

The specific metric that was exceeded
Current value vs. threshold
File path and line number
Severity level (Critical, Warning, Info)

Historical Trends

Track how your code quality changes over time. See if complexity is growing or improving with each scan.

CI/CD Integration

Integrate Spec This into your continuous integration pipeline to automatically scan code on every push or pull request.

GitHub Actions Example

Add this workflow to your repository at .github/workflows/spec-this.yml:

name: Code Quality Scan
on: [push, pull_request]

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

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

      - name: Install Spec This CLI
        run: npm install -g @spec-this/cli

      - name: Authenticate CLI
        run: spec-this login
        env:
          # You'll need to set up device login in your CI environment
          # or use a different auth method for CI
          SPEC_THIS_TOKEN: ${{ secrets.SPEC_THIS_TOKEN }}

      - name: Run Scan
        run: spec-this scan

Note: For CI/CD environments, you may need to configure authentication differently. Contact support for guidance on automated scanning.

Setting Alert Thresholds

Configure which metrics trigger alerts in your Organization Settings.

Choose from preset sensitivity levels (High, Medium, Low) or customize individual thresholds.

Recommended Starting Point

Start with Medium Sensitivity for most projects
Use High Sensitivity for new projects or critical code
Use Low Sensitivity for legacy codebases you're gradually improving

Next Steps

Now that you've run your first scan, learn more about the metrics:

Code Complexity Metrics Overview - Understand what each metric measures
Nesting Depth - Learn about nested code blocks
Branch Count - Understand decision points
Logical Lines of Code - Function length analysis

Common Issues

Authentication Failed

If you see authentication errors:

Run spec-this login to authenticate
Check that you completed the device authorization in your browser
Verify your credentials at ~/.spec-this/credentials.json
Try spec-this logout then login again

Repository Not Found

If the CLI can't find your repository:

Verify you're in a git repository directory
Check that you have a remote configured: git remote -v
Ensure the repository is hosted on GitHub
Confirm the Spec This GitHub App is installed on your repository

GitHub App Not Installed

To scan a repository, you must install the Spec This GitHub App:

Visit your organization settings in the Spec This dashboard
Install the GitHub App and grant access to your repositories
The CLI will then be able to upload scan results

High Parse Failure Rate

If many files fail to parse:

Check for syntax errors in your code
Ensure TypeScript/ESLint passes successfully
Note that generated files and build artifacts may fail to parse
See Parse Failure Rate for more details

Need Help?

If you encounter issues or have questions, we're here to help:

Email us at support@specthis.ai
Check the documentation in the sidebar for detailed metric explanations
Review your organization settings to adjust thresholds