---
title: Reveal Installation Guide
type: documentation
category: installation
date: 2026-01-04
---

# Installation Guide

## Quick Install (Recommended)

**From PyPI (stable release):**
```bash
pip install reveal-cli
```

**From GitHub (latest development):**
```bash
pip install git+https://github.com/Semantic-Infrastructure-Lab/reveal.git
```

That's it! The `reveal` command is now available globally.

## Verify Installation

```bash
reveal --version          # Check version
reveal --list-supported   # See supported file types
reveal README.md          # Try on any file
```

## Alternative Methods

### From Source (Development)

```bash
git clone https://github.com/Semantic-Infrastructure-Lab/reveal.git
cd reveal
pip install -e .
```

The `-e` flag installs in "editable" mode - changes to the code take effect immediately.

### Specific Version

```bash
# Install specific tag/release
pip install git+https://github.com/Semantic-Infrastructure-Lab/reveal.git@v0.1.0

# Install specific branch
pip install git+https://github.com/Semantic-Infrastructure-Lab/reveal.git@main
```

### Using pipx (Isolated Environment)

```bash
# Install with pipx for isolated environment
pipx install git+https://github.com/Semantic-Infrastructure-Lab/reveal.git
```

## Requirements

- **Python:** 3.10 or higher
- **Dependencies:** Automatically installed (PyYAML, rich)

## What's Included by Default

Just `pip install reveal-cli` gives you everything:

**Languages (85 total — run `reveal --languages` for the live breakdown):**
- Explicit analyzers: Python, JavaScript, TypeScript, Rust, Go, C, C++, C#, Java, Ruby, PHP, Kotlin, Swift, Dart, Zig, Scala, Lua, GDScript, Bash, SQL, and more
- Markdown, JSON, JSONL, YAML, TOML, HCL/Terraform, GraphQL, Protobuf
- Nginx configs, Dockerfiles
- Office documents: Word (.docx), Excel (.xlsx), PowerPoint (.pptx)
- LibreOffice: Writer (.odt), Calc (.ods), Impress (.odp)
- All other tree-sitter grammars work immediately as a structure-only fallback - no extra installation needed, though the underlying `tree-sitter-language-pack` dependency downloads its grammar bundle from GitHub the first time it's used on a machine — see [Network Requirements](#network-requirements) below.

**URI Adapters (run `reveal --adapters` for the live, current list):**
- `help://` - Self-documenting help system
- `env://` - Environment variable inspection
- `ast://` - Code queries and semantic analysis
- `json://` - JSON navigation with path access
- `python://` - Python runtime inspection and diagnostics
- `reveal://` - Self-inspection and validation
- `stats://` - Code quality metrics and hotspot detection
- ...plus `calls://`, `git://`, `imports://`, `claude://`, `codex://`, `diff://`, `depends://`, and more

## Optional Features

### MySQL Database Inspection

For database health inspection with the `mysql://` adapter:

```bash
pip install reveal-cli[database]
```

**What you get:**
- MySQL database health monitoring and diagnostics
- Industry-standard DBA tuning ratios (table scans, thread cache efficiency, temp tables)
- Index usage analysis (most used indexes, unused indexes)
- Slow query detection and analysis (last 24 hours)
- InnoDB buffer pool metrics and lock information

**Examples:**
```bash
reveal mysql://localhost                    # Health overview
reveal mysql://localhost/performance        # Performance metrics + DBA tuning ratios
reveal mysql://localhost/indexes            # Index usage analysis
reveal mysql://localhost/slow-queries       # Slow query analysis (last 24h)
reveal mysql://localhost/innodb             # InnoDB buffer pool and locks
```

### Development Tools

For contributors:

```bash
pip install reveal-cli[dev]
```

**Includes:** pytest, pytest-cov, black, ruff

### Installing Multiple Extras

```bash
pip install reveal-cli[database,dev]
```

## Migration Note

**If you previously used `[treesitter]` extra:**

Tree-sitter is now included by default (since v0.8.0, Nov 2025). You can safely remove `[treesitter]` from your install commands - it's no longer needed, but old commands still work for backward compatibility.

**Example:**
```bash
# Old (still works, but unnecessary)
pip install reveal-cli[treesitter]

# New (recommended)
pip install reveal-cli
```

## Network Requirements

`pip install reveal-cli` needs network access to PyPI as usual. Beyond that,
reveal itself only makes network calls for explicitly network-oriented
features (`ssl://`, `domain://`, `nginx` upstream checks, `cpanel://`,
`mysql://`, the opt-in `L002` link-checker, the `reveal-mcp` server) and a
daily PyPI update check (disable with `REVEAL_NO_UPDATE_CHECK=1`).

**One thing to plan for in air-gapped or network-restricted environments**:
the `tree-sitter-language-pack` dependency does not ship every grammar
inside its wheel. The first time reveal parses a file in a language it
hasn't parsed before on that machine, the pack downloads an ~18–21MB
platform-specific grammar bundle from GitHub Releases
(`github.com` + `release-assets.githubusercontent.com`) and caches it at
`~/.cache/tree-sitter-language-pack/v<version>/`. After that first fetch,
parsing that language (and any other language already cached) works fully
offline.

If your environment can't reach GitHub at runtime (CI sandboxes, air-gapped
hosts, restrictive egress policies), pre-seed the cache while building your
base image or container, on a machine that does have network access:

```bash
pip install reveal-cli
reveal offline --languages python,javascript,go   # pre-download just what you need
reveal offline                                    # or every grammar the pack ships (306+, larger image)
reveal offline --disable-update-check             # also stop the daily PyPI version check permanently
# then copy ~/.cache/tree-sitter-language-pack/ into the restricted image
```

(`reveal offline` wraps the pack's own `download()`/`download_all()` — calling
those directly still works if you'd rather not shell out.)

If the cache isn't pre-seeded and the download fails, reveal surfaces it
rather than degrading silently: a `WARNING`-level log before the fetch
attempt, `--explain-file` reports the grammar isn't cached instead of
claiming full support, and `--format json` includes an explicit `"error"`
key instead of an ambiguous empty structure (fixed by `BACK-979`).

An egress allowlist for CI needs `pypi.org` + `files.pythonhosted.org` (pip
install) and `github.com` + `release-assets.githubusercontent.com`
(grammar bundle) — a PyPI-only allowlist will let install succeed but the
first real parse will hang or fail.

## Troubleshooting

### Permission Denied

If you get permission errors, try:
```bash
pip install --user git+https://github.com/Semantic-Infrastructure-Lab/reveal.git
```

### Command Not Found

If `reveal` is not found after installation, add to your PATH:
```bash
# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"
```

Then reload your shell:
```bash
source ~/.bashrc  # or source ~/.zshrc
```

### Upgrade to Latest

```bash
pip install --upgrade git+https://github.com/Semantic-Infrastructure-Lab/reveal.git
```

### Uninstall

```bash
pip uninstall reveal-cli
```

## Custom Plugin Directory

Create custom plugins in `~/.config/reveal/plugins/`:

```bash
mkdir -p ~/.config/reveal/plugins
cd ~/.config/reveal/plugins

# Create your plugin
cat > rust.yaml << 'EOF'
extension: .rs
name: Rust Source
icon: 🦀
levels:
  0: {name: metadata, description: "File stats"}
  1: {name: structure, description: "Code structure"}
  2: {name: preview, description: "Code preview"}
  3: {name: full, description: "Complete source"}
EOF
```

Custom plugins are automatically loaded alongside built-in plugins.

## For Projects

Add to `requirements.txt`:
```txt
reveal-cli @ git+https://github.com/Semantic-Infrastructure-Lab/reveal.git
```

Or `pyproject.toml`:
```toml
[project.dependencies]
reveal-cli = {git = "https://github.com/Semantic-Infrastructure-Lab/reveal.git"}
```

## CI/CD Integration

### GitHub Actions

```yaml
- name: Install reveal
  run: pip install reveal-cli

- name: Analyze files
  run: |
    reveal src/main.py
    reveal config.yaml
    reveal src/main.py main --format=json  # Extract main function as JSON
```

## Next Steps

After installation:

1. **Try it:** `reveal --help`
2. **Explore a file:** `reveal README.md`
3. **Extract an element:** `reveal app.py function_name`
4. **Read docs:** See [README](reveal/docs/README.md) for examples
5. **Contribute:** [Contributing Guide](CONTRIBUTING.md)

## Getting Help

- **Issues:** https://github.com/Semantic-Infrastructure-Lab/reveal/issues
- **Discussions:** https://github.com/Semantic-Infrastructure-Lab/reveal/discussions
- **Documentation:** https://github.com/Semantic-Infrastructure-Lab/reveal/tree/main/docs

---

**Having trouble?** Open an issue and we'll help!
