CLI Reference

Complete reference for every nat command.

Global flags

These flags are available on all commands:

Flag	Short	Description
`--help`	`-h`	Show help text
`--version`	`-v`	Print NAT version and exit
`--verbose`		Enable verbose/debug output
`--config`	`-c`	Path to config file (default: `~/.nat/config.yaml`)
`--no-color`		Disable ANSI color output
`--json`		Output command results as JSON

`nat scan`

Run a security scan against a target API.

nat scan [flags]

Required flags

Flag	Description
`--url <url>`	Base URL of the target API

Discovery flags

Flag	Description	Default
`--spec <path\|url>`	OpenAPI 3.x / Swagger 2.x spec	Auto-discover
`--depth <n>`	Crawl depth for endpoint discovery	`3`
`--include <pattern>`	Only test paths matching glob pattern	All paths
`--exclude <pattern>`	Skip paths matching glob pattern	None
`--graphql`	Enable GraphQL introspection and testing	Auto-detect

Authentication flags

Flag	Description
`--auth-type <type>`	`bearer`, `header`, `basic`, `oauth2`, `none`
`--token <token>`	Bearer token value
`--header <K:V>`	Custom header (repeatable)
`--oauth2-token-url`	OAuth2 token endpoint URL
`--oauth2-client-id`	OAuth2 client ID
`--oauth2-client-secret`	OAuth2 client secret
`--oauth2-scope`	OAuth2 scopes (space-separated)

Execution flags

Flag	Description	Default
`--concurrency <n>`	Parallel request count	`5`
`--timeout <s>`	Per-request timeout (seconds)	`30`
`--rate-limit <n>`	Max requests per second	Unlimited
`--max-requests <n>`	Hard cap on total requests	Unlimited
`--dry-run`	Discover endpoints only, no tests	`false`
`--watch`	Enable live progress and inline findings display	`false`

Output flags

Flag	Description	Default
`--output <path>`	Report output file path	`./nat-report.html`
`--format <fmt>`	`html`, `json`, `sarif`, `markdown`	`html`
`--severity <level>`	Minimum severity to include in report	`info`
`--fail-on <level>`	Exit with non-zero code if findings ≥ level	None
`--open`	Open report in browser after scan	`false`
`--diff <scan-id>`	Compare results against a previous scan ID	—

Examples

# Basic scan
nat scan --url https://api.example.com
 
# Scan with OpenAPI spec, authenticated
nat scan \
  --url https://api.example.com \
  --spec ./openapi.yaml \
  --auth-type bearer \
  --token "$TOKEN"
 
# CI mode — fail build on high+ findings, SARIF output
nat scan \
  --url https://staging.example.com \
  --spec ./openapi.yaml \
  --format sarif \
  --output results.sarif \
  --fail-on high
 
# Live progress mode — see findings as they are discovered
nat scan --url https://api.example.com --watch
 
# Regression delta — compare against a previous scan
nat scan --url https://api.example.com --diff scan_abc123

`nat init`

Detect your project's framework and generate a .natrc configuration file.

nat init [flags]

Flag	Description
`--ci`	Generate a CI-optimised config with `--fail-on high` and SARIF output
`--force`	Overwrite an existing `.natrc` file
`--template <name>`	Start from a named starter template

Examples

# Auto-detect framework and generate .natrc
nat init
 
# Generate a CI-ready config
nat init --ci
 
# Overwrite an existing config
nat init --force

The interactive flow detects your framework (e.g. Express, FastAPI) and any OpenAPI spec in the project, then writes a pre-filled .natrc to the current directory.

nat init --ci produces a config with --fail-on high and SARIF output enabled — ready to drop into a GitHub Actions workflow.

`nat status`

Display a health dashboard showing the status of all NAT components.

nat status [flags]

Flag	Description
`--json`	Output status as machine-readable JSON
`--watch`	Continuously refresh the dashboard (live mode)

Example output

NAT Status Dashboard
────────────────────────────────────
Component        Status
────────────────────────────────────
Engine           ✅ Connected
AI Provider      ✅ Connected
Database         ✅ Connected
CI Integration   ⚠️  Degraded
────────────────────────────────────

`nat demo`

Run a complete demo scan against NAT's built-in example API.

nat demo [flags]

Flag	Description
`--no-browser`	Don't open the report in a browser
`--output <path>`	Save demo report to a specific path

`nat setup`

Interactive setup wizard that walks you through configuring NAT from scratch.

nat setup [flags]

Flag	Description
`--non-interactive`	Skip all prompts — read configuration from environment variables
`--demo`	Launch `nat demo` after setup completes

See the Setup Wizard guide for a detailed walkthrough of all 7 phases.

`nat upgrade`

Check for updates and upgrade NAT to the latest version.

nat upgrade [flags]

Flag	Description
`--check`	Only check if an update is available — don't install
`--migrate`	Run `alembic upgrade head` after upgrading (for self-hosted deployments)
`--pre`	Allow pre-release versions

See the Upgrade & Uninstall guide for details.

`nat uninstall`

Remove NAT configuration files, data, and shell completions.

nat uninstall [flags]

Flag	Short	Description
`--keep-config`		Preserve `.natrc` files
`--yes`	`-y`	Skip confirmation prompt
`--purge`		Also run `alembic downgrade base` and remove Docker volumes

See the Upgrade & Uninstall guide for details.

`nat doctor`

Run pre-flight environment validation checks.

nat doctor [flags]

Flag	Description
`--json`	Output check results as a JSON array for CI/automation
`--verbose`	Show detailed diagnostics and fix hints for each check

Runs 8 checks: Python version (≥ 3.10), pip extras, critical env vars, .natrc config, database connectivity, Alembic migration state, LLM keys, and exporter reachability. See the Environment Doctor guide for details.

`nat server`

Manage the NAT local server (self-hosted mode).

`nat server start`

nat server start [flags]

Flag	Description	Default
`--port <n>`	Listen port	`8080`
`--host <addr>`	Bind address	`127.0.0.1`
`--data-dir <path>`	Data and report storage directory	`~/.nat/data`
`--daemon`	Run as background daemon	`false`

`nat server stop`

nat server stop

Stop a running background daemon.

`nat server status`

nat server status

Show server status, port, and uptime.

`nat badge`

Generate a compliance badge for your API security posture.

nat badge [flags]

Flag	Description	Default
`--framework <name>`	Compliance framework: `owasp`, `pci-dss`, `hipaa`, `soc2`	`owasp`
`--format <fmt>`	Output format: `svg`, `png`, `markdown`	`svg`
`--output <path>`	Output file path	`./badge.<fmt>`
`--scan-id <id>`	Base badge on a specific scan (defaults to latest)	Latest

Examples

# Generate an OWASP SVG badge from the latest scan
nat badge --framework owasp --format svg --output badges/owasp.svg
 
# Generate a PCI-DSS markdown badge
nat badge --framework pci-dss --format markdown --output badges/pci-dss.md
 
# Base badge on a specific scan
nat badge --framework hipaa --scan-id scan_abc123 --format png --output badges/hipaa.png

`nat ai`

AI-powered assistant for test planning, finding explanation, and compliance reporting. Requires an AI provider to be configured (see AI Assistant docs).

nat ai <subcommand> [flags]

Global AI flags

Flag	Description
`--provider <name>`	AI provider: `openai`, `anthropic`, `ollama`, `azure`
`--model <name>`	Model name (e.g. `gpt-4`, `claude-3-opus`, `llama3`)
`--chat`	Start an interactive REPL session

`nat ai plan`

Generate a test plan from an OpenAPI spec.

nat ai plan [flags]

Flag	Description
`--spec <path>`	Path to OpenAPI/Swagger spec
`--focus <area>`	Narrow the plan to a specific area (e.g. `auth`, `payments`)
`--output <path>`	Save the plan to a file

nat ai plan --spec ./openapi.yaml --focus auth --output test-plan.md

`nat ai generate-tests`

Generate test cases for specific endpoints.

nat ai generate-tests [flags]

Flag	Description
`--endpoint <path>`	API endpoint path (e.g. `/users/{id}`)
`--method <method>`	HTTP method (e.g. `GET`, `POST`)
`--spec <path>`	Path to OpenAPI/Swagger spec

nat ai generate-tests --spec ./openapi.yaml --endpoint /users/{id} --method GET

`nat ai explain`

Explain scan findings in plain English with actionable remediation advice.

nat ai explain [flags]

Flag	Description
`--scan-id <id>`	Scan to explain findings from (defaults to latest)
`--finding-id <id>`	Explain a specific finding
`--verbose`	Include extended remediation details and code examples

nat ai explain --scan-id scan_abc123 --finding-id find_001 --verbose

`nat ai configure`

Interactive .natrc configuration advisor.

nat ai configure [flags]

Flag	Description
`--analyze`	Analyze your existing `.natrc` and suggest improvements

# Start interactive advisor
nat ai configure
 
# Analyze and improve an existing config
nat ai configure --analyze

`nat ai compliance-report`

Generate a compliance report for a specific framework.

nat ai compliance-report [flags]

Flag	Description	Default
`--framework <name>`	Compliance framework: `owasp`, `pci-dss`, `hipaa`, `soc2`	Required
`--scan-id <id>`	Source scan (defaults to latest)	Latest
`--format <fmt>`	Output format: `pdf`, `html`, `markdown`	`html`

nat ai compliance-report --framework owasp --format pdf

`nat ai audit-trail`

Generate a BGSTM (Bug Generation, Scan, Test, Mitigate) 6-phase audit trail document.

nat ai audit-trail [flags]

Flag	Description	Default
`--scan-id <id>`	Source scan (defaults to latest)	Latest
`--format <fmt>`	Output format: `pdf`, `html`, `markdown`	`html`
`--output <path>`	Output file path	`./audit-trail.<fmt>`

nat ai audit-trail --scan-id scan_abc123 --format pdf --output audit.pdf

`nat ai insights`

Get proactive insights and trend analysis from your scan history.

nat ai insights [flags]

Flag	Description	Default
`--limit <n>`	Number of scans to analyse	`10`
`--severity <level>`	Filter insights by severity level	All

nat ai insights --limit 20 --severity high

Interactive REPL

# Start a conversational AI assistant session
nat ai --chat
 
# Use a local Ollama model
nat ai --provider ollama --model llama3 --chat

See the AI Assistant docs for detailed guides on each subcommand.

`nat report`

View or export scan reports.

nat report [flags]

Flag	Description	Default
`--scan-id <id>`	Specific scan to report on	Latest
`--format <fmt>`	`html`, `json`, `sarif`, `markdown`	`html`
`--output <path>`	Output file path	`./nat-report.<fmt>`
`--open`	Open HTML report in browser	`false`
`--list`	List all available scan reports	`false`

`nat auth`

Manage NAT cloud authentication (SaaS plan).

`nat auth login`

nat auth login --key <api-key>

`nat auth logout`

nat auth logout

`nat auth status`

nat auth status

`nat config`

Manage NAT configuration.

`nat config show`

nat config show

Print current configuration.

`nat config set`

nat config set <key> <value>

Set a configuration value. Example:

nat config set scan.concurrency 10
nat config set scan.timeout 60

`nat config reset`

nat config reset

Reset all configuration to defaults.

Configuration file (`.natrc`)

NAT automatically looks for a .natrc YAML configuration file to set default values for CLI flags. This lets you avoid repeating common options on every command.

Lookup order

Project directory — .natrc in the current working directory
Home directory — ~/.natrc in your home directory
Explicit path — --config /path/to/config.yaml overrides both

The first file found wins. CLI flags always override values loaded from .natrc.

Example `.natrc`

# .natrc — NAT project-level configuration
# Place this file in your project root or home directory.
 
# Scan defaults
base_url: https://api.example.com
spec: ./openapi.yaml
timeout: 30
executors: 5
output: json
verbose: false
 
# Authentication
auth_token: "${NAT_AUTH_TOKEN}"
# api_key: "${NAT_API_KEY}"
# api_key_header: X-API-Key
 
# AI Assistant
ai:
  provider: openai
  model: gpt-4
  # provider: ollama
  # model: llama3
 
# Server defaults (for `nat server start`)
# host: 0.0.0.0
# port: 8080
# log_level: info

.natrc vs ~/.nat/config.yaml — .natrc is a project-level config file that lives alongside your code. ~/.nat/config.yaml stores global NAT defaults (like your default API key). Project-level .natrc values take precedence over global defaults, and CLI flags override both.

For a complete example, see examples/.natrc.example (opens in a new tab) in the framework repository.

Global configuration file

NAT reads global configuration from ~/.nat/config.yaml by default. Override with --config <path>.

# ~/.nat/config.yaml
scan:
  concurrency: 5
  timeout: 30
  depth: 3
  default_format: html
 
server:
  port: 8080
  host: 127.0.0.1
  data_dir: ~/.nat/data
 
auth:
  api_key: ""     # Set via `nat auth login` or NAT_API_KEY env var

Environment variables

All configuration keys can be set via environment variables using the NAT_ prefix and _ separator:

Variable	Equivalent config key
`NAT_API_KEY`	`auth.api_key`
`NAT_SCAN_CONCURRENCY`	`scan.concurrency`
`NAT_SCAN_TIMEOUT`	`scan.timeout`
`NAT_SERVER_PORT`	`server.port`
`NAT_SERVER_HOST`	`server.host`
`NAT_DATA_DIR`	`server.data_dir`
`NAT_LOG_LEVEL`	`log.level`
`NAT_AI_PROVIDER`	`ai.provider`
`NAT_AI_MODEL`	`ai.model`
`NAT_AI_API_KEY`	`ai.api_key`

Environment variables take precedence over the config file.

Exit codes

Code	Meaning
`0`	Success — scan completed, no findings at or above `--fail-on` level
`1`	Findings found at or above `--fail-on` severity level
`2`	Scan error (target unreachable, auth failure, etc.)
`3`	Configuration or usage error

`nat-admin`

Manage tenants, API keys, and plans for a self-hosted NAT deployment.

nat-admin is a separate CLI entry point installed alongside nat-engine. It operates directly on the database and requires DATABASE_URL to be set.

export DATABASE_URL=postgresql://user:password@localhost:5432/nat
nat-admin <command> [flags]

Prerequisites

Requirement	Details
`DATABASE_URL`	PostgreSQL connection string — must be set in the environment
Database migrations	Run `alembic upgrade head` before first use

Subcommands

Command	Description
`nat-admin tenant create`	Create a new tenant
`nat-admin tenant list`	List all tenants (with optional filters)
`nat-admin tenant show <tenant-id>`	Show details for a specific tenant
`nat-admin tenant update <tenant-id>`	Update plan, quota, or security quota
`nat-admin tenant deactivate <tenant-id>`	Deactivate a tenant
`nat-admin tenant rotate-key <tenant-id>`	Rotate the API key for a tenant
`nat-admin tenant usage <tenant-id>`	Show scan usage for a tenant

All subcommands accept --json for machine-readable output.

`nat-admin tenant create`

nat-admin tenant create --name "Acme Corp" --email admin@acme.com [--plan free]

Flag	Description	Default
`--name <name>`	Tenant display name	Required
`--email <email>`	Admin email address	Required
`--plan <plan>`	Plan: `free`, `pro`, `team`, `enterprise`	`free`

`nat-admin tenant list`

nat-admin tenant list [--plan <plan>] [--limit <n>] [--all]

Flag	Description	Default
`--plan <plan>`	Filter by plan: `free`, `pro`, `team`, `enterprise`	All plans
`--limit <n>`	Maximum results to return	`50`
`--all`	Return all tenants (override `--limit`)	`false`

`nat-admin tenant show`

nat-admin tenant show <tenant-id>

Shows tenant ID, name, email, plan, quota, API key prefix, and creation date.

`nat-admin tenant update`

nat-admin tenant update <tenant-id> --plan pro [--quota 500] [--security-quota 100]

Flag	Description
`--plan <plan>`	New plan: `free`, `pro`, `team`, `enterprise`
`--quota <n>`	Monthly scan quota
`--security-quota <n>`	Monthly security scan quota

`nat-admin tenant deactivate`

nat-admin tenant deactivate <tenant-id>

Deactivates the tenant. Existing scan data is preserved. Reactivation requires a database update.

`nat-admin tenant rotate-key`

nat-admin tenant rotate-key <tenant-id>

Generates a new API key for the tenant. The old key is immediately invalidated.

`nat-admin tenant usage`

nat-admin tenant usage <tenant-id>

Prints the tenant's scan count and quota consumption for the current billing period.

Examples

# Create a new tenant on the pro plan
nat-admin tenant create --name "Acme Corp" --email admin@acme.com --plan pro
 
# List all enterprise tenants as JSON
nat-admin tenant list --plan enterprise --json
 
# Upgrade a tenant's plan and set a quota
nat-admin tenant update ten_abc123 --plan team --quota 1000
 
# Rotate an API key and capture the new value
nat-admin tenant rotate-key ten_abc123 --json
 
# Show current usage for a tenant
nat-admin tenant usage ten_abc123

Exit codes

Code	Meaning
`0`	Success
`1`	Error (tenant not found, database error, missing required flag, etc.)

Was this helpful?

Custom Check Plugins Upgrade & Uninstall

CLI Reference

Global flags

nat scan

Required flags

Discovery flags

Authentication flags

Execution flags

Output flags

Examples

nat init

Examples

nat status

Example output

nat demo

nat setup

nat upgrade

nat uninstall

nat doctor

nat server

nat server start

nat server stop

nat server status

nat badge

Examples

nat ai

Global AI flags

nat ai plan

nat ai generate-tests

nat ai explain

nat ai configure

nat ai compliance-report

nat ai audit-trail

nat ai insights

Interactive REPL

nat report

nat auth

nat auth login

nat auth logout

nat auth status

nat config

nat config show

nat config set

nat config reset

Configuration file (.natrc)

Lookup order

Example .natrc

Global configuration file

Environment variables

Exit codes

nat-admin

Prerequisites

Subcommands

nat-admin tenant create

nat-admin tenant list

nat-admin tenant show

nat-admin tenant update

nat-admin tenant deactivate

nat-admin tenant rotate-key

nat-admin tenant usage

Examples

Exit codes

`nat scan`

`nat init`

`nat status`

`nat demo`

`nat setup`

`nat upgrade`

`nat uninstall`

`nat doctor`

`nat server`

`nat server start`

`nat server stop`

`nat server status`

`nat badge`

`nat ai`

`nat ai plan`

`nat ai generate-tests`

`nat ai explain`

`nat ai configure`

`nat ai compliance-report`

`nat ai audit-trail`

`nat ai insights`

`nat report`

`nat auth`

`nat auth login`

`nat auth logout`

`nat auth status`

`nat config`

`nat config show`

`nat config set`

`nat config reset`

Configuration file (`.natrc`)

Example `.natrc`

`nat-admin`

`nat-admin tenant create`

`nat-admin tenant list`

`nat-admin tenant show`

`nat-admin tenant update`

`nat-admin tenant deactivate`

`nat-admin tenant rotate-key`

`nat-admin tenant usage`