gaze-cli

Gaze command-line interface

Part of the Gaze workspace — a reversible PII pseudonymization runtime for agentic LLM workflows.

This crate publishes the gaze binary. It is the process boundary used by shell integrations and language adapters that should not link the Rust library directly.

The CLI reads from stdin, writes JSON to stdout, and emits sanitized structured errors to stderr. Panic handling is overridden so dependency panics do not dump raw input or backtraces into caller logs.

Cargo

Install from crates.io:

$ cargo install gaze-cli

Build from the workspace root:

$ cargo build -p gaze-cli

The default build includes gaze proxy for local LLM API proxy use.

Build with the MCP installer/server surface:

$ cargo build -p gaze-cli --features mcp

Run from the workspace root:

$ cargo run -p gaze-cli -- clean --policy policy.toml

The installed binary name is gaze.

Subcommands

Current subcommands in src/commands/mod.rs:

Audit logging is captured on clean via --audit-db <path>; the audit query and audit export subcommands read the same database back.

Daemon mode

gaze daemon --policy policy.toml keeps one pipeline alive and reads one JSON request per stdin line:

{"session_id":"conversation-1","text":"Contact [email protected]"}

Each stdout line is either a clean response:

{"session_id":"conversation-1","clean_text":"Contact <...:Email_1>","manifest":[],"tokens":[]}

or a typed protocol/cleaning error:

{"session_id":null,"error":"JsonMalformed","detail":"malformed JSON line"}

Sessions are isolated by session_id, evicted by LRU after --session-cap (default 1000), and evicted after --session-idle-timeout seconds (default 3600). --idle-timeout exits the process after stdin inactivity (default 1800). SIGINT and SIGTERM finish the current line, flush stdout/audit writes, and exit. Daemon audit rows are stamped with provenance_stage = "daemon".

MCP installation

The mcp feature embeds the rmcp stdio server into the gaze binary and registers gaze-document tools:

$ cargo install gaze-cli --features mcp
$ gaze mcp install --client=claude-code
$ gaze mcp doctor

install always writes the absolute std::env::current_exe() path into the client config:

{
  "mcpServers": {
    "gaze": {
      "command": "/absolute/path/to/gaze",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

Supported clients:

Use --agents-md <path> to choose where the marker-fenced Gaze MCP guidance section is written. By default, install updates ./AGENTS.md. Use --skip-agents-md to update only client JSON, and --dry-run to preview without writing.

doctor checks whether the current binary matches client config entries, whether tesseract and pdfium are available for gaze_read_file, whether the manifest directory is writable, and whether the AGENTS.md guidance section is present. Warnings do not fail by default; --strict exits non-zero on warnings. Use --json for machine-readable output.

serve runs the stdio MCP server:

$ gaze mcp serve --manifest-dir ~/.local/share/gaze/mcp-manifests --max-file-size 26214400

The server covers the data-source to model path only. It does not filter text the user pastes directly into a chat UI.

clean

$ printf '%s' 'Email [email protected] now' \
  | gaze clean --policy policy.toml

Flags:

When --policy is omitted, the CLI runs a stub email pipeline so the process surface can be exercised. Production use should pass --policy.

Safety net

The optional --safety-net=<kind> flag activates the observer-only safety net documented in docs/architecture/safety-nets.md. The safety net runs after the deterministic clean and reports suspected leaks against the manifest of emitted tokens. It cannot mutate the clean text and cannot affect restore.

Safety-net backends

Two observer-only backends are available; pick one via --safety-net-backend <backend> (v0.8) or the legacy --safety-net=<kind>. Both share the strict/tolerant exit-code contract, the LeakReport shape, and the safety_net_log audit table.

openai-filter (v0.6+) wraps the official openai/privacy-filter subprocess. Strengths: eight typed labels covering Person, Email, Phone, URL, Address, Date, Account number, Secret; documented operating points; mature upstream. Trade-offs: heavier model and slower per-clean latency; no first-party fetch path; runtime depends on a third-party Python install the operator pins.

kiji-distilbert (v0.8+) wraps a pinned DistilBERT NER model. It supports --kiji-backend=subprocess for the existing external command path and --kiji-backend=ort for in-process ONNX Runtime inference without a Python install. Strengths: lightweight ONNX-served weights, straightforward fetch script, second NER opinion at the chokepoint that complements OPF's class set. Trade-offs: narrower closed label set (person, location, organization, miscellaneous) so financial-secret or account-number suspects are not surfaced; pinned-artifact contract requires SHA256SUMS present on disk (Axis-1 fail-closed — no silent disable). The default remains subprocess for backwards compatibility.

Setup

The safety-net features are gated off by default. Build with one or both:

$ cargo build -p gaze-cli --features safety-net-openai
$ cargo build -p gaze-cli --features safety-net-kiji
$ cargo build -p gaze-cli --features safety-net-openai,safety-net-kiji

The opf command must be installed from a pinned upstream Git revision or an official release of the openai/privacy-filter repository. Adopters should record the exact upstream Git SHA or tag they install in their deployment manifest. The adapter does not download or update the checkpoint; bring-your-own-binary plus bring-your-own-weights is the v0.6 contract.

Pin the install path with GAZE_OPENAI_FILTER_OPF=/opt/opf/bin/opf or pass --openai-filter-command=<path> per invocation. The command path must be a regular file (not a symlink) when given as an absolute path, and the checkpoint directory must be owned by the current user with mode 0700 and no group/world write bits.

If the checkpoint is missing, the CLI fails closed with exit 3 and variant WeightsMissing before any subprocess spawn. Initialization failures are cached for the lifetime of the process so missing-checkpoint errors do not retry on every clean.

The Kiji DistilBERT backend follows the same bring-your-own pattern. The model directory must contain SHA256SUMS, labels.json, model.onnx, and tokenizer.json; populate it via scripts/fetch-kiji-safetynet-model.sh. A missing artifact (including a missing SHA256SUMS) fails closed with the typed SafetyNetArtifactMissing envelope and exit code 2 before the subprocess is spawned — Axis-1 reliability never silent-disables a requested backend.

See also: Kiji DistilBERT SafetyNet setup.

Synthetic example — strict mode

$ printf '%s' 'Email [email protected] or call 555-0100 now' \
  | gaze clean \
      --policy=policy.toml \
      --safety-net=openai-filter \
      --safety-net-mode=strict \
      --openai-filter-command=/opt/opf/bin/opf \
      --openai-filter-checkpoint=/opt/opf/checkpoint

A clean run emits the standard {clean_text, session_blob, stats} JSON plus a leak_report block on stdout:

{
  "clean_text": "Email <{session_hex}:Email_1> or call <{session_hex}:Phone_1> now",
  "session_blob": "<base64>",
  "stats": {"detections": 2},
  "leak_report": {
    "stats": {
      "suspect_count": 0,
      "uncovered_count": 0,
      "partial_bleed_count": 0,
      "class_mismatch_count": 0,
      "locale_skipped_count": 0
    }
  }
}

Exit code 0 and suspect_count = 0 is the contract for "no leaks".

Synthetic example — tolerant mode

$ printf '%s' 'Sender: Bob Example, phone +44 113 496 0123' \
  | gaze clean \
      --policy=policy.toml \
      --safety-net=openai-filter \
      --openai-filter-command=/opt/opf/bin/opf \
      --openai-filter-checkpoint=/opt/opf/checkpoint \
      --safety-net-mode=tolerant

If the safety net reports an Uncovered or PartialBleed suspect that the deterministic pipeline missed, tolerant mode emits a stderr warning and exits 0:

{"warning":"SafetyNet","variant":"SuspectedLeak","count":1}

Strict mode (the v0.7.x default; now opt-in via --safety-net-mode strict) would exit 3 with the JSON error {"error":"SafetyNet","exit":3,"variant":"SuspectedLeak"} and stdout would be empty. ClassMismatch suspects always warn but never fail strict mode, because the manifest still tokenized the bytes — only the class disagrees. The default mode in v0.8.x+ is resolve with a redact fallback (see the flag table above and the mode catalog).

Synthetic example — Kiji DistilBERT backend

$ printf '%s' 'Alice Example mailed the package to Berlin' \
  | gaze clean \
      --policy=policy.toml \
      --safety-net=kiji-distilbert \
      --safety-net-backend=kiji-distilbert \
      --kiji-distilbert-command=/opt/kiji/bin/kiji \
      --kiji-distilbert-model-dir=~/.local/share/gaze/models/kiji-distilbert

The --safety-net-backend flag overrides any legacy --safety-net=<kind> value, so a deployment can keep its existing --safety-net=openai-filter invocation and flip to Kiji by adding one flag. Suspects emit the same LeakReport shape; the safety_net_id field switches to kiji-distilbert.

Approved synthetic PII

All examples in this README use project-approved synthetic fixtures so the fixture-citation and no-tenant-knowledge gates remain green:

• Emails: <local>@example.invalid, *.invalid, *.test. RFC 6761 guarantees these never resolve.
• US/CA phones: NANPA 555-01xx range (555-0100 through 555-0199), reserved by the FCC for fictional use.
• UK phones: Ofcom drama ranges (e.g. +44 113 496 0xxx), reserved by Ofcom for fictional use.
• Names: Alice Example, Bob Example. Avoid real public-figure names.

Do not paste real customer or operator data into examples or fixtures — the fixture-citation-lint xtask gate will reject any literal that looks real or that is not cited from a checked-in test.

Latency budget

Each safety-net check spawns one opf subprocess. The default subprocess deadline is 5000 ms; tighten it via --safety-net-timeout-ms for latency-sensitive callers. On timeout the adapter sends SIGKILL, reaps the process, and returns exit 3 with variant Timeout. The safety net does not currently amortize subprocess startup across calls; a long-lived helper is filed for post-v0.6.0 (todo #303).

Audit

Combine the safety net with --audit-db <path> to persist metadata-only suspect rows into the safety_net_log table. Query the rows back with gaze audit safety-net query (see below). The schema and the bytes-free invariants are documented in docs/architecture/safety-nets.md.

restore

$ printf '%s' '{"session_blob":"<base64>","text":"Email <token> now"}' \
  | gaze restore

Flags:

strict restore fails on unknown tokens. tolerant restore preserves unknown tokens and returns a warning in the JSON response.

audit query

Reads the SQLite redaction log written by gaze clean --audit-db <path> and prints filtered metadata rows as tab-separated values. The DB is opened read-only via OpenFlags::SQLITE_OPEN_READ_ONLY, so the audit CLI cannot write back to the log even if compromised.

$ gaze audit query --audit-db audit.sqlite --class email --action tokenize

Filters:

Time-filtered queries omit NULL created_at rows from legacy v0.4.3 audit DBs by SQL semantics. Unfiltered queries still surface those rows.

audit export

Same filter set as audit query, with output destined for downstream processing rather than the terminal:

$ gaze audit export --audit-db audit.sqlite --format jsonl --output redactions.jsonl

Exported JSON rows include created_at since v0.4.4. The export ships a restricted column set so raw PII payloads stay outside the export surface.

audit safety-net query

Reads the safety_net_log rows written by gaze clean --audit-db <path> --safety-net <kind> and prints them as tab-separated values. The DB is opened read-only.

$ gaze audit safety-net query \
    --audit-db audit.sqlite \
    --leak-kind uncovered \
    --field-path '$.user.email'

Filters:

The safety_net_log table stores metadata only — raw_label is the validated upstream label, not the upstream raw text. See docs/architecture/safety-nets.md for the full schema.

Exit codes

Exit codes are defined by CliError in src/error.rs.

Safety-net summary: exit 3 means the safety net (or strict mode) closed the door; exit 0 with no leak_report.stats.suspect_count means a clean run; exit 0 plus stderr {"warning":"SafetyNet",...} means tolerant mode reported suspects without blocking.

Stderr is JSON with the error variant and exit code, for example:

{"error":"PolicyConfig","exit":2}

UnknownToken includes the unknown token string because the token is already a pseudonym emitted by Gaze, not raw PII.

Full exit-code catalog (including 5 document, 6 mcp, 7 proxy feature codes) and the stability guarantee for each variant: docs/metrics.md.

Policy path

clean --policy <path> loads the TOML policy through gaze::Policy, loads bundled/path rulepacks, resolves locale precedence, builds a pipeline with gaze-assembly, then exports the session as session_blob.

For policy schema details, see docs/policy.md.