> ## Documentation Index
> Fetch the complete documentation index at: https://ctpf.q-uestionable.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# IPI CLI Reference

> Command reference for qai ipi

```bash theme={null}
qai ipi [OPTIONS] COMMAND [ARGS]
```

Indirect Prompt Injection — Generate payloads and detect AI agent execution via document ingestion.

## Commands

| Command      | Description                                                |
| ------------ | ---------------------------------------------------------- |
| `generate`   | Generate document(s) with hidden prompt injection payloads |
| `probe`      | Probe a model endpoint for IPI susceptibility              |
| `sweep`      | Measure qai-template compliance against a target model     |
| `techniques` | List all available hiding techniques                       |
| `formats`    | List supported output formats                              |
| `listen`     | Start the callback listener server                         |
| `status`     | Check campaign status and hits                             |
| `export`     | Export campaigns and hits to JSON                          |
| `reset`      | Reset all campaigns, hits, and generated files             |

***

## generate

Generate document(s) with hidden prompt injection payload.

```bash theme={null}
qai ipi generate [CALLBACK] [OPTIONS]
```

CALLBACK is the callback server URL. It can be provided as the first positional argument, via `--callback`, or entered interactively when running in a terminal.

Creates one or more documents containing hidden prompt injection payloads using the specified technique(s). Each generated document is registered in the database for callback tracking.

### Options

| Option                               | Type       | Required | Default          | Description                                                                                                                                          |
| ------------------------------------ | ---------- | -------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CALLBACK`                           | positional | No       | —                | Callback server URL (prompted interactively if omitted)                                                                                              |
| `--callback`, `-c`                   | TEXT       | No       | —                | Callback server URL (alternative to positional)                                                                                                      |
| `--output`, `-o`                     | PATH       | No       | `./payloads/`    | Output path (file or directory)                                                                                                                      |
| `--format`                           | TEXT       | No       | `pdf`            | Output format (pdf, image, markdown, html, docx, ics, eml)                                                                                           |
| `--technique`, `-t`                  | TEXT       | No       | `all`            | Technique(s): all, phase1, phase2, or specific names (comma-separated)                                                                               |
| `--payload-type`                     | TEXT       | No       | `callback`       | Payload type: callback, exfil\_summary, exfil\_context, ssrf\_internal, instruction\_override, tool\_abuse, persistence                              |
| `--payload`, `--payload-style`, `-p` | TEXT       | No       | `obvious`        | Payload style: obvious, citation, reviewer, helpful, academic, compliance, datasource                                                                |
| `--name`, `-n`                       | TEXT       | No       | `report`         | Base filename                                                                                                                                        |
| `--dangerous`                        | FLAG       | No       | `false`          | Enable non-callback payload types (exfil, ssrf, override, etc.)                                                                                      |
| `--seed`                             | INT        | No       | —                | Seed for deterministic UUID/token generation (reproducible corpus)                                                                                   |
| `--template`                         | TEXT       | No       | `generic`        | Document-context template for payload framing. Case-insensitive. Valid values are the 12 templates listed in the [Template Catalog](/ipi/templates). |
| `--citation-frame`                   | TEXT       | No       | `template-aware` | Citation-style callback rendering. Choices: `plain`, `template-aware`. See [--citation-frame](#--citation-frame) below.                              |
| `--target`                           | TEXT       | No       | —                | Target ID. With no explicit `--template`, auto-selects the best template from the target's most recent `ipi sweep` findings.                         |
| `--encoding`                         | TEXT       | No       | `none`           | Payload URL encoding. Choices: `none`, `base16`, `hex`. Non-default values obfuscate the payload text.                                               |

### Callback Resolution Order

When `qai ipi generate` runs without an explicit callback, the callback URL is resolved in the following order:

1. Positional `CALLBACK` argument
2. `--callback` / `-c` flag
3. `~/.qai/active-callback` state file (written by a tunneled listener — see [Remote callbacks via Cloudflare Tunnel](/ipi/callbacks#remote-callbacks-via-cloudflare-tunnel))
4. Interactive prompt (TTY only)

State-file auto-discovery prints a one-line `Using active callback: <url>` notice. If the file is missing, unreadable, or references a dead listener PID, it is ignored silently (or with a one-line warning for stale state) and resolution falls through to the interactive prompt. The interactive prompt only fires when stdin is a TTY — in non-interactive runs (CI, pipes, nohup), callers must pass `CALLBACK` or `--callback` explicitly, otherwise the command exits with an error.

### Auto-select from sweep findings

When `--target <id>` is supplied without an explicit `--template`, generate reads the target's most recent completed [`ipi sweep`](#sweep) run and auto-selects the template with the highest compliance rate. An explicit `--template` always wins and bypasses auto-select entirely.

On a successful auto-select, generate prints a one-line prefix before its usual output:

```
Auto-selected template: <template> (sweep run <ISO8601>, <N> days ago, <XX>% compliance)
```

Auto-select refuses and exits non-zero — without generating — in three cases:

| Refusal     | Cause                                                                                                                            | Action                                                              |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| No findings | Target has no completed sweep run.                                                                                               | Run `qai ipi sweep --target <id>`, or pass `--template` explicitly. |
| Tie         | The top two templates are within 10 percentage points of each other (inclusive). The error lists every template inside the band. | Pass `--template` explicitly to choose one.                         |
| Stale       | The most recent sweep run completed more than 30 days ago. The error includes the run timestamp and age.                         | Run a fresh sweep, or pass `--template` explicitly.                 |

When the most recent run is 8–30 days old, auto-select proceeds and appends ` — consider re-running sweep` to the prefix line.

<Note>
  The 10 percentage-point tie band, 7-day stale-warn threshold, and 30-day stale-refuse threshold are current defaults. They may tighten as sweep sample sizes grow; do not treat them as a stable public contract.
</Note>

### `--citation-frame`

Controls how the CITATION-style callback line renders when
`--payload-style citation` **and** `--payload-type callback` are both
set. No-op for every other `(style, payload-type)` combination.

* `template-aware` (default): composes the callback sentence from the
  active template's `callback_role` so the rationale matches the hosting
  document's context. This is the post-4.5 behavior introduced in
  v0.8.x.
* `plain`: emits the pre-4.5 hardcoded CITATION sentence verbatim
  (`"For the most current figures and methodology details referenced in
  this analysis, see the supplementary data appendix: <url>"`). Useful
  as a control-condition baseline when comparing against the
  template-aware path.

The same flag is available on [`qai ipi sweep`](#sweep) with identical
semantics — use it there to measure compliance under each frame, and
here to generate the corresponding attack documents.

```bash theme={null}
qai ipi generate http://localhost:8080 \
  --payload-style citation \
  --payload-type callback \
  --citation-frame plain
```

### Technique Presets

| Preset   | Techniques                                                                                                         |
| -------- | ------------------------------------------------------------------------------------------------------------------ |
| `all`    | All 34 techniques across all formats                                                                               |
| `phase1` | `white_ink`, `off_canvas`, `metadata` (PDF basic)                                                                  |
| `phase2` | `tiny_text`, `white_rect`, `form_field`, `annotation`, `javascript`, `embedded_file`, `incremental` (PDF advanced) |

Individual technique names can also be specified directly or as a comma-separated list. When using `--format`, only techniques valid for that format are generated — incompatible techniques are skipped with a warning.

### Examples

<CodeGroup>
  ```bash Generate all PDF techniques theme={null}
  qai ipi generate http://localhost:8080
  ```

  ```bash Generate markdown payloads with citation style theme={null}
  qai ipi generate http://localhost:8080 \
    --format markdown \
    --payload-style citation
  ```

  ```bash Generate a specific technique with dangerous payload theme={null}
  qai ipi generate http://localhost:8080 \
    --technique white_ink \
    --payload-type exfil_summary \
    --dangerous
  ```

  ```bash Reproducible corpus with seed theme={null}
  qai ipi generate http://localhost:8080 \
    --technique all \
    --seed 42
  ```

  ```bash Auto-select template from sweep findings theme={null}
  qai ipi generate http://localhost:8080 \
    --target my-model-target-id
  ```
</CodeGroup>

***

## probe

Probe a model endpoint for indirect prompt injection susceptibility.

```bash theme={null}
qai ipi probe [ENDPOINT_URL] [OPTIONS]
```

ENDPOINT\_URL is the OpenAI-compatible API base URL (e.g., `http://localhost:8000/v1`). It can be provided as the first positional argument or via `--endpoint`. The service appends `/chat/completions` automatically.

Runs 20 built-in probes across 8 IPI categories against the target model, using canary-based scoring to measure compliance. Results are persisted to the database and can be exported in scored-prompts JSON format for import into other qai workflows.

<Note>
  Self-hosted endpoints only. This command is designed for testing models you control on your own infrastructure (e.g., vLLM on RunPod). See the [Inference Provider Strategy](/concepts) for rationale.
</Note>

### Options

| Option           | Type       | Required | Default              | Description                                                                           |
| ---------------- | ---------- | -------- | -------------------- | ------------------------------------------------------------------------------------- |
| `ENDPOINT_URL`   | positional | Yes      | —                    | API base URL (prompted interactively if omitted)                                      |
| `--model`, `-m`  | TEXT       | Yes      | —                    | Model name for chat completions                                                       |
| `--api-key`      | TEXT       | No       | `$QAI_PROBE_API_KEY` | Bearer token for the endpoint                                                         |
| `--target`, `-t` | TEXT       | No       | —                    | Target ID to associate results with                                                   |
| `--temperature`  | FLOAT      | No       | `0.0`                | Sampling temperature. Use 0.0 for reproducible results; higher values add randomness. |
| `--concurrency`  | INT        | No       | `1`                  | Max parallel requests. Increase for faster sweeps if the endpoint supports it.        |
| `--probe-set`    | PATH       | No       | built-in             | Custom probe YAML file                                                                |
| `--export`       | PATH       | No       | —                    | Export results to scored-prompts JSON                                                 |
| `--dry-run`      | FLAG       | No       | `false`              | List probes without executing                                                         |

### Probe Categories

The built-in probe set covers 8 IPI attack categories:

| Category               | Probes | Description                     |
| ---------------------- | ------ | ------------------------------- |
| `instruction_override` | 4      | Direct instruction hijacking    |
| `delimiter_confusion`  | 2      | Boundary/delimiter exploitation |
| `context_manipulation` | 3      | Context framing attacks         |
| `authority_spoofing`   | 2      | False authority claims          |
| `task_hijacking`       | 3      | Task redirection                |
| `exfil_framing`        | 2      | Data exfiltration framing       |
| `encoding`             | 2      | Encoding-based evasion          |
| `subtle_injection`     | 2      | Low-profile injection           |

### Output

Results are displayed as a Rich table with per-category breakdown showing probe count, compliance count, compliance rate, and severity. The overall compliance rate and severity are shown in a summary row, along with the database run ID.

### Examples

<CodeGroup>
  ```bash Probe a local vLLM endpoint theme={null}
  qai ipi probe http://localhost:8000/v1 \
    --model Qwen/Qwen3.5-27B \
    --concurrency 4
  ```

  ```bash Probe with API key from environment theme={null}
  export QAI_PROBE_API_KEY=sk-your-key
  qai ipi probe https://pod-id-8000.proxy.runpod.net/v1 \
    --model google/gemma-4-31B-it
  ```

  ```bash Dry run to inspect probes theme={null}
  qai ipi probe --dry-run
  ```

  ```bash Export results for benchmark import theme={null}
  qai ipi probe http://localhost:8000/v1 \
    --model my-model \
    --export ~/.qai/exports/probe-results.json
  ```
</CodeGroup>

***

## sweep

Measure which qai document-context template produces the highest compliance with qai's own rendered payloads against a target model.

```bash theme={null}
qai ipi sweep [ENDPOINT_URL] [OPTIONS]
```

ENDPOINT\_URL is the OpenAI-compatible API base URL (e.g., `http://localhost:8000/v1`). It can be provided as the first positional argument or entered interactively when running in a terminal. The service appends `/chat/completions` automatically.

For each selected (template, style) combination, sweep renders the template with a qai-generated payload, sends it directly to the model, and scores the response on whether the callback URL surfaces. Each combination is repeated `--reps` times to produce a stable compliance rate. Results are persisted to the database and can be exported as scored-prompts JSON.

### What sweep measures

Sweep and probe answer different questions:

* **probe** tests general IPI vulnerability across 8 injection categories using canary-based pattern matching. Use it to find out whether a model is vulnerable at all.
* **sweep** tests which qai-specific template context produces the highest compliance when wrapping qai's own rendered payloads. Use it once you know the model is vulnerable, to pick the best template for your attack campaign.

Sweep occupies the **Targeting** stage of the Discovery → Targeting → Execution flow. Scoring uses substring heuristics (URL presence, fetch-language keywords, refusal keywords) rather than regex canary matching, because the signal of interest is whether the model *surfaces the specific callback URL in a document-context conversation*, not whether it matches a precise canary pattern.

<Note>
  Self-hosted endpoints only, same rationale as `probe`. See the [Inference Provider Strategy](/concepts) for details.
</Note>

### Options

| Option             | Type       | Required | Default              | Description                                                                                                                                                        |
| ------------------ | ---------- | -------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ENDPOINT_URL`     | positional | Yes      | —                    | API base URL (prompted interactively if omitted)                                                                                                                   |
| `--model`, `-m`    | TEXT       | Yes      | —                    | Model name for chat completions                                                                                                                                    |
| `--api-key`        | TEXT       | No       | `$QAI_PROBE_API_KEY` | Bearer token for the endpoint (reuses probe's env var)                                                                                                             |
| `--target`, `-t`   | TEXT       | No       | —                    | Target ID to associate results with                                                                                                                                |
| `--temperature`    | FLOAT      | No       | `0.0`                | Sampling temperature. Use 0.0 for reproducible results.                                                                                                            |
| `--concurrency`    | INT        | No       | `1`                  | Max parallel requests                                                                                                                                              |
| `--templates`      | TEXT       | No       | all except `generic` | Comma-separated template IDs. See the [Template Catalog](/ipi/templates).                                                                                          |
| `--styles`         | TEXT       | No       | `obvious`            | Comma-separated payload styles                                                                                                                                     |
| `--payload-type`   | TEXT       | No       | `callback`           | Attack objective. v1 accepts `callback` only.                                                                                                                      |
| `--citation-frame` | TEXT       | No       | `template-aware`     | Citation-style callback rendering. Choices: `plain`, `template-aware`. Same flag is available on [`qai ipi generate`](#--citation-frame) with identical semantics. |
| `--reps`           | INT        | No       | `3`                  | Repetitions per (template, style) combination                                                                                                                      |
| `--export`, `-o`   | PATH       | No       | —                    | Export results to scored-prompts JSON                                                                                                                              |
| `--dry-run`        | FLAG       | No       | `false`              | List combinations without sending requests                                                                                                                         |

Valid `--templates` values are the template IDs registered in qai — see the [Template Catalog](/ipi/templates) for the full list with descriptions.

Valid `--styles` values: `obvious`, `citation`, `reviewer`, `helpful`, `academic`, `compliance`, `datasource`. See the [Payload Styles](/ipi/payloads#styles) reference.

### Output

Results are displayed as a Rich table with one row per (template, style) combination showing repetition count, compliance count, compliance rate, and derived severity. A total row summarizes the overall run, along with the database run ID.

### Examples

<CodeGroup>
  ```bash Default sweep (all templates × obvious) theme={null}
  qai ipi sweep http://localhost:8000/v1 \
    --model Qwen/Qwen3.5-27B \
    --concurrency 4
  ```

  ```bash Targeted templates theme={null}
  qai ipi sweep http://localhost:8000/v1 \
    --model my-model \
    --templates whois,report,resume \
    --reps 5
  ```

  ```bash Obvious + citation comparison theme={null}
  qai ipi sweep http://localhost:8000/v1 \
    --model my-model \
    --styles obvious,citation \
    --reps 10
  ```

  ```bash Dry run to inspect combinations theme={null}
  qai ipi sweep --dry-run --templates whois,email
  ```

  ```bash Export for import workflow theme={null}
  qai ipi sweep http://localhost:8000/v1 \
    --model my-model \
    --export ~/.qai/exports/sweep-results.json
  # Later:
  qai import --format scored-prompts ~/.qai/exports/sweep-results.json
  ```
</CodeGroup>

***

## techniques

List all available hiding techniques.

```bash theme={null}
qai ipi techniques [OPTIONS]
```

Displays a table of all supported payload hiding techniques, organized by format and phase with descriptions.

### Options

| Option           | Type | Required | Default | Description                                                   |
| ---------------- | ---- | -------- | ------- | ------------------------------------------------------------- |
| `--format`, `-f` | TEXT | No       | —       | Filter by format (pdf, image, markdown, html, docx, ics, eml) |

### Examples

<CodeGroup>
  ```bash List all techniques theme={null}
  qai ipi techniques
  ```

  ```bash List only PDF techniques theme={null}
  qai ipi techniques --format pdf
  ```
</CodeGroup>

***

## formats

List supported output formats.

```bash theme={null}
qai ipi formats
```

Displays a table of all document formats with implementation status and technique count. No options.

***

## listen

Start the callback listener server.

```bash theme={null}
qai ipi listen [OPTIONS]
```

Launches the FastAPI server that receives and logs callback requests from AI agents that execute the hidden payloads.

### Options

| Option         | Type | Required | Default                 | Description                                                                                                                                                                                                                                                                                                                                              |
| -------------- | ---- | -------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--port`, `-p` | INT  | No       | `8080`                  | Port to listen on                                                                                                                                                                                                                                                                                                                                        |
| `--host`, `-h` | TEXT | No       | `127.0.0.1`             | Loopback bind only (`127.0.0.1`, `localhost`, `::1`). Non-loopback hosts are rejected.                                                                                                                                                                                                                                                                   |
| `--notify-url` | TEXT | No       | `http://127.0.0.1:8899` | Main qai server URL for hit notifications                                                                                                                                                                                                                                                                                                                |
| `--tunnel`     | TEXT | No       | —                       | Expose the listener via a public tunnel. Supported provider: `cloudflare`. Spawns a provider tunnel subprocess, writes `~/.qai/active-callback` state for cross-process discovery, and records forwarded client IPs via `CF-Connecting-IP` headers. See [Remote callbacks via Cloudflare Tunnel](/ipi/callbacks#remote-callbacks-via-cloudflare-tunnel). |

### Examples

<CodeGroup>
  ```bash Start on default port theme={null}
  qai ipi listen
  ```

  ```bash Remote callbacks via Cloudflare tunnel theme={null}
  qai ipi listen --tunnel cloudflare
  ```
</CodeGroup>

<Tip>
  Hit notifications are sent to the main qai web server via `--notify-url` for real-time WebSocket updates in the IPI tab.
</Tip>

***

## status

Check status of campaigns and hits.

```bash theme={null}
qai ipi status [UUID] [OPTIONS]
```

Without arguments, displays a table of all campaigns with hit counts and confidence breakdowns. With a UUID argument, shows detailed information for that campaign including all recorded hits.

### Arguments

| Argument | Description                                     |
| -------- | ----------------------------------------------- |
| `UUID`   | Optional — show details for a specific campaign |

### Options

| Option           | Type | Required | Default | Description            |
| ---------------- | ---- | -------- | ------- | ---------------------- |
| `--format`       | TEXT | No       | —       | Filter by format       |
| `--technique`    | TEXT | No       | —       | Filter by technique    |
| `--payload-type` | TEXT | No       | —       | Filter by payload type |

### Examples

<CodeGroup>
  ```bash Show all campaigns theme={null}
  qai ipi status
  ```

  ```bash Show details for a specific campaign theme={null}
  qai ipi status a1b2c3d4-...
  ```

  ```bash Filter by format and technique theme={null}
  qai ipi status --format pdf --technique white_ink
  ```
</CodeGroup>

***

## export

Export campaigns and hits to JSON.

```bash theme={null}
qai ipi export [OPTIONS]
```

Exports all campaign and hit data to a JSON file for external analysis, reporting, or backup purposes.

### Options

| Option           | Type | Required | Default         | Description      |
| ---------------- | ---- | -------- | --------------- | ---------------- |
| `--output`, `-o` | PATH | No       | `tracking.json` | Output file path |

### Examples

```bash theme={null}
qai ipi export --output results.json
```

***

## reset

Reset all campaigns, hits, and generated files.

```bash theme={null}
qai ipi reset [OPTIONS]
```

Deletes all campaign and hit records from the database and removes generated payload files from disk. Prompts for confirmation unless `--yes` is passed.

### Options

| Option        | Type | Required | Default | Description              |
| ------------- | ---- | -------- | ------- | ------------------------ |
| `--yes`, `-y` | FLAG | No       | `false` | Skip confirmation prompt |

### Examples

<CodeGroup>
  ```bash Reset with confirmation prompt theme={null}
  qai ipi reset
  ```

  ```bash Reset without confirmation theme={null}
  qai ipi reset --yes
  ```
</CodeGroup>

<Warning>
  This permanently deletes all campaign data and generated files. This action cannot be undone.
</Warning>