🔧 CLI Reference

Complete command-line reference for ai-slop-gate.

Basic Usage

python -m ai_slop_gate.cli <command> [options]

Commands

`init`

Initialize a default policy.yml in the current directory.

python -m ai_slop_gate.cli init [--force]

Options:

--force — Overwrite existing policy.yml

Examples:

python -m ai_slop_gate.cli init
python -m ai_slop_gate.cli init --force

`run`

Run code analysis.

python -m ai_slop_gate.cli run [options]

Core Options

`--policy <path>` ⚠️ Required

Path to policy.yml.

Why it matters: policy.yml defines include_paths — without it, every file in the repository is sent to the LLM provider, which hits token limits and generates noise from docs, lock files, and other non-code content. Always provide a policy.

Discovery order (when --policy is omitted — not recommended):

<--path>/policy.yml — policy inside the repository being analysed
./policy.yml — current working directory
Bundled package default (very permissive, no include_paths)

Best practice: every repository you scan should have its own minimal policy.yml (see Minimal policy for a target repository).

Examples:

# Explicit policy (recommended)
python -m ai_slop_gate.cli run --provider static --policy policy.yml

# Policy from the target repo (auto-discovery, requires policy.yml in --path)
python -m ai_slop_gate.cli run --provider static --path /path/to/project

# Strict production policy
python -m ai_slop_gate.cli run --provider static --policy policies/prod-strict.yml

`--provider <name> [<name> ...]`

Specify which provider(s) to run.

Available providers:

Provider	Requires API key	Description
`static` / `static_pipeline`	No	Fast deterministic static analysis
`gemini`	`GEMINI_API_KEY`	Google Gemini LLM
`groq`	`SLOPE_GATE_GROQ`	Groq LLM (Llama 3.3)
`ollama`	No (local)	Local Ollama LLM

Examples:

# Single provider
python -m ai_slop_gate.cli run --provider static --policy policy.yml

# Multiple providers
python -m ai_slop_gate.cli run --provider static gemini --policy policy.yml

# LLM + local files
python -m ai_slop_gate.cli run --provider groq --llm-local --policy policy.yml

`--path <path>`

Project directory to analyse.

Default: . (current directory)

Note: include_paths in policy.yml are resolved relative to --path. Scoping --path to your source directory alone is not sufficient — always use include_paths in policy.yml to restrict what providers see.

Examples:

python -m ai_slop_gate.cli run --provider static --policy policy.yml
python -m ai_slop_gate.cli run --provider static --path /path/to/project --policy policy.yml

`--enforcement <mode>`

Override the enforcement level set in policy.yml.

Mode	Behaviour
`blocking`	CI fails on violations (default from policy)
`advisory`	Findings are reported, CI never blocked
`never`	Report only — exit code always 0

Use advisory or never when:

Introducing the gate to an existing project (clearing baseline noise first)
Running analysis steps that should never break the build independently

Examples:

# Warn but don't block CI
python -m ai_slop_gate.cli run --provider static --enforcement advisory --policy policy.yml

# Full blocking mode
python -m ai_slop_gate.cli run --provider static --enforcement blocking --policy policy.yml

LLM Options

`--llm-local`

Scan local files with the LLM provider instead of a PR diff.

Requires: --policy with include_paths configured — otherwise the LLM receives the entire repository and will exceed token limits.

Excluded automatically by llm_provider.py (regardless of policy):

.env, .env.*, .env.example
policy.yml
docs/, scripts/, .ai-slop-cache/
Lock files (package-lock.json, poetry.lock, etc.)
Minified bundles (*.min.js)

Examples:

python -m ai_slop_gate.cli run --provider groq --llm-local --policy policy.yml
python -m ai_slop_gate.cli run --provider ollama --llm-local --path ./src --policy policy.yml

`--cache-dir <path>`

Cache directory for LLM responses.

Default: .ai-slop-cache

python -m ai_slop_gate.cli run --provider gemini --llm-local --cache-dir /tmp/cache --policy policy.yml

`--no-cache`

Disable LLM response caching (always call API).

Warning: Increases API costs significantly.

python -m ai_slop_gate.cli run --provider gemini --llm-local --no-cache --policy policy.yml

Compliance Options

`--compliance`

Run compliance checks in addition to provider analysis.

Checks: GDPR/DSGVO, license violations (GPL, AGPL), secret detection, PII detection.

python -m ai_slop_gate.cli run --provider static --compliance --policy policy.yml

`--compliance-only`

Run ONLY compliance checks, skip all LLM and static providers.

python -m ai_slop_gate.cli run --compliance-only --policy policy.yml

Output

`--verbose`

Show detailed diagnostic output: cache hits/misses, per-file progress, triggered rules.

python -m ai_slop_gate.cli run --provider gemini --llm-local --verbose --policy policy.yml

GitHub Integration

All three flags are required together to post PR comments or create GitHub Checks.

`--github-repo <owner/repo>` + `--pr-id <number>` + `--github-token <token>`

Post analysis results as a PR comment.

export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"

python -m ai_slop_gate.cli run \
  --provider groq \
  --github-repo owner/repo \
  --pr-id 123 \
  --policy policy.yml

`--github-sha <sha>`

Publish results as a GitHub Checks annotation (for push events). Used together with --github-repo and --github-token.

python -m ai_slop_gate.cli run \
  --provider static \
  --github-repo owner/repo \
  --github-sha abc123def456 \
  --policy policy.yml

`--github-token <token>`

GitHub API token. Prefer GITHUB_TOKEN environment variable over passing via CLI flag (CLI flags appear in shell history).

# Recommended
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
python -m ai_slop_gate.cli run --github-repo owner/repo --pr-id 123 --policy policy.yml

GitLab Integration

`--gitlab-project <path>` + `--mr-iid <number>` + `--gitlab-token <token>`

Post analysis results as a Merge Request comment.

export GITLAB_TOKEN="glpat-xxxxxxxxxxxx"

python -m ai_slop_gate.cli run \
  --provider groq \
  --gitlab-project user/repo \
  --mr-iid 42 \
  --policy policy.yml

`--gitlab-url <url>`

GitLab instance URL.

Default: https://gitlab.com

python -m ai_slop_gate.cli run \
  --provider static \
  --gitlab-project user/repo \
  --mr-iid 1 \
  --gitlab-url https://gitlab.company.com \
  --policy policy.yml

Minimal Policy for a Target Repository

Place this policy.yml in the root of the repository you want to scan. The gate will automatically use it (discovery order: target repo → cwd → bundled default).

# policy.yml — minimal override for target repository
version: "v1.4"
project_name: "my-project"

enforcement: advisory   # start with advisory, switch to blocking after tuning

# REQUIRED: limits what providers see. Without this, LLMs hit token limits.
include_paths:
  - src    # adjust to your source directory

ai_provider:
  name: groq
  models:
    groq: llama-3.3-70b-versatile

compliance:
  enabled: false

rules:
  - id: block-hardcoded-secrets
    when:
      signal: "hardcoded_.*"
    then:
      action: blocking
      message: "Hardcoded secret detected."

  - id: advisory-quality
    when:
      category: quality
      severity: medium
    then:
      action: advisory
      message: "Code quality issue detected."

Environment Variables

LLM API Keys

export GEMINI_API_KEY="your-gemini-key"
export SLOPE_GATE_GROQ="your-groq-key"

GitHub / GitLab Tokens

export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
export GITLAB_TOKEN="glpat-xxxxxxxxxxxx"

Complete Examples

Static Analysis (local project)

python -m ai_slop_gate.cli run \
  --provider static \
  --policy policy.yml

LLM Analysis on Local Files

export SLOPE_GATE_GROQ="your-key"

python -m ai_slop_gate.cli run \
  --provider groq \
  --llm-local \
  --policy policy.yml

Static + LLM Combined

python -m ai_slop_gate.cli run \
  --provider static groq \
  --llm-local \
  --policy policy.yml

Compliance Only

python -m ai_slop_gate.cli run \
  --compliance-only \
  --policy policy.yml

GitHub PR Analysis

export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
export SLOPE_GATE_GROQ="your-key"

python -m ai_slop_gate.cli run \
  --provider groq \
  --github-repo owner/repo \
  --pr-id 123 \
  --policy policy.yml

GitLab MR Analysis

export GITLAB_TOKEN="glpat-xxxxxxxxxxxx"
export SLOPE_GATE_GROQ="your-key"

python -m ai_slop_gate.cli run \
  --provider groq \
  --gitlab-project user/repo \
  --mr-iid 42 \
  --policy policy.yml

Local Ollama (no API key)

# Start Ollama first: ollama serve
python -m ai_slop_gate.cli run \
  --provider ollama \
  --llm-local \
  --policy policy.yml

Advisory Mode (safe for new projects)

python -m ai_slop_gate.cli run \
  --provider static \
  --enforcement advisory \
  --policy policy.yml

Production Strict Mode

python -m ai_slop_gate.cli run \
  --provider static groq \
  --llm-local \
  --enforcement blocking \
  --policy policies/production.yml

Exit Codes

Code	Meaning
`0`	Success — no blocking violations, or `--enforcement advisory/never`
`1`	Blocking violations detected (`--enforcement blocking`)

Tips & Best Practices

1. Always provide `--policy`

Without policy.yml and include_paths, LLM providers receive the entire repository and will exceed token limits on any non-trivial project.

# ✅ GOOD
python -m ai_slop_gate.cli run --provider groq --llm-local --policy policy.yml

# ❌ BAD — sends everything to the LLM
python -m ai_slop_gate.cli run --provider groq --llm-local

2. Start with `advisory`, then tighten

# Step 1: understand findings
python -m ai_slop_gate.cli run --provider static --enforcement advisory --policy policy.yml

# Step 2: block on violations once baseline is clear
python -m ai_slop_gate.cli run --provider static --enforcement blocking --policy policy.yml

3. Use environment variables for tokens

# ✅ GOOD — token not in shell history
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
python -m ai_slop_gate.cli run --github-repo owner/repo --pr-id 123 --policy policy.yml

# ❌ BAD — visible in shell history
python -m ai_slop_gate.cli run --github-token "ghp_xxxxxxxxxxxx" ...

4. Use cache for LLM in CI

LLM calls are expensive. Cache is enabled by default and reduces costs on repeat runs (e.g. when only one file changed).

# ✅ Cache enabled (default)
python -m ai_slop_gate.cli run --provider groq --llm-local --policy policy.yml

# Use --no-cache only when debugging prompt changes
python -m ai_slop_gate.cli run --provider groq --llm-local --no-cache --verbose --policy policy.yml

Troubleshooting

“LLM provider skipped: no PR context and –llm-local not set”

Add --llm-local to analyse files on disk, or pass --github-repo + --pr-id for PR diff mode.

“Token limit exceeded”

Add or tighten include_paths in policy.yml to limit which directories are sent to the LLM.

“No policy.yml found”

Run python -m ai_slop_gate.cli init to create a default policy, or pass --policy <path> explicitly.

“Trivy / Syft binary not found”

Install the required tools before running static analysis in CI:

# Trivy
curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh \
  | sh -s -- -b /usr/local/bin v

# Syft
curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh \
  | sh -s -- -b /usr/local/bin

🔧 CLI Reference

Basic Usage

Commands

init

run

Core Options

--policy <path> ⚠️ Required

--provider <name> [<name> ...]

--path <path>

--enforcement <mode>

LLM Options

--llm-local

--cache-dir <path>

--no-cache

Compliance Options

--compliance

--compliance-only

Output

--verbose

GitHub Integration

--github-repo <owner/repo> + --pr-id <number> + --github-token <token>

--github-sha <sha>

--github-token <token>

GitLab Integration

--gitlab-project <path> + --mr-iid <number> + --gitlab-token <token>

--gitlab-url <url>

Minimal Policy for a Target Repository

Environment Variables

LLM API Keys

GitHub / GitLab Tokens

Complete Examples

Static Analysis (local project)

LLM Analysis on Local Files

Static + LLM Combined

Compliance Only

GitHub PR Analysis

GitLab MR Analysis

Local Ollama (no API key)

Advisory Mode (safe for new projects)

Production Strict Mode

Exit Codes

Tips & Best Practices

1. Always provide --policy

2. Start with advisory, then tighten

3. Use environment variables for tokens

4. Use cache for LLM in CI

Troubleshooting

“LLM provider skipped: no PR context and –llm-local not set”

“Token limit exceeded”

“No policy.yml found”

“Trivy / Syft binary not found”

Related Documentation

`init`

`run`

`--policy <path>` ⚠️ Required

`--provider <name> [<name> ...]`

`--path <path>`

`--enforcement <mode>`

`--llm-local`

`--cache-dir <path>`

`--no-cache`

`--compliance`

`--compliance-only`

`--verbose`

`--github-repo <owner/repo>` + `--pr-id <number>` + `--github-token <token>`

`--github-sha <sha>`

`--github-token <token>`

`--gitlab-project <path>` + `--mr-iid <number>` + `--gitlab-token <token>`

`--gitlab-url <url>`

1. Always provide `--policy`

2. Start with `advisory`, then tighten