flowpatrol-cli 0.2.0

Flowpatrol CLI — run security scans from your terminal

flowpatrol-cli

Command-line interface for Flowpatrol — run automated security scans against your web applications directly from your terminal or CI pipeline.

Requirements

• Python 3.10 or later
• A Flowpatrol API key (sign up)

Installation

pip install flowpatrol-cli
# or, recommended for CLI tools:
pipx install flowpatrol-cli

Quick start

# 1. Save your API key
flowpatrol auth set-key fp_live_abc123

# 2. Run a Surface scan (fast, waits for results)
flowpatrol surface https://myapp.com

# 3. Run a full scan
flowpatrol scan https://myapp.com

Commands

flowpatrol auth set-key <key>

Store your API key in ~/.config/flowpatrol/config.json. The key is also read from the FLOWPATROL_API_KEY environment variable, which takes precedence.

flowpatrol auth set-key fp_live_abc123

flowpatrol auth whoami

Show the currently active API key (redacted) and API endpoint.

flowpatrol auth whoami
flowpatrol auth whoami --verify   # also verify the key against the API

flowpatrol surface <url>

Run a Surface scan — headers, secrets, fingerprints, RLS, screenshots.

flowpatrol surface https://myapp.com
flowpatrol surface https://myapp.com --format json
flowpatrol surface https://myapp.com --format sarif
flowpatrol surface https://myapp.com --timeout 300   # 5-minute timeout

Exits with code 1 if critical or high findings are found, 0 if clean.

flowpatrol scan <url> [options]

Run a full scan. Waits for completion by default.

flowpatrol scan https://myapp.com
flowpatrol scan https://myapp.com --mode deep
flowpatrol scan https://myapp.com --no-wait          # fire-and-forget
flowpatrol scan https://myapp.com --format sarif > results.sarif

Options:

Flag	Default	Description
-m, --mode	deep	surface | deep
-f, --format	human	human | json | sarif
--no-wait	—	Return immediately with the scan ID
--timeout <seconds>	3600	Give up polling after N seconds

flowpatrol status <scan-id>

Check the current status of a scan.

flowpatrol status abc-123-def

Exit codes: 0 = complete, 1 = still running, 2 = failed/cancelled.

flowpatrol report <scan-id> [options]

Fetch the full report for a completed scan.

flowpatrol report abc-123-def
flowpatrol report abc-123-def --format json
flowpatrol report abc-123-def --format sarif > results.sarif
flowpatrol report abc-123-def --severity critical,high   # filter output

Options:

Flag	Default	Description
-f, --format	human	human | json | sarif
--severity	all	Comma-separated list to filter: critical,high,medium,low,info

Global flags

Flag	Description
-q, --quiet	Suppress all human output; rely on exit codes only
-v, --version	Print CLI version
-f, --format	Default output format for all commands: human | json | sarif
--api-url	Override the API base URL
--api-key	Override the API key (takes precedence over config file and env var)

Configuration

Configuration is stored at ~/.config/flowpatrol/config.json:

{
  "apiKey": "fp_live_abc123",
  "apiUrl": "https://api.flowpatrol.ai"
}

Environment variables override the config file:

Variable	Description
FLOWPATROL_API_KEY	API key
FLOWPATROL_API_URL	API base URL (useful for self-hosted or local dev)

Exit codes

Code	Meaning
0	Success — scan clean or command completed without findings
1	Findings detected (critical or high severity)
2	Error — invalid arguments, network failure, auth failure, timeout

CI / GitHub Actions example

- name: Security scan
  run: |
    pipx install flowpatrol-cli
    flowpatrol scan ${{ env.DEPLOY_URL }} --format sarif > flowpatrol.sarif
  env:
    FLOWPATROL_API_KEY: ${{ secrets.FLOWPATROL_API_KEY }}

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: flowpatrol.sarif

SARIF output

The --format sarif flag produces SARIF 2.1.0 output compatible with GitHub Advanced Security, VS Code SARIF Viewer, and any SARIF-aware tool.

Each finding maps to a SARIF rule with:

• A stable ID derived from the finding type (e.g. FP-SQL-INJECTION)
• OWASP and CWE tags when available
• high precision for confirmed findings, medium for unconfirmed

Human output example

  Flowpatrol — https://myapp.com
  ─────────────────────────────────────────────

  CRITICAL  Supabase service_role key exposed in client JS
            GET / → found in main-abc123.js
            Fix: Move service key to a server-only environment variable
            OWASP A02:2021 · CWE-312

  HIGH      Missing Row Level Security on 'users' table
            /rest/v1/users readable with anon key
            Fix: Enable RLS and add a SELECT policy

  ─────────────────────────────────────────────
  1 critical · 1 high · 0 medium · 0 low
  Scan ID: abc-123-def  |  Duration: 42s

Local development (monorepo)

cd packages/cli-python
pip install -e ".[dev]"   # or: uv sync

# Run tests
pytest

# Run the CLI directly
python -m flowpatrol_cli --help