Getting Started

RichView takes a JSON or YAML file describing a report and renders it into a self-contained HTML file. This page walks you through installation, generating your first report, and creating a report from scratch.

Install

RichView is not yet published to npm. Install from source:

git clone https://github.com/richview-universe/richview-v2.git
cd richview-v2
pnpm install
pnpm build

After the build completes, the richview command is available through pnpm:

pnpm richview --version

Generate your first report

The repository includes example report schemas. Render one:

pnpm richview generate examples/climate-briefing.json -o out/

Open the result in your browser:

open out/climate-briefing.html    # macOS
xdg-open out/climate-briefing.html  # Linux

That HTML file is completely self-contained. All styles, scripts, chart data, and fonts are embedded. You can email it, drop it on a file server, or open it offline.

Create a report from scratch

Create a file called my-report.yaml:

title: Sales Update
subtitle: Week ending March 28, 2026
sections:
  - type: big-number
    label: Weekly Revenue
    value: "$142K"
    change:
      value: 8
      direction: up
      period: vs prior week

  - type: markdown
    content: |
      The eastern region drove most of the growth, with a 15% increase
      in new accounts. Western region was flat.

  - type: chart
    title: Revenue by Region
    chart:
      type: bar
      xAxis: { field: region }
      yAxis: { field: revenue }
      series:
        - dataKey: revenue
    data:
      type: inline
      columns: [region, revenue]
      values:
        - [East, 68000]
        - [West, 42000]
        - [Central, 32000]

  - type: table
    title: Top Accounts
    columns:
      - key: account
        label: Account
      - key: revenue
        label: Revenue
        align: right
    data:
      type: inline
      columns: [account, revenue]
      values:
        - [Acme Corp, "$24,500"]
        - [Globex, "$18,200"]
        - [Initech, "$12,800"]

Generate it:

pnpm richview generate my-report.yaml -o out/
open out/my-report.html

Scaffold a new project

The init command creates a directory with an example schema file:

pnpm richview init my-report
cd my-report

Templates are available for common report types:

pnpm richview init dashboard --template dashboard
pnpm richview init postmortem --template postmortem

Run pnpm richview init --help to see all templates.

Validate and lint

Check that a schema is valid before rendering:

pnpm richview validate my-report.yaml

Run quality checks (data quality, chart best practices, accessibility):

pnpm richview lint my-report.yaml

Fetch live data

Pull data from built-in providers and pipe it into reports:

# Stock prices (Yahoo Finance)
pnpm richview data fetch stocks AAPL -f json

# Cryptocurrency (CoinGecko)
pnpm richview data fetch crypto BTC -f json

# Weather forecast (Open-Meteo)
pnpm richview data fetch weather London -f json

Run pnpm richview data guide to see all supported data sources.

Connect to a database

Register a database connection and query it directly:

# Add a connection (requires the API server running)
pnpm richview connect add --name my-db --type postgres --database mydb --host localhost

# Test it
pnpm richview connect test <connection-id>

# Run a query
pnpm richview connect query <connection-id> "SELECT * FROM sales LIMIT 5"

See the CLI Reference for all connection options.

Three ways to use RichView

CLI (for scripts and automation)

The richview command handles generation, validation, linting, and more. Use it in shell scripts, CI pipelines, or cron jobs. Reports render locally with no network access required.

See the CLI Reference for the full command list.

MCP Server (for AI agents)

The MCP server lets AI agents in Claude Desktop, Cursor, Windsurf, or any MCP-compatible client create and manipulate reports through tool calls. The agent writes the report schema; RichView renders it.

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "richview": {
      "command": "node",
      "args": ["/path/to/richview-v2/packages/mcp-server/dist/index.js"]
    }
  }
}

See the MCP Server Guide for setup and available tools.

Web Editor (for visual editing)

A React-based editor with live preview. Add sections, edit data inline, toggle between edit and presentation mode.

For local development:

pnpm dev
# API server starts at http://localhost:4400
# Web editor starts at http://localhost:5173

See the Web Editor Guide for details.

Next steps

• Schema Reference -- all section types, data sources, and layout options
• CLI Reference -- full command list with examples
• MCP Server Guide -- MCP tools, resources, and prompts
• Agent Integration Guide -- how AI agents use RichView end-to-end
• Themes -- light/dark mode, design tokens, corporate branding
• Self-Hosting -- run your own RichView instance