---
title: Reveal Recipes
category: reference
help_topic: tricks
help_description: Cool tricks and hidden features
help_category: best_practices
help_token_estimate: "~3,500"
---
# Reveal Recipes

**Task-based patterns for getting work done**

Find your task, get the commands. This guide organizes reveal by workflow, not by feature.

---

## Table of Contents

- [Start Here: Distinctive Capabilities](#start-here-distinctive-capabilities)
- [Code Review](#code-review)
- [Onboarding & Exploration](#onboarding-exploration)
- [Debugging & Troubleshooting](#debugging-troubleshooting)
- [Large-Function Navigation](#large-function-navigation)
- [Refactoring & Quality](#refactoring-quality)
  - [Trace call relationships](#trace-call-relationships)
  - [Find testability pressure](#find-testability-pressure)
- [Documentation Maintenance](#documentation-maintenance)
  - [Search doc body text](#search-doc-body-text)
  - [Count values across a field](#count-values-across-a-field)
  - [Build a link graph](#build-a-link-graph)
- [Session Analysis](#session-analysis)
  - [Browse sessions](#browse-sessions)
  - [Search across sessions](#search-across-sessions)
  - [Track file history across sessions](#track-file-history-across-sessions)
  - [Inspect a session](#inspect-a-session)
  - [Inspect Claude install state](#inspect-claude-install-state)
- [JSON Navigation](#json-navigation)
- [Database Operations](#database-operations)
- [Spreadsheet and BI Inspection](#spreadsheet-and-bi-inspection)
- [Infrastructure](#infrastructure)
  - [SSL certificate inspection](#ssl-certificate-inspection)
  - [On-disk certificate inspection](#on-disk-certificate-inspection)
  - [SSL expiry monitoring](#ssl-expiry-monitoring)
  - [Nginx SSL audit](#nginx-ssl-audit)
  - [Nginx ACL, routing, and ACME audit](#nginx-acl-routing-and-acme-audit)
  - [cPanel user environment](#cpanel-user-environment)
  - [Batch SSL checking with @file](#batch-ssl-checking-with-file)
- [Pipeline Integration](#pipeline-integration)
- [AI Agent Patterns](#ai-agent-patterns)
- [Multi-Language Support](#multi-language-support)
- [Quick Reference](#quick-reference)

---

## Start Here: Distinctive Capabilities

If you only have two minutes, these are the commands that most quickly explain
what Reveal does that normal code utilities do not.

### Architectural gravity and impact radius

```bash
reveal 'calls://src/?rank=callers&top=20'
reveal 'calls://src/?uncalled&type=function'
reveal 'calls://src/?target=main&format=dot' | dot -Tsvg > callgraph.svg
```

**Why this matters:** `calls://` gives you coupling hotspots, dead-code
candidates, and graph export from the CLI.

### Agent-ready PR context

```bash
reveal pack src/ --since main --budget 8000 --content
reveal review main..HEAD
```

**Why this matters:** `pack` curates token-budgeted context, and `review`
composes structural diff, checks, hotspots, and complexity delta in one pass.

### Testability pressure

```bash
reveal 'patches://tests?group=target&limit=20'
reveal testability src --tests tests
```

**Why this matters:** Patch pressure becomes useful when grouped by production
target and joined to functions that cross runtime boundaries.

### Adapter graph + documentation graph

```bash
reveal help://relationships
reveal 'markdown://docs/?link-graph'
```

**Why this matters:** `help://relationships` shows the adapter ecosystem and
power pairs; `markdown://?link-graph` turns docs into a bidirectional graph with
orphan detection.

### Session archaeology

```bash
reveal claude://
reveal 'claude://sessions/?search=auth'
reveal claude://config
```

**Why this matters:** `claude://` treats AI work history and Claude Code install
state as queryable data.

### BI workbook reverse engineering

```bash
reveal xlsx:///data/report.xlsx?powerpivot=relationships
reveal xlsx:///data/report.xlsx?powerquery=list
reveal xlsx:///data/report.xlsx?connections=show
```

**Why this matters:** Reveal can inspect Power Pivot models, Power Query M code,
and workbook connection strings from the same interface.

---

## Code Review

### See what changed structurally

```bash
# Compare branches
reveal diff://git://main/.:git://feature/.

# Pre-commit check (what did I actually change?)
reveal diff://git://HEAD/src/:src/

# Compare specific files
reveal diff://app.py:backup/app.py

# See commit impact
reveal diff://git://HEAD~1/src/:git://HEAD/src/
```

**What you get:** Functions/classes added, removed, modified. Complexity changes. Import changes.

### Check quality before merge

```bash
# Run all checks
reveal src/ --check

# Security + bugs only (fast)
reveal src/ --check --select B,S

# Specific file
reveal src/auth.py --check --select B,S
```

### Review specific changes

```bash
# See what's in a file
reveal src/app.py

# Extract specific function
reveal src/app.py handle_request

# Check complexity of changed functions
reveal 'ast://src/?complexity>10'
```

### PR Review Workflow

```bash
# Full PR review: structural diff + quality violations + hotspots + complexity delta
reveal review main..HEAD

# Security and bugs only (fast path)
reveal review main..HEAD --select B,S

# JSON for CI/automated processing
reveal review main..HEAD --format json

# CI gate: exit 0 clean, exit 1 warnings, exit 2 errors
reveal review main..HEAD || exit 1

# See exactly what changed structurally (lower level)
reveal diff://git://main/.:git://HEAD/.

# Which functions got more complex in this PR?
reveal diff://git://main/.:git://HEAD/. --format json | \
  jq '.diff.functions[] | select(.complexity_delta > 5)'
```

**What `reveal review` composes for you:** structural diff → quality checks → hotspot detection → complexity delta, all under consistent exit codes. Every changed function carries `complexity_before`, `complexity_after`, and `complexity_delta`.

---

## Onboarding & Exploration

### Map a new codebase

```bash
# 1. See high-level structure
reveal .

# 2. Explore main directories
reveal src/
reveal tests/

# 3. Find entry points
reveal src/main.py
reveal src/__init__.py

# 4. Drill into key functions
reveal src/main.py main
reveal src/app.py create_app
```

### Find patterns

```bash
# Find all authentication-related code
reveal 'ast://./src?name=*auth*'

# Find complex functions (likely important or buggy)
reveal 'ast://./src?complexity>10'

# Find long functions (refactor candidates)
reveal 'ast://./src?lines>50'

# Combine filters (complex AND long)
reveal 'ast://./src?complexity>10&lines>50'
```

### Understand architecture

```bash
# See all imports
reveal imports://src/

# Find circular dependencies
reveal 'imports://src?circular'

# Check layer violations
reveal 'imports://src?violations'

# Get statistics
reveal stats://./src
```

### Cross-codebase analysis

```bash
# Find all get_* methods across entire project
reveal 'ast://.?name=get_*' --format=json | \
  jq -r '.results[] | "\(.file):\(.line) \(.name)"'

# Count functions per file
reveal 'ast://./src?type=function' --format=json | \
  jq -r '.results[].file' | sort | uniq -c | sort -rn

# Find largest classes (potential god objects)
reveal 'ast://./src?type=class' --format=json | \
  jq -r '[.results[] | {name, file, lines: .line_count}] |
         sort_by(.lines) | reverse | .[0:10][] |
         "\(.file) - \(.name) (\(.lines) lines)"'
```

---

## Debugging & Troubleshooting

### Python environment issues

```bash
# Full health check
reveal python://doctor

# Check specific module (import shadowing?)
reveal python://module/requests

# Analyze sys.path conflicts
reveal python://syspath

# Find stale bytecode
reveal python://debug/bytecode

# See virtual environment status
reveal python://venv

# Check installed packages
reveal python://packages
```

### Detect import shadowing

```bash
# Is your local module hiding a pip package?
reveal python://module/requests

# Output shows:
# - import_location: Where Python actually imports from
# - pip_package: Where pip thinks it is
# - conflicts: [] or [{ type: "cwd_shadowing", ... }]
# - recommendations: Exact fix if there's a problem
```

### Find the code behind the error

```bash
# Traceback says "file.py, line 166" — go straight to the enclosing function
reveal src/app.py :166              # element at line 166
reveal src/app.py 166               # bare integer works too

# grep -n gives you line numbers — use them directly
grep -n "raise ValueError" src/app.py
reveal src/app.py :73               # jump to that element

# Locate error handling by name
reveal 'ast://src?name=*error*'
reveal 'ast://src?name=*exception*'

# Find specific handler
reveal src/handlers.py error_handler

# Check environment configuration
reveal env://
reveal env://DATABASE_URL
```

### Self-referential diagnosis

```bash
# Use reveal to extract reveal's own implementation
reveal reveal://rules/links/L001.py _extract_anchors_from_markdown

# Extract a class definition
reveal reveal://analyzers/markdown.py MarkdownAnalyzer

# Learn adapter patterns by extracting adapter code
reveal reveal://adapters/reveal.py get_element
```

### Cross-adapter orientation

```bash
# See how the adapters fit together
reveal help://relationships

# Find the best adapter family for the task
reveal help://adapters
```

**Why this matters:** Reveal is strongest when you combine adapters instead of
staying in one domain. `help://relationships` is the fastest map of the
high-value combinations.

---

## Large-Function Navigation

When a function is too large to read line by line, use the nav flags to inspect
control flow, context, and data flow first.

```bash
# Control-flow skeleton
reveal src/processor.py process_batch --outline

# Exact context around a line from a stack trace
reveal src/processor.py :123 --around
reveal src/processor.py :123 --around 10

# Branching and exception skeletons
reveal src/processor.py process_batch --ifmap
reveal src/processor.py process_batch --catchmap

# Exit points and reachability verdict
reveal src/processor.py process_batch --exits
reveal src/processor.py process_batch --flowto

# Variable and dependency analysis for a sub-range
reveal src/processor.py process_batch --varflow result
reveal src/processor.py process_batch --deps --range 20-80
reveal src/processor.py process_batch --mutations --range 20-80

# Scope lookup from a line number
reveal src/processor.py :123 --scope
```

**Why this matters:** these commands let you debug and refactor giant functions
the way experienced engineers actually do it: structure first, then the one
branch, variable, or range that matters.

---

## Refactoring & Quality

### Find technical debt

```bash
# Quality hotspots (worst files first)
reveal hotspots ./src

# Complex functions across codebase
reveal 'ast://./src?complexity>10'

# Long functions
reveal 'ast://./src?lines>100'

# Code golf (complex but short - suspicious)
reveal 'ast://./src?complexity>10&lines<50'
```

### Find testability pressure

```bash
# What do tests patch most often?
reveal 'patches://tests?group=target&limit=20'

# Which tests need many patches?
reveal 'patches://tests?group=test&min=3'

# Join patch pressure with production boundary fan-out
reveal testability src --tests tests
reveal testability src --tests tests --top 20
reveal testability src --tests tests --format json
```

Use this before refactoring patch-heavy test areas. The report is advisory:
mocking an external API, clock, filesystem, DNS, or certificate probe can be
correct. The strongest signal is repeated private/internal patching that
overlaps with production functions touching several runtime boundaries.

Follow up on a reported function:

```bash
reveal src/module.py function_name --boundary
reveal src/module.py function_name --sideeffects
reveal 'calls://src?callees=function_name'
```

### Complexity analysis

```bash
# Find complex functions (industry standard: >10 needs refactoring)
reveal 'ast://./src?complexity>10'

# The danger zone - extremely complex functions
reveal 'ast://./src?complexity>20'

# Find functions that are BOTH complex AND long (prime refactoring targets)
reveal 'ast://./src?complexity>15&lines>100'

# Top 10 most complex functions in your codebase
reveal 'ast://./src?type=function' --format=json | \
  jq -r '[.results[] | {name, file, complexity, lines: .line_count}] |
         sort_by(.complexity) | reverse | .[0:10][] |
         "\(.file) - \(.name) (complexity: \(.complexity), lines: \(.lines))"'

# Find god functions (both metrics high)
reveal 'ast://./src?complexity>30&lines>150'

# Simple but long - candidate for splitting or inlining
reveal 'ast://./src?complexity<5&lines>50'
```

### Combined AST filters

```bash
# Name glob + complexity — find complex handlers specifically
reveal 'ast://src/?name=*handle*&complexity>10'

# Name glob + type — find all test functions
reveal 'ast://tests/?name=test_*&type=function'

# Decorator + complexity — complex cached functions (may be hiding cost)
reveal 'ast://src/?decorator=*cache*&complexity>5'

# Name + lines — large parse/render functions
reveal 'ast://src/?name=*parse*&lines>50&sort=-complexity'
```

### Extract a raw line range

```bash
# Get exact source lines by range — useful after diff:// or grep finds a location
reveal src/auth.py :45-70

# Combined with Class.method syntax
reveal src/auth.py :45-70  # raw lines
reveal src/auth.py MyClass.validate :45-70  # not valid — use range on file directly
```

### Decorator intelligence

```bash
# Find all @property methods
reveal 'ast://.?decorator=property'

# Find all cached functions (wildcards work!)
reveal 'ast://.?decorator=*cache*'

# Find abstract interface methods
reveal 'ast://.?decorator=abstractmethod'

# Find complex properties (code smell - properties should be simple)
reveal 'ast://.?decorator=property&lines>10'

# Find all @dataclass classes
reveal 'ast://.?decorator=dataclass&type=class'

# Analyze decorator usage across your codebase
reveal src/ --decorator-stats
```

### Navigate inside a large function (v0.72.0+)

When a function is too large to read in full, use sub-function nav flags to
understand it without reading every line.

```bash
# Control-flow skeleton — what branches and loops exist?
reveal src/processor.py process_batch --outline
# DEF process_batch  L1→L13
#   FOR  item in items  L3→L12
#     IF  item.active  L4→L12
#     ELIF  item.pending  L7→L12
#       TRY  L8→L12
#   RETURN  results  L13

# Ancestor scope for a line from a stack trace or grep result
reveal src/processor.py :5 --scope

# Trace a variable — where is it written and read?
reveal src/processor.py process_batch --varflow results

# What does a specific branch call?
reveal src/processor.py process_batch --calls 7-12
```

Workflow for a complex function:
```bash
# 1. Skeleton — find the suspicious branch
reveal src/processor.py process_batch --outline

# 2. Zoom in — what calls happen in lines 7-12?
reveal src/processor.py process_batch --calls 7-12

# 3. Trace a variable through the whole function
reveal src/processor.py process_batch --varflow result

# 4. Read only the branch you care about
reveal src/processor.py process_batch --range 7-12

# Class.method syntax works everywhere
reveal src/processor.py MyClass.process_batch --outline
```

### Semantic diff — what actually changed

```bash
# Structural diff between branches (functions added/removed/changed + complexity delta)
reveal diff://git://main/.:git://HEAD/.

# Per-file commit diff — see exactly which functions changed and how
reveal diff://git://HEAD~1/src/auth.py:src/auth.py

# CI gate: fail if any function's complexity increased by more than 5
reveal diff://git://main/.:git://HEAD/. --format json | \
  jq '.diff.functions[] | select(.complexity_delta > 5)'
```

### Before/after refactoring

```bash
# Before: Capture current state
reveal src/module.py function_name
reveal src/module.py --check --select C
reveal src/module.py --outline

# After: Verify improvements
reveal diff://git://HEAD/src/module.py:src/module.py
reveal src/module.py --check
reveal 'imports://src?circular'
```

### Find duplication

```bash
# Check for duplicate code
reveal src/ --check --select D

# Specific duplication check
reveal src/module.py --check --select D001,D002
```

### Trace call relationships

```bash
# Who calls this function across the whole project? (reverse/impact)
reveal 'calls://src/?target=validate_item'

# Shorthand — colon syntax (equivalent to ?target=)
reveal 'calls://src/auth.py:validate_item'

# What does this function call? (forward/dependency, builtins hidden)
reveal 'calls://src/?callees=process_request'

# Include Python builtins — useful to audit for eval/open/exec
reveal 'calls://src/?callees=process_request&builtins=true'

# Transitive: callers-of-callers (2 levels deep)
reveal 'calls://src/?target=validate_item&depth=2'

# Most-called functions in the project (coupling hotspots)
reveal 'calls://src/?rank=callers'
reveal 'calls://src/?rank=callers&top=20'

# Generate Graphviz call graph (pipe to dot)
reveal 'calls://src/?target=main&format=dot' | dot -Tsvg > callgraph.svg
```

**Before refactoring a function:** run `?target=fn` to see impact radius — everything that calls it.
**Before splitting a function:** run `?callees=fn` to see its full dependency surface.
**Dead code hunt:** if `?target=fn` returns 0 callers, it's a candidate for removal.

```bash
# Dead code: all functions defined but never called anywhere in the project
reveal 'calls://src/?uncalled'

# Functions only (skip methods and class-level definitions)
reveal 'calls://src/?uncalled&type=function'

# Top 20 most-recently-added uncalled functions
reveal 'calls://src/?uncalled&top=20'

# JSON output — pipe to jq, filter private vs public
reveal 'calls://src/?uncalled' --format json | jq '.uncalled[] | select(.is_private == false)'
```

**What to expect:** `__dunder__` methods and functions decorated with `@property`, `@classmethod`, `@staticmethod` are excluded (they're called implicitly). Functions imported under aliases are correctly resolved — `from utils import helper as h` means `helper` is treated as called when `h` is called.

```bash
# Within a single file (cheaper — no cross-file index)
reveal 'ast://src/auth.py?calls=validate_item'    # who calls it in this file?
reveal 'ast://src/auth.py?callee_of=process'      # what does process call?
reveal 'ast://src/auth.py?show=calls'             # full call graph diagram
```

---

### Trace module-level dependencies (reverse import graph)

`depends://` answers "what imports *this*?" — the complement of `imports://`.

```bash
# Who imports this module?
reveal depends://src/utils.py

# Who imports anything in models/?
reveal depends://src/models/

# Most-imported (high-coupling) modules — change these carefully
reveal 'depends://src?top=10'

# Full reverse dependency graph (pipe to Graphviz)
reveal 'depends://src?format=dot' | dot -Tsvg > deps.svg
```

**Key use cases:**
- **Impact analysis before refactoring** — run `depends://src/utils.py` to see every importer before touching a module
- **Safe deletion** — verify `count: 0` before removing a module
- **Coupling audit** — `?top=N` ranks modules by fan-in; high fan-in = high blast radius if changed

| Adapter | Question | Direction |
|---------|----------|-----------|
| `imports://src` | What does this code import? | Forward |
| `depends://src/module.py` | What imports this module? | Reverse |
| `calls://src/?target=fn` | Who calls this function? | Reverse (function level) |

**Limitations:** Dynamic imports (`importlib.import_module`) and `TYPE_CHECKING`-only imports are not tracked.

---

## Documentation Maintenance

### Validate markdown frontmatter

```bash
# Session READMEs
reveal sessions/*/README.md --validate-schema session

# Hugo blog posts
reveal content/posts/*.md --validate-schema hugo

# Jekyll/GitHub Pages
reveal _posts/*.md --validate-schema jekyll

# MkDocs
reveal docs/**/*.md --validate-schema mkdocs
```

### Find docs by metadata

```bash
# Find all docs on a topic
reveal 'markdown://docs/?topics=authentication'

# Find incomplete docs
reveal 'markdown://docs/?status=draft'

# Find docs with specific tag
reveal 'markdown://?tags=python'

# Find docs missing metadata
reveal 'markdown://?!topics'
```

### Search doc body text

```bash
# Find docs containing a keyword in the body (not just frontmatter)
reveal 'markdown://docs/?body-contains=deployment'

# AND logic: both terms must appear
reveal 'markdown://docs/?body-contains=authentication&body-contains=oauth'

# Combine with frontmatter filter: docs about auth that mention oauth
reveal 'markdown://docs/?topics=authentication&body-contains=oauth'
```

### Count values across a field

```bash
# See frequency of each value for a frontmatter field
reveal 'markdown://docs/?aggregate=type'

# Count by topic tag (list fields are expanded per item)
reveal 'markdown://docs/?aggregate=beth_topics'

# Count by status
reveal 'markdown://docs/?aggregate=status'
```

**Output:** Sorted frequency table. Great for understanding your doc taxonomy.

### Build a link graph

```bash
# Which docs link to which? (forward edges + backlinks)
reveal 'markdown://docs/?link-graph'

# Grep-friendly tab-separated edges for scripting
reveal 'markdown://docs/?link-graph' --format=grep

# Pipe to see which docs have the most backlinks
reveal 'markdown://docs/?link-graph' --format=grep | cut -f2 | sort | uniq -c | sort -rn
```

**Output:** Per-file: links-to list, linked-by count. Plus isolated files (no links in or out — orphaned docs).

### Validate links

```bash
# Check all link rules
reveal docs/ --check --select L

# Fast check (internal links + routing only)
reveal docs/ --check --select L001,L003

# Extract all links
reveal README.md --links

# Filter by type
reveal README.md --links --link-type=external
reveal README.md --links --link-type=internal

# Find broken links
reveal docs/*.md --links 2>/dev/null | grep BROKEN
```

### Extract content

```bash
# See frontmatter structure
reveal docs/page.md --frontmatter

# Get as JSON for scripting
reveal docs/page.md --frontmatter --format=json

# All code blocks
reveal README.md --code

# Only Python examples
reveal README.md --code --language=python
```

---

## JSON Navigation

The `json://` adapter turns reveal into a JSON explorer - no jq required for basic operations.

### Explore unknown JSON structure

```bash
# What's in this JSON file?
reveal json://config.json?schema

# Output:
# Schema:
# {
#   "database": {
#     "host": "str",
#     "port": "int",
#     "credentials": {
#       "username": "str",
#       "password": "str"
#     }
#   },
#   "features": "Array[str]"
# }
```

**Why this matters:** AI agents constantly work with `package.json`, `tsconfig.json`, API responses. Schema inference shows structure without reading the whole file.

### Navigate to specific keys

```bash
# Get nested value
reveal json://package.json/scripts
reveal json://config.json/database/host

# Array access
reveal json://data.json/users/0           # First user
reveal json://data.json/users[0:3]        # First 3 users (slice)
```

### Search inside JSON (gron-style)

```bash
# Flatten to grep-able format
reveal json://config.json?flatten

# Output:
# json = {}
# json.database = {}
# json.database.host = "localhost"
# json.database.port = 5432
# json.database.credentials = {}
# json.database.credentials.username = "admin"

# Now search!
reveal json://config.json?flatten | grep -i password
reveal json://large-config.json?flatten | grep 'api.*key'
```

### Real-world patterns

```bash
# Explore package.json
reveal json://package.json?schema           # See structure
reveal json://package.json/dependencies     # List deps
reveal json://package.json/scripts          # See npm scripts

# Explore tsconfig.json
reveal json://tsconfig.json/compilerOptions
reveal json://tsconfig.json?flatten | grep strict

# Debug API response (saved to file)
reveal json://api-response.json?schema      # Understand structure
reveal json://api-response.json/data/0      # First result
```

**Token savings:** For AI agents, `json://?schema` gives structure understanding in ~100 tokens vs ~5000 tokens for the full file.

---

## Database Operations

### SQLite inspection

```bash
# Database overview
reveal sqlite:///path/to/app.db

# Table structure
reveal sqlite:///path/to/app.db/users

# Get as JSON
reveal sqlite:///app.db --format=json
```

### MySQL inspection (requires [database] extra)

```bash
# Database health
reveal mysql://localhost

# Performance metrics
reveal mysql://localhost/performance

# Index analysis
reveal mysql://localhost/indexes

# Slow queries
reveal mysql://localhost/slow-queries

# InnoDB status
reveal mysql://localhost/innodb
```

### Schema drift detection

```bash
# Compare database schemas
reveal diff://mysql://localhost/users:mysql://staging/users

# Compare SQLite schemas
reveal diff://sqlite://./dev.db:sqlite://./prod.db
```

---

## Spreadsheet and BI Inspection

### Explore an Excel workbook like a dataset

```bash
# Workbook overview
reveal xlsx:///data/report.xlsx

# Inspect a sheet or range
reveal xlsx:///data/report.xlsx?sheet=Summary
reveal xlsx:///data/report.xlsx?sheet=Sales&range=A1:C10

# Search across all sheets
reveal xlsx:///data/report.xlsx?search=revenue
```

### Reverse-engineer a Power BI / Power Pivot export

```bash
# Tables, columns, measures, DAX, and relationships
reveal xlsx:///data/report.xlsx?powerpivot=tables
reveal xlsx:///data/report.xlsx?powerpivot=schema
reveal xlsx:///data/report.xlsx?powerpivot=dax
reveal xlsx:///data/report.xlsx?powerpivot=relationships

# Power Query M code
reveal xlsx:///data/report.xlsx?powerquery=list
reveal xlsx:///data/report.xlsx?powerquery=show

# Named ranges and external connections
reveal xlsx:///data/report.xlsx?names=list
reveal xlsx:///data/report.xlsx?connections=show
```

**Why this matters:** this turns opaque finance and BI workbooks into something
you can inspect structurally: data model, ETL queries, and source systems.

---

## Infrastructure

### SSL certificate inspection

```bash
# Certificate overview
reveal ssl://example.com

# Non-standard port
reveal ssl://example.com:8443

# View all domains covered by certificate (SANs)
reveal ssl://example.com/san

# Certificate chain details
reveal ssl://example.com/chain

# Health check (expiry, chain verification, hostname match)
reveal ssl://example.com --check

# JSON output for CI/CD
reveal ssl://example.com --check --format=json
```

### On-disk certificate inspection

```bash
# Inspect a PEM/DER cert file directly (no network connection needed)
reveal ssl://file:///var/cpanel/ssl/apache_tls/example.com/combined
reveal ssl://file:///etc/letsencrypt/live/example.com/fullchain.pem

# Same output as live cert: health, expiry, SANs, chain count
# Combined PEM files (leaf + chain) are split automatically
```

### SSL expiry monitoring

```bash
# Check if certificate expires within 30 days
reveal ssl://example.com --check
# Exit code 0 = healthy, 1 = warning (<30 days), 2 = critical (<7 days)

# Combine with nginx config analysis
reveal /etc/nginx/nginx.conf --check  # N004 detects ACME path issues, N006 detects timeout mismatches

# Batch output shows failure reason and expiry dates inline:
# example.com    EXPIRED  3 days ago  (Jan 25, 2026)
# api.example.com    DNS FAILURE (NXDOMAIN)
# staging.example.com    WARNING  expires in 12 days  (Mar 11, 2026)
# www.example.com    OK  182 days  (Aug 27, 2026)
```

### Nginx SSL audit

```bash
# See nginx config with SSL status indicators
reveal /etc/nginx/nginx.conf

# Extract all SSL-enabled domains as ssl:// URIs
reveal /etc/nginx/nginx.conf --extract domains

# Check SSL certificates for all nginx domains (composable pipeline)
reveal /etc/nginx/nginx.conf --extract domains | reveal --stdin --check

# Show only problems (failures and warnings)
reveal /etc/nginx/nginx.conf --extract domains | reveal --stdin --check --only-failures

# Quick summary (counts only)
reveal /etc/nginx/nginx.conf --extract domains | reveal --stdin --check --summary

# Find certs expiring within 30 days
reveal /etc/nginx/nginx.conf --extract domains | reveal --stdin --check --expiring-within=30
```

### Nginx ACL, routing, and ACME audit

```bash
# Check nobody-user ACL access on all docroots (required for nginx ACME renewal)
reveal /etc/nginx/conf.d/users/USERNAME.conf --check-acl

# Find all ACME challenge root paths + ACL status in one table
reveal /etc/nginx/conf.d/users/USERNAME.conf --extract acme-roots

# Detect location block routing surprises (prefix overlap, regex shadowing prefix)
reveal /etc/nginx/conf.d/users/USERNAME.conf --check-conflicts

# Filter output to a single server block (essential for 1,500-line cPanel user configs)
reveal /etc/nginx/conf.d/users/USERNAME.conf --server-name example.com

# Full composed audit: ACME paths + ACL status + live SSL cert per domain
reveal /etc/nginx/conf.d/users/USERNAME.conf --validate-nginx-acme

# On large configs (500+ domains), show only failures
reveal /etc/nginx/conf.d/users/USERNAME.conf --validate-nginx-acme --only-failures

# Disk cert vs live cert comparison (detect "AutoSSL renewed but nginx not reloaded")
reveal /etc/nginx/conf.d/users/USERNAME.conf --cpanel-certs
# ⚠️ STALE (reload nginx) when serial numbers differ; exit 2 on stale or expired

# Scan nginx error log for ACME/SSL failure patterns (retroactive diagnosis)
reveal /etc/nginx/conf.d/users/USERNAME.conf --diagnose
# Groups by domain: permission_denied (exit 2), ssl_error (exit 2), not_found (info)
```

### cPanel user environment

```bash
# Overview: domain count, SSL summary, nginx config path
reveal cpanel://USERNAME

# All domains with docroots and type (addon/subdomain/main)
reveal cpanel://USERNAME/domains

# Disk cert health per domain
reveal cpanel://USERNAME/ssl

# DNS-verified: exclude NXDOMAIN (former-customer) domains from counts
# Useful when large accounts have inactive domains with expiring certs
reveal cpanel://USERNAME/ssl --dns-verified

# Live cert check: for each non-ok disk cert, also probe the live TLS handshake
# Shows ↳ live: Nd (date) lines — confirms whether cert on disk is actually in use
reveal cpanel://USERNAME/ssl --check-live

# Only failures, with live probe (fast triage for large accounts)
reveal cpanel://USERNAME/ssl --only-failures --check-live

# Nobody ACL check on every domain docroot
reveal cpanel://USERNAME/acl-check

# Full audit: SSL + ACL + nginx ACME in one pass (exit 2 on any failure)
reveal cpanel://USERNAME --audit

# JSON output for scripting
reveal cpanel://USERNAME/ssl --format=json
```

### Batch SSL checking with @file

```bash
# Create a domain list file (one per line, comments with #)
cat > domains.txt << 'EOF'
# Production domains
ssl://api.example.com
ssl://www.example.com
ssl://app.example.com

# Staging
ssl://staging.example.com
EOF

# Check all domains from file
reveal @domains.txt --check

# Show only failures
reveal @domains.txt --check --only-failures

# Filter to expiring soon
reveal @domains.txt --check --expiring-within=14
```

---

## Session Analysis

The `claude://` adapter reads Claude Code session files (`.jsonl` in `~/.claude/projects/`).

### Browse sessions

```bash
# List all sessions (newest first)
reveal claude://

# Filter by project
reveal 'claude://?filter=reveal'

# Sessions from today only
reveal 'claude://?since=today'
```

### Search across sessions

```bash
# Find all sessions that mention a keyword
reveal 'claude://?search=migration'

# Scope to recent sessions (recommended for large histories)
reveal 'claude://?search=authentication&since=today'
reveal 'claude://?search=deployment&since=2026-03-01'

# Path-style alias (same result)
reveal 'claude://search/migration'
```

**Why:** With 2,000+ sessions, scanning manually doesn't scale. `?search=` pre-filters with parallel byte-scan (~0.7s for 2,700 files).

### Track file history across sessions

```bash
# Which sessions touched this file?
reveal 'claude://files/src/auth.py'

# Partial paths work (matches absolute paths)
reveal 'claude://files/auth.py'

# Scope to recent sessions
reveal 'claude://files/operations.py?since=today'
```

**What you get:** Session name, project, date, and Read/Edit/Write counts per session. Answers "what sessions changed this?" at the AI-interaction level — `git log` doesn't capture this.

### Inspect a session

```bash
# Overview (badge, files touched, tools used)
reveal claude://my-session-name

# Timeline (message sequence)
reveal 'claude://my-session-name?timeline'

# Files touched (Read/Write/Edit breakdown)
reveal 'claude://my-session-name?files'

# Errors encountered
reveal 'claude://my-session-name?errors'

# Workflow (tool call sequence, collapsed duplicates)
reveal 'claude://my-session-name?workflow'
```

### Session tail / recovery

```bash
# Last assistant message (fast session recovery)
reveal 'claude://my-session-name?last'

# Last 5 turns
reveal 'claude://my-session-name?tail=5'
```

### Inspect Claude install state

```bash
# Where does Claude store everything?
reveal claude://info

# MCP registrations and install flags
reveal claude://config
reveal 'claude://config?key=installMethod'

# Prompt history across all projects
reveal claude://history
reveal 'claude://history?search=deploy'

# Saved plans, memory, agents, and hooks
reveal claude://plans
reveal claude://memory
reveal claude://agents
reveal claude://hooks
```

**Why this matters:** `claude://` is not only for replaying sessions. It also
gives you observability into your Claude Code install, memory footprint, and
automation surface.

---

## Pipeline Integration

### Unix pipelines

```bash
# Process changed files
git diff --name-only | reveal --stdin --outline

# Find complex functions in changed files
git diff --name-only origin/main | grep "\.py$" | reveal --stdin --format=json

# CI/CD quality gate
git diff --name-only origin/main | reveal --stdin --check --format=grep
```

### JSON processing

```bash
# Extract function info
reveal src/app.py --format=json | jq '.functions'

# Find large functions
reveal src/ --format=json | jq '.functions[] | select(.line_count > 100)'

# Get complexity metrics
reveal stats://src/ --format=json | jq '.quality_score'
```

### Batch operations

```bash
# Check multiple files
find src/ -name "*.py" -print0 | xargs -0 -I {} reveal {} --check

# Process all markdown
fd -e md | reveal --stdin --validate-schema hugo

# Get structure of all files
fd -e py | reveal --stdin --format=json > structure.json
```

### URI batch processing

```bash
# Check multiple SSL certificates
echo -e "ssl://example.com\nssl://api.example.com\nssl://staging.example.com" | reveal --stdin

# Mix file paths, URIs, and env vars in the same batch — all processed in one pass
echo -e "src/auth.py\nssl://prod.example.com\nenv://DATABASE_URL" | reveal --stdin

# Scan all domains from nginx config
grep -h "server_name" /etc/nginx/sites-enabled/* | awk '{print $2}' | \
  sed 's/;$//' | sed 's/^/ssl:\/\//' | reveal --stdin --check

# Batch SSL health checks with JSON output
cat domains.txt | sed 's/^/ssl:\/\//' | reveal --stdin --format=json | \
  jq 'select(.status.health != "healthy")'
```

### Extract-then-batch pipeline

Combine `--extract` with `--stdin --batch` to build composable check pipelines.

```bash
# Extract domains from nginx config, then batch-check their SSL certs
reveal /etc/nginx/conf.d/app.conf --extract domains | \
  sed 's/^/ssl:\/\//' | reveal --stdin --check

# Show only SSL failures from all configs in a directory
reveal /etc/nginx/sites-enabled/ --extract domains | \
  sed 's/^/ssl:\/\//' | reveal --stdin --check --only-failures

# Extract from cPanel domain list, batch-check SSL
reveal cpanel://USERNAME/domains --format=json | \
  jq -r '.domains[].domain' | sed 's/^/ssl:\/\//' | reveal --stdin --check

# Use cpanel://USER/ssl --extract for already-structured data
reveal cpanel://USERNAME/ssl --format=json | \
  jq -r '.certs[] | select(.status != "ok") | .domain' | \
  sed 's/^/ssl:\/\//' | reveal --stdin --check-live

# Quality check with severity filter (only high+)
reveal src/ --check --severity high

# Full pipeline: extract domains → batch SSL → JSON → filter failures
reveal nginx.conf --extract domains | sed 's/^/ssl:\/\//' | \
  reveal --stdin --format=json | jq 'select(.status.health != "healthy")'
```

### Clipboard integration

```bash
# Copy function to clipboard
reveal src/app.py handle_request --copy

# Copy structure as JSON
reveal src/app.py --format=json --copy
```

### Format transformations

```bash
# Structure as JSON
reveal app.py --format=json

# Query with jq
reveal app.py --format=json | jq '.structure.functions | length'
reveal app.py --format=json | jq '.structure.imports[].content'

# Typed JSON (with relationships)
reveal app.py --format=typed

# Grep-compatible output
reveal app.py --format=grep
# Output: file:line:content
# Perfect for: reveal ... | grep pattern | cut -d: -f1-2
```

---

## AI Agent Patterns

### Progressive disclosure pattern

```bash
# Level 1: Structure (~100 tokens)
reveal app.py

# Level 2: Hierarchy (~150 tokens)
reveal app.py --outline

# Level 3: Specific extraction (~50 tokens)
reveal app.py process_data

# Compare: cat app.py (~7,500 tokens for 300 lines)
# Savings: 50-150x
```

### Token efficiency

```bash
# Python environment
reveal python://              # Overview (~20 tokens)
reveal python://packages      # Package list (~200 tokens)
reveal python://packages/numpy  # Specific package (~50 tokens)

# AST queries
reveal ast://./src            # All structure (~500 tokens)
reveal 'ast://./src?complexity>10'  # Just complex ones (~100 tokens)
```

### Semantic slicing

```bash
# First 5 functions only
reveal large_module.py --head 5

# Last 3 functions (bugs cluster at the bottom!)
reveal large_module.py --tail 3

# Specific range
reveal conversation.jsonl --range 48-52
```

### Query before reading

```bash
# Find relevant code without reading everything
reveal 'ast://./src?name=*config*'

# Filter by complexity
reveal 'ast://./src?complexity>5'

# Get structured output for parsing
reveal 'ast://./src?name=*auth*' --format=json
```

---

## Multi-Language Support

### Built-in analyzers (full support)

```bash
# Python, JS, TS, Rust, Go, Dockerfile, YAML, JSON, TOML, Markdown
reveal app.py            # Python
reveal config.yaml       # YAML
reveal Dockerfile        # Dockerfile with quality checks
reveal package.json      # JSON structure
reveal main.go           # Go
reveal lib.rs            # Rust
```

### Tree-sitter fallback (37+ languages)

```bash
# C, C++, Java, Ruby, PHP, Scala, Haskell, OCaml, Lua...
reveal Main.java         # Works!
reveal app.rb            # Works!
reveal script.lua        # Works!

# Check what's supported
reveal --list-supported
```

### Nginx configuration

```bash
# See all server blocks
reveal nginx.conf

# Filter output to a single domain (essential for large cPanel user configs)
reveal /etc/nginx/conf.d/users/USERNAME.conf --domain example.com

# Extract specific server block by name
reveal nginx.conf server_myapp

# Find all upstreams
reveal nginx.conf --format=json | jq '.structure.upstreams'

# Check for common issues
reveal /etc/nginx/nginx.conf --check
# N001: Duplicate backends
# N002: SSL servers missing certificate directives
# N003: Proxy locations missing X-Real-IP, X-Forwarded-For
# N004: ACME challenge path inconsistency (cert renewal failures)
# N005: Timeout/buffer values outside safe ranges
# N006: send_timeout too short for client_max_body_size (HIGH — silent uploads)

# Large generated configs collapse repeated rules by default
reveal ea-nginx.conf --check          # N003 x2,685 shown as one summary line
reveal ea-nginx.conf --check --no-group  # expand all occurrences

# Check nobody-user ACL access (cPanel ACME requirement)
reveal /path/user.conf --check-acl

# Find ACME challenge root paths + ACL status
reveal /path/user.conf --extract acme-roots

# Detect location routing surprises (regex shadowing prefix, prefix overlap)
reveal /path/user.conf --check-conflicts

# Full audit: ACME paths + ACL + live SSL cert status per domain
reveal /path/user.conf --validate-nginx-acme
reveal /path/user.conf --validate-nginx-acme --only-failures  # filter to failures on large configs

# Disk cert vs live cert comparison
reveal /path/user.conf --cpanel-certs

# Scan nginx error log for ACME/SSL failures
reveal /path/user.conf --diagnose
```

### Jupyter notebooks

```bash
# See notebook structure
reveal analysis.ipynb

# All cells with outputs
reveal analysis.ipynb --format=json
```

---

## Advanced Multi-Adapter Patterns

### Pattern 1: The Complexity Drill-Down
**Combine**: `stats://` → `ast://` → `diff://` → `git://`

```bash
# 1. Find hotspots
reveal hotspots ./src

# 2. Identify complex functions in hotspot
reveal 'ast://src/hotspot.py?complexity>10'

# 3. Compare to previous version (did we make it worse?)
reveal diff://git://HEAD~10/src/hotspot.py:src/hotspot.py

# 4. Who wrote the complex function?
reveal git://src/hotspot.py?type=blame&element=complex_function
```

### Pattern 2: The Import Archaeology
**Combine**: `imports://` → `ast://` → `git://`

```bash
# 1. Find circular dependencies
reveal 'imports://src?circular'

# 2. Identify functions involved in cycle
reveal 'ast://src/module_a.py?type=function'
reveal 'ast://src/module_b.py?type=function'

# 3. When was the cycle introduced?
reveal git://src/module_a.py?type=history
reveal git://src/module_b.py?type=history
```

### Pattern 3: The Config Drift Detector
**Combine**: `json://` → `diff://` → `env://`

```bash
# 1. Understand config structure
reveal json://config.json?schema

# 2. Compare environments
reveal diff://json://config.dev.json:json://config.prod.json

# 3. Check environment variables
reveal env://
```

### Pattern 4: The Security Sweep
**Combine**: `ast://` → `git://` → `env://`

```bash
# 1. Check for code-level security issues (B001-B006, S701)
reveal check src/ --select B,S

# 2. Who wrote insecure code?
reveal git://src/insecure.py?type=blame&element=bad_function

# 3. Check for secrets in env
reveal env:// --format=json | jq '[.categories[] | .[] | select(.sensitive==true)]'
```

### Pattern 5: The Documentation Validator
**Combine**: `markdown://` → `ast://` → `diff://`

```bash
# 1. Check for broken links across all docs
reveal check docs/ --select L

# 2. Check frontmatter completeness
reveal check docs/ --select F

# 3. Verify docs updated with code changes
reveal diff://git://HEAD~1/docs:docs
```

---

## Token-Efficient AI Review Strategies

### Strategy 1: Progressive Disclosure

```bash
# Layer 1: Structure (~100 tokens)
reveal src/

# Layer 2: Stats (~200 tokens)
reveal stats://./src

# Layer 3: Hotspots (~500 tokens)
reveal hotspots ./src

# Layer 4: Specific file outline (~150 tokens)
reveal src/hotspot.py --outline

# Layer 5: Specific function (~50 tokens)
reveal src/hotspot.py complex_function
```

~1,000 tokens total vs ~500,000 for full file reads. **500x improvement.**

### Strategy 2: Query-Driven Exploration

```bash
# "What are the most complex functions?"
reveal 'ast://./src?complexity>15' --format=json

# "Are there circular dependencies?"
reveal 'imports://src?circular'

# "Who wrote this function?"
reveal git://src/app.py?type=blame&element=process

# "What changed between these versions?"
reveal diff://v1.py:v2.py
```

### Strategy 3: Semantic Slicing

```bash
# First 10 functions (entry points)
reveal app.py --head 10

# Last 5 functions (utilities)
reveal app.py --tail 5
```

### Strategy 4: Format + Filter Pipeline

```bash
# Extract only function names
reveal app.py --format=json | jq -r '.structure.functions[].name'

# Functions over 50 lines
reveal app.py --format=json | \
  jq -r '.structure.functions[] | select(.line_count > 50) | .name'
```

### Strategy 5: Multi-Pass Budget

- **Pass 1** (~500 tokens): Stats + hotspots
- **Pass 2** (~1,000 tokens): AST queries + imports
- **Pass 3** (~2,000 tokens): Specific files + functions
- **Pass 4** (~500 tokens): Git blame + diffs

---

## Real-World Scenarios

### Scenario: Technical Due Diligence

```bash
reveal stats://./src > due_diligence/stats.txt
reveal hotspots ./src > due_diligence/hotspots.txt
reveal 'ast://./src?complexity>20' > due_diligence/complex_functions.txt
reveal 'imports://src?circular' > due_diligence/circular_deps.txt
find src/ -name "*.py" | reveal --stdin --check --select=B,S > due_diligence/security.txt
reveal mysql://prod > due_diligence/db_health.txt
reveal git://.
```

**Risk score**: hotspots × 10 + circular deps × 20 + security issues × 50 + (100 − quality_score) × 2

### Scenario: Performance Optimization

```bash
# Find complexity hotspots
reveal 'ast://./src?complexity>20'

# Find long functions
reveal 'ast://./src?lines>100'

# Track improvement
reveal stats://./src --format=json > perf_before.json
# ... optimize ...
reveal stats://./src --format=json > perf_after.json
```

### Scenario: Security Audit

```bash
find src/ -name "*.py" | reveal --stdin --check --select=B,S
reveal env:// --format=json | jq '[.categories[] | .[] | select(.sensitive==true)]'
reveal 'imports://src' | grep -v "^from \."   # external deps
reveal git://.                                  # maintainer activity
```

**Red flags**: B001 (bare except), B005 (broken imports), hardcoded secrets, high average complexity (>10).

---

## Quick Reference

### Discovery commands

```bash
reveal .                                 # Map directory structure
reveal src/                              # Explore subdirectory
reveal 'ast://./src?name=*pattern*'      # Find by name
reveal 'ast://./src?complexity>10'       # Find by complexity
reveal 'imports://src?circular'          # Find circular imports
reveal hotspots ./src                    # Find technical debt
reveal 'calls://src/?target=fn'          # Who calls fn? (cross-file reverse)
reveal 'calls://src/file.py:fn'          # Shorthand for ?target=fn
reveal 'calls://src/?callees=fn'         # What does fn call? (cross-file forward)
reveal 'calls://src/?rank=callers'       # Most-called functions (coupling metrics)
reveal 'claude://?search=term'           # Search session history for keyword
reveal 'claude://files/path/to/file.py'  # Sessions that touched this file
reveal 'markdown://docs/?link-graph'     # Cross-file doc link graph
reveal 'markdown://docs/?aggregate=type' # Frontmatter field frequency table
```

### Inspection commands

```bash
reveal file.py                           # File structure
reveal file.py --outline                 # Hierarchical view (file-level)
reveal file.py function_name             # Extract specific code
reveal file.py function_name --outline   # Control-flow skeleton (function-level)
reveal file.py function_name --varflow x # Trace variable x reads/writes
reveal file.py :42 --scope              # Ancestor scope for line 42
reveal file.py function_name --calls 1-50  # Calls in a line range
reveal file.py --format=json             # Structured output
```

### Validation commands

```bash
reveal check file.py                     # All rules
reveal check file.py --select B,S       # Specific categories
reveal --rules                           # List all rules
reveal --explain B001                    # Explain specific rule
```

### Comparison commands

```bash
reveal diff://file1.py:file2.py          # Compare files
reveal diff://git://HEAD/.:src/          # Pre-commit check
reveal diff://git://main/.:git://feat/.  # Branch comparison
```

### Configuration commands

```bash
reveal reveal://config                   # Show active config
reveal env://                            # Environment variables
reveal python://doctor                   # Python health check
```

### AST query operators

| Operator | Example | Description |
|----------|---------|-------------|
| `name=` | `name=test_*` | Wildcard matching |
| `complexity>` | `complexity>10` | Cyclomatic complexity |
| `lines>` | `lines>50` | Function line count |
| `type=` | `type=class` | Element type |
| `depth>` | `depth>4` | Nesting depth |
| `decorator=` | `decorator=property` | Decorator filter |
| `&` | `complexity>10&lines>50` | AND logic |

### Rule categories

| Category | Description |
|----------|-------------|
| **B** | Bugs and anti-patterns |
| **S** | Security vulnerabilities |
| **C** | Complexity metrics |
| **D** | Duplicate code detection |
| **E** | Errors and syntax issues |
| **F** | Frontmatter validation |
| **I** | Import analysis |
| **L** | Link validation |
| **M** | Maintainability issues |
| **N** | Nginx configuration |
| **V** | Validation rules |

### Performance tips

```bash
# Fast mode (skip line counting, ~6x faster)
reveal src/ --fast

# Per-directory limit (stops node_modules from dominating)
reveal project/ --dir-limit 20

# Global entry limit (hard cap on total output)
reveal huge_dir/ --max-entries 100

# Control tree depth
reveal . --depth 2
```

---

## Getting Help

```bash
# List all adapters
reveal help://

# Adapter-specific help
reveal help://ast
reveal help://python
reveal help://diff

# Agent documentation
reveal --agent-help
```

---

**See also:**
- [AGENT_HELP.md](../AGENT_HELP.md) - AI agent reference
- [CONFIGURATION_GUIDE.md](CONFIGURATION_GUIDE.md) - Configuration options
