RedVeil.ai | Autonomous Penetration Testing

Install and configure pentest-agent, the command-line interface for the RedVeil automated penetration testing platform.

pentest-agent is the command-line interface for the RedVeil automated penetration testing platform. Published on npm as pentest-agent, it lets you manage projects, run scans, triage findings, generate reports, and monitor usage — all from your terminal or CI pipeline.

Installation

Install from npm or Bun:

npm install -g pentest-agent
# or
bun install -g pentest-agent

Or build from source (requires Bun):

cd cli
bun run build
# produces dist/cli.js — link or copy to your PATH

To build a self-contained binary:

bun run build:binary
# produces dist/pentest-agent

Verify the installation:

pentest-agent --help

Quick Start

# 1. Authenticate
pentest-agent auth login
# 2. Create a project
pentest-agent project create webapp \
  --name "Acme Web App" \
  --target https://app.acme.com \
  --auth-type none
# 3. Start a scan
pentest-agent scan start <projectId>
# 4. Check scan progress
pentest-agent scan status <projectId>
# 5. View findings
pentest-agent finding list <projectId>
# 6. Generate a report
pentest-agent report generate --project <projectId> --type executive_pdf

Global Options

These options apply to every command.

Option	Description
`--json`	Emit JSON output. Recommended for scripts and AI agents. Automatically enabled when stdout is not a TTY.
`--profile <name>`	Use a specific saved auth profile instead of the active one.
`--help`	Show help for any command.

Output Modes

Interactive (TTY)

When the CLI detects a terminal, it renders human-friendly output:

Arrays of objects are displayed as aligned ASCII tables.
Single objects are shown as key: value lines.
Primitives (strings, numbers, booleans) are printed directly.

JSON

When --json is passed, or when stdout is not a TTY (e.g. in a pipeline), all output is emitted as pretty-printed JSON:

{
  "_id": "jt7f9v3x8y2p1m0n4b6r5k1h2g7q3d4",
  "name": "Acme Web App",
  "scanStatus": "completed"
}

Errors in JSON mode are written to stderr:

{
  "ok": false,
  "error": "Project not found: abc123",
  "details": {}
}

Environment Variables

Variable	Description
`REDVEIL_TOKEN`	JWT access token. Overrides any token stored in the active profile. Useful for CI environments.
`REDVEIL_PROFILE`	Profile name to use when `--profile` is not passed. Falls back to the config file's `activeProfile`.
`REDVEIL_CONFIG_DIR`	Override the directory where the config file is stored. Defaults to `$XDG_CONFIG_HOME/redveil` or `~/.config/redveil`.
`REDVEIL_DEBUG`	Set to `1` to print full stack traces on errors.

Configuration

The CLI stores authentication state in a local config file.

Default path: ~/.config/redveil/config.json

The directory is resolved in order:

$REDVEIL_CONFIG_DIR if set
$XDG_CONFIG_HOME/redveil if $XDG_CONFIG_HOME is set
~/.config/redveil

Config File Format

{
  "version": 1,
  "activeProfile": "default",
  "profiles": {
    "default": {
      "token": "eyJhb...",
      "refreshToken": "ref_...",
      "tokenExpiresAt": 1741824000000,
      "lastAuthenticatedAt": 1741820400000,
      "lastValidatedAt": 1741820400000,
      "claims": {
        "sub": "user_abc",
        "email": "user@example.com",
        "org_id": "org_xyz"
      }
    }
  }
}

Profiles

Profiles allow you to maintain multiple authenticated sessions (e.g. for different organizations or environments). Only one profile is active at a time. Switch profiles with auth use.

CLI Overview