> ## Documentation Index
> Fetch the complete documentation index at: https://docs.masker.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Using the Masker CLI: masker and masker-voice tools

> Install and authenticate the masker and masker-voice binaries for detection testing, policy management, report generation, and audio replay.

Masker ships two CLI binaries built from the same repository. `masker` is a general-purpose text and admin CLI that you use for detection testing, policy authoring, session inspection, and compliance report generation. `masker-voice` is a voice-specific CLI that replays audio files through the full masking pipeline for offline testing and forensics. Neither binary is required for normal proxy operation — that is handled by the API server. The CLIs are for development, CI, and operational workflows.

## Installation

<Tabs>
  <Tab title="Build from source">
    ```bash theme={null}
    git clone git@github.com:navi25/masker.git
    cd masker
    cargo build --release
    # Binaries land at:
    #   target/release/masker
    #   target/release/masker-voice
    ```
  </Tab>

  <Tab title="GitHub Releases">
    Download a pre-built binary for your platform from [GitHub Releases](https://github.com/navi25/masker/releases). Unarchive and place the binary somewhere on your `PATH`.
  </Tab>
</Tabs>

## Authentication

Most commands operate on local files and need no credentials. For commands that talk to a remote Masker server — `sessions`, `report`, `agents`, `policy reload` — you authenticate with a session cookie.

<Steps>
  <Step title="Sign in via browser">
    Open your Masker portal at `https://masker-voice.fly.dev/portal/login` (or your self-hosted URL) and sign in with GitHub.
  </Step>

  <Step title="Copy the session cookie">
    Open your browser's developer tools, navigate to the **Application → Cookies** tab, and copy the value of `masker_session`.
  </Step>

  <Step title="Export the variable">
    ```bash theme={null}
    export MASKER_SESSION=ey...
    ```

    All remote CLI commands pick this up automatically. You can also pass it per-command with `--session`.
  </Step>
</Steps>

<Note>
  A scoped, long-lived CLI token is on the May 30 roadmap. Until then, the session cookie is the supported authentication path for remote commands.
</Note>

## Configuration file

The CLI reads `masker.toml` for defaults like the server URL, policy path, and output format. It looks for the file in this order:

1. `--config <path>` flag
2. `MASKER_CONFIG` environment variable
3. `./masker.toml` in the current directory
4. `~/.config/masker/config.toml`

A typical `masker.toml`:

```toml masker.toml theme={null}
[server]
url = "https://masker-voice.fly.dev"

[policy]
path = "./configs/mask_policy.yaml"

[output]
format = "json"
color  = "auto"
```

## Global flags

These flags apply to every command:

| Flag               | Default                        | Description                         |
| ------------------ | ------------------------------ | ----------------------------------- |
| `--config <path>`  | `~/.config/masker/config.toml` | Path to `masker.toml`               |
| `--server <url>`   | (none)                         | Override the remote API URL         |
| `--policy <path>`  | `./configs/mask_policy.yaml`   | Override the policy file            |
| `--json`           | `false`                        | Force JSON output                   |
| `--quiet`          | `false`                        | Suppress non-essential output       |
| `-v` / `--verbose` | off                            | More logging; `-vv` for trace-level |

## masker mask

Pipe text through the full masking pipeline — detection and tokenization — and see the masked output along with per-entity events.

```bash theme={null}
masker mask [--input <file>] [--policy <path>] [--scheme vault-deterministic|reversible-aead|synthetic]
```

**Example:**

```bash theme={null}
echo "Hi, this is Sarah Chen at (415) 555-2671" | masker mask --policy configs/mask_policy.yaml
# {
#   "masked": "Hi, this is MSKV1.NAME.K_HEALTHCARE.... at MSKV1.PHONE.K_HEALTHCARE....",
#   "events": [...],
#   "policy_name": "healthcare-default",
#   "policy_version": 1
# }
```

| Flag              | Description                                                                    |
| ----------------- | ------------------------------------------------------------------------------ |
| `--input <file>`  | Read from a file instead of stdin.                                             |
| `--scheme <name>` | Override the tokenization scheme for this run.                                 |
| `--passes <list>` | Comma-separated passes to run (`regex`, `gemma`). Defaults to policy settings. |
| `--require-match` | Exit `2` if no entities were detected. Useful in CI assertions.                |

## masker detect

Run detection only, without tokenizing. Returns the list of detected spans with confidence scores. Use this when tuning thresholds in your policy.

```bash theme={null}
masker detect [--input <file>] [--policy <path>] [--threshold <float>]
```

**Example:**

```bash theme={null}
masker detect tests/fixtures/sample-call.json --policy configs/mask_policy.yaml --json
```

Output is a JSON list of events, each with `kind`, `span`, `text`, `confidence`, and `pass` fields.

## masker policy

Manage and inspect mask policies.

| Subcommand                            | Description                                                |
| ------------------------------------- | ---------------------------------------------------------- |
| `masker policy validate <path>`       | Validate a policy YAML and report errors before deploying. |
| `masker policy diff <a> <b>`          | Show what would change between two policy files.           |
| `masker policy show [--name <name>]`  | Print the active policy as JSON.                           |
| `masker policy reload --server <url>` | Trigger an atomic policy reload on a running server.       |

**Validate a policy before deploying:**

```bash theme={null}
masker policy validate configs/mask_policy.yaml
```

Catches `unknown_kid`, `invalid_pass`, and `missing_entity` errors. Exit code `3` on validation failure.

**Diff two policy versions:**

```bash theme={null}
masker policy diff configs/mask_policy.yaml configs/mask_policy_v2.yaml
```

Shows added/removed entities, threshold changes, and action changes — useful before replacing a live policy.

## masker sessions

Inspect sessions on a remote server. All subcommands require `MASKER_SESSION`.

| Subcommand                                                 | Description                                              |
| ---------------------------------------------------------- | -------------------------------------------------------- |
| `masker sessions list [--agent <id>] [--since <duration>]` | List recent sessions.                                    |
| `masker sessions show <id>`                                | Show full session detail including all redaction events. |
| `masker sessions tail [--agent <id>]`                      | Stream session-completed events to stdout in real time.  |

**Tail live sessions while debugging an integration:**

```bash theme={null}
masker sessions tail --server https://masker-voice.fly.dev
```

## masker report

Generate compliance reports for a session, an agent, or your entire account. Output is a signed PDF.

```bash theme={null}
# Per-session report
masker report \
  --server https://masker-voice.fly.dev \
  --session-id sess_abc123 \
  --output report.pdf

# Per-agent weekly report
masker report \
  --server https://masker-voice.fly.dev \
  --agent-id agent_xyz \
  --since 7d \
  --output weekly.pdf

# Account-wide monthly report
masker report \
  --server https://masker-voice.fly.dev \
  --since 30d \
  --output monthly.pdf
```

| Flag                 | Description                       |
| -------------------- | --------------------------------- |
| `--session-id <id>`  | Scope report to a single session. |
| `--agent-id <id>`    | Scope report to a single agent.   |
| `--since <duration>` | Time window: `1h`, `7d`, `30d`.   |
| `--output <file>`    | PDF output path. Required.        |

## masker agents

Manage agents on a remote server.

| Subcommand                                           | Description                     |
| ---------------------------------------------------- | ------------------------------- |
| `masker agents list`                                 | List all agents.                |
| `masker agents create --name <n> --upstream <model>` | Create a new agent.             |
| `masker agents show <id>`                            | Show one agent's configuration. |
| `masker agents delete <id>`                          | Delete an agent.                |

## masker-voice replay

Replay a recorded audio file through the full voice pipeline — ASR transcription, detection, and tokenization — and write the masked transcript to a file.

```bash theme={null}
masker-voice replay \
  --input recording.wav \
  --policy configs/mask_policy.yaml \
  --asr-provider deepgram \
  --output transcript.json
```

| Flag              | Description                                                                   |
| ----------------- | ----------------------------------------------------------------------------- |
| `--input <file>`  | WAV or MP3 input file. Required.                                              |
| `--asr-provider`  | Which ASR backend to use: `deepgram`, `openai`, or `whisper-local` (default). |
| `--diarize`       | Run speaker diarization (Pass 3). Default `true`.                             |
| `--output <file>` | Write the masked transcript to this file.                                     |

<Tip>
  Use `masker-voice replay` with `whisper-local` and `--diarize false` for the fastest offline test loop — no external API calls required.
</Tip>

## Exit codes

| Code | Meaning                                                         |
| ---- | --------------------------------------------------------------- |
| `0`  | Success                                                         |
| `1`  | Generic error                                                   |
| `2`  | Command-specific failure (e.g. `--require-match` not satisfied) |
| `3`  | Policy validation failure                                       |
| `4`  | Auth failure — missing or invalid `MASKER_SESSION`              |
| `5`  | Server unreachable                                              |
| `64` | Usage error (bad or missing flags)                              |

## Environment variables read by the CLI

| Variable             | Description                                                 |
| -------------------- | ----------------------------------------------------------- |
| `MASKER_CONFIG`      | Path to `masker.toml`. Overrides the default search path.   |
| `MASKER_SERVER`      | Default `--server` URL.                                     |
| `MASKER_SESSION`     | Session cookie for remote commands.                         |
| `MASKER_POLICY_PATH` | Default `--policy` path.                                    |
| `RUST_LOG`           | Standard `tracing` filter (e.g. `masker=debug,tower=info`). |