Precogs CLI

The Precogs CLI provides command-line access to all Precogs security features for local development, CI/CD pipelines, and automation.

Installation

Install the official package from PyPI:

pip install precogs-cli

Requirements: Python 3.8+

Environment Variables

Variable	Description
PRECOGS_API_KEY	Your project API key (pk_live_...)
PRECOGS_BASE_URL	Override API endpoint (for local development)

---

Quick Start

# Authenticate (saves key to ~/.precogs/config.json)
precogs auth login

# List your projects
precogs projects list

# Trigger a code scan
precogs scan code <project-id>

# View vulnerabilities
precogs vulns list --severity critical

Authentication

Interactive Login

precogs auth login
# Enter your API key when prompted

API Key Flag

precogs auth login --api-key pk_live_xxxxxxxxxxxx

Environment Variable

export PRECOGS_API_KEY=pk_live_xxxxxxxxxxxx
precogs projects list  # No login required

Check Status

precogs auth status
# ✓ Authenticated with key: pk_live_a423...4709

Commands

Authentication

Command	Description
precogs auth login	Configure API key
precogs auth logout	Remove stored credentials
precogs auth status	Show authentication status

Projects

Command	Description
precogs projects list	List all projects
precogs projects get <id>	Get project details

Security Scans

Command	Description
precogs scan code <project-id>	Code security scan (SAST)
precogs scan code <id> --branch develop	Scan specific branch
precogs scan dependency <project-id>	Dependency scan (SCA)
precogs scan iac <project-id>	Infrastructure as Code scan
precogs scan container <project-id> <image>	Container image scan

Vulnerabilities

Command	Description
precogs vulns list	List all vulnerabilities
precogs vulns list --severity high	Filter by severity
precogs vulns list --project <id>	Filter by project
precogs vulns get <vuln-id>	Get vulnerability details
precogs vulns fix <vuln-id>	Get AI-generated fix

Dashboard

Command	Description
precogs dashboard	Security overview
precogs dashboard --project <id>	Project-specific metrics

Examples

Trigger a Scan

$ precogs scan code proj_abc123
✓ Scan started: scan_xyz789
  Status: pending

View Critical Vulnerabilities

$ precogs vulns list --severity critical --limit 10

╭─────────────────────────────────────────────────────────────────╮
│                  Vulnerabilities (3 found)                      │
├──────────────┬──────────┬─────────────────────────┬────────────┤
│ ID           │ Severity │ Title                   │ File       │
├──────────────┼──────────┼─────────────────────────┼────────────┤
│ vuln_abc123  │ CRITICAL │ SQL Injection           │ api/db.py  │
│ vuln_def456  │ CRITICAL │ Command Injection       │ utils.py   │
│ vuln_ghi789  │ CRITICAL │ Hardcoded Secret        │ config.py  │
╰──────────────┴──────────┴─────────────────────────┴────────────╯

Get AI Fix Suggestion

$ precogs vulns fix vuln_abc123

╭─────────────── AI-Generated Fix ───────────────╮
│                                                │
│  # Replace raw SQL with parameterized query   │
│  cursor.execute(                              │
│      "SELECT * FROM users WHERE id = ?",      │
│      (user_id,)                               │
│  )                                            │
│                                                │
╰────────────────────────────────────────────────╯

CI/CD Integration

GitHub Actions

name: Security Scan
on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Precogs CLI
        run: pip install precogs-cli
      
      - name: Run Security Scan
        env:
          PRECOGS_API_KEY: ${{ secrets.PRECOGS_API_KEY }}
        run: |
          precogs scan code ${{ secrets.PROJECT_ID }}
          precogs vulns list --severity critical

Configuration

Credentials are stored in ~/.precogs/config.json:

{
  "api_key": "pk_live_xxxxxxxxxxxx",
  "default_project": "proj_123"
}

Next Steps

• Python SDK — Programmatic access
• MCP Server — AI assistant integration