---
title: CLI and MCP reference
description: Commands, flags, tools and result fields generated from the implementation.
styles: [scientific]
---

Use [the CLI walkthrough](https://richview.ai/docs/cli) or [MCP setup](https://richview.ai/docs/mcp) for the working path. This page supplies the exact vocabulary the installed command exposes. Publication goes to a [separate report server](https://richview.ai/docs/publishing).

## CLI command and flag reference

### `richview`

Rich Markdown: render, check and publish reports from your agent

| Argument | Required | Description |
| --- | --- | --- |
| `-h, --help` | no | Print help |

### `richview generate`

Write the self-contained report, or a PDF, into the report folder's Rendered/

| Argument | Required | Description |
| --- | --- | --- |
| `input` | yes | The report's `.rmd`, saved in its own folder (a folder holding one `.rmd` also works) |
| `--style` | no | Style (a builtin name or a file in the report folder) replacing the source's `styles` for this call; repeatable |
| `--connectors` | no | Trusted `connectors.toml` binding the names in `report.connectors.yaml` to data sources Environment: `RICHVIEW_CONNECTORS`. |
| `-o, --output` | no | File name inside Rendered/; a name ending in .pdf implies --to pdf |
| `--to` | no | Write the interactive report (default) or a PDF printed by a local Chromium-family browser Values: `report`, `pdf`. |
| `--page` | no | Paper size of a PDF Values: `a4`, `letter`. |
| `--browser` | no | Chromium, Google Chrome or Microsoft Edge executable for PDF output (or RICHVIEW_BROWSER) |
| `--settle-timeout` | no | Seconds a PDF waits for fonts and charts to settle |
| `--format` | no | `pretty` for people, `json` for agents Values: `pretty`, `json`. |
| `-h, --help` | no | Print help (see more with '--help') |

### `richview validate`

Check the structure of a report without rendering it

| Argument | Required | Description |
| --- | --- | --- |
| `input` | yes | The report's `.rmd`, saved in its own folder (a folder holding one `.rmd` also works) |
| `--publish` | no | Also apply the publish rules: title, description, version and a valid slug Values: `true`, `false`. |
| `--format` | no | `pretty` for people, `json` for agents Values: `pretty`, `json`. |
| `-h, --help` | no | Print help |

### `richview check`

Render the report and return every diagnostic and each chart's geometry

| Argument | Required | Description |
| --- | --- | --- |
| `input` | yes | The report's `.rmd`, saved in its own folder (a folder holding one `.rmd` also works) |
| `--style` | no | Style (a builtin name or a file in the report folder) replacing the source's `styles` for this call; repeatable |
| `--connectors` | no | Trusted `connectors.toml` binding the names in `report.connectors.yaml` to data sources Environment: `RICHVIEW_CONNECTORS`. |
| `--chart-width` | no | Measure charts at this width in pixels instead of the widths readers get; repeatable |
| `--format` | no | `pretty` for people, `json` for agents Values: `pretty`, `json`. |
| `-h, --help` | no | Print help |

### `richview init`

Start a report folder from the template, never overwriting

| Argument | Required | Description |
| --- | --- | --- |
| `dir` | no | Folder to create; defaults to the report name |
| `--name` | no | Name of the report file |
| `--format` | no | `pretty` for people, `json` for agents Values: `pretty`, `json`. |
| `-h, --help` | no | Print help |

### `richview learn`

Print the authoring guide, or one section of it

| Argument | Required | Description |
| --- | --- | --- |
| `section` | no | grammar, chart-contract, style, workflow or anti-slop |
| `-h, --help` | no | Print help |

### `richview mcp`

Serve the RichView tools to an agent over MCP (stdio)

| Argument | Required | Description |
| --- | --- | --- |
| `-h, --help` | no | Print help |

### `richview publish`

Publish a version of the report to a RichView server

| Argument | Required | Description |
| --- | --- | --- |
| `input` | yes | The report's `.rmd`, saved in its own folder (a folder holding one `.rmd` also works) |
| `--style` | no | Style (a builtin name or a file in the report folder) replacing the source's `styles` for this call; repeatable |
| `--connectors` | no | Trusted `connectors.toml` binding the names in `report.connectors.yaml` to data sources Environment: `RICHVIEW_CONNECTORS`. |
| `--server` | no | Server URL (https, or http on loopback) Environment: `RICHVIEW_SERVER`. |
| `--choose-server` | no | Choose and remember a publish server again (without RICHVIEW_SERVER) Values: `true`, `false`. |
| `--token` | no | Bearer token of the server Environment: `RICHVIEW_TOKEN`. |
| `--slug` | no | Address of the report; defaults to the frontmatter slug, then the title |
| `--new` | no | Create a report address the server has not stored before Values: `true`, `false`. |
| `--format` | no | `pretty` for people, `json` for agents Values: `pretty`, `json`. |
| `-h, --help` | no | Print help |

### `richview serve`

Preview the report in a browser and reload it when the folder changes

| Argument | Required | Description |
| --- | --- | --- |
| `input` | yes | The report's `.rmd`, saved in its own folder (a folder holding one `.rmd` also works) |
| `--style` | no | Style (a builtin name or a file in the report folder) replacing the source's `styles` for this call; repeatable |
| `--connectors` | no | Trusted `connectors.toml` binding the names in `report.connectors.yaml` to data sources Environment: `RICHVIEW_CONNECTORS`. |
| `-p, --port` | no |  |
| `--bind` | no |  |
| `-h, --help` | no | Print help |

### `richview report`

Delete, pin, unpin or regenerate a stored report on a server

| Argument | Required | Description |
| --- | --- | --- |
| `-h, --help` | no | Print help |

### `richview report delete`

Delete a version for good; its address answers 410 and it can never be published again

| Argument | Required | Description |
| --- | --- | --- |
| `slug` | yes |  |
| `version` | yes |  |
| `--yes` | no | Delete without asking Values: `true`, `false`. |
| `--server` | no | Server URL (https, or http on loopback) Environment: `RICHVIEW_SERVER`. |
| `--token` | no | Bearer token of the server Environment: `RICHVIEW_TOKEN`. |
| `--format` | no | `pretty` for people, `json` for agents Values: `pretty`, `json`. |
| `-h, --help` | no | Print help |

### `richview report pin`

Make a version the one the report address serves

| Argument | Required | Description |
| --- | --- | --- |
| `slug` | yes |  |
| `version` | yes |  |
| `--server` | no | Server URL (https, or http on loopback) Environment: `RICHVIEW_SERVER`. |
| `--token` | no | Bearer token of the server Environment: `RICHVIEW_TOKEN`. |
| `--format` | no | `pretty` for people, `json` for agents Values: `pretty`, `json`. |
| `-h, --help` | no | Print help |

### `richview report unpin`

Serve the highest release version again

| Argument | Required | Description |
| --- | --- | --- |
| `slug` | yes |  |
| `--server` | no | Server URL (https, or http on loopback) Environment: `RICHVIEW_SERVER`. |
| `--token` | no | Bearer token of the server Environment: `RICHVIEW_TOKEN`. |
| `--format` | no | `pretty` for people, `json` for agents Values: `pretty`, `json`. |
| `-h, --help` | no | Print help |

### `richview report regenerate`

Re-render a stored version with this engine and say whether the HTML changes; stores nothing

| Argument | Required | Description |
| --- | --- | --- |
| `slug` | yes |  |
| `version` | yes |  |
| `--server` | no | Server URL (https, or http on loopback) Environment: `RICHVIEW_SERVER`. |
| `--token` | no | Bearer token of the server Environment: `RICHVIEW_TOKEN`. |
| `--format` | no | `pretty` for people, `json` for agents Values: `pretty`, `json`. |
| `-h, --help` | no | Print help |

### `richview server`

Run RichView Cowork, the report server

| Argument | Required | Description |
| --- | --- | --- |
| `-p, --port` | no |  Environment: `PORT`. |
| `--bind` | no |  Environment: `RICHVIEW_BIND`. |
| `--data-dir` | no |  Environment: `RICHVIEW_DATA_DIR`. |
| `--token` | no |  Environment: `RICHVIEW_TOKEN`. |
| `--public-url` | no |  Environment: `RICHVIEW_PUBLIC_URL`. |
| `--report-origin` | no | The origin that serves report pages, apart from the app's. Defaults to this host on --report-port Environment: `RICHVIEW_REPORT_ORIGIN`. |
| `--report-port` | no | The port of the report listener; defaults to the port after --port (any free port for 0) Environment: `RICHVIEW_REPORT_PORT`. |
| `--quota-bytes` | no | Most bytes the report store may hold; a publication past it fails with `publish.quota` Environment: `RICHVIEW_QUOTA_BYTES`. |
| `--default-visibility` | no | Who can read a report until its owner shares it: private, org or public Environment: `RICHVIEW_DEFAULT_VISIBILITY`. |
| `--admin-email` | no | Creates this admin on first start when the server has no people yet; the password comes from RICHVIEW_ADMIN_PASSWORD Environment: `RICHVIEW_ADMIN_EMAIL`. |
| `-h, --help` | no | Print help |

### `richview asset`

Upload, verify and abort integrity-pinned remote data and media

| Argument | Required | Description |
| --- | --- | --- |
| `-h, --help` | no | Print help |

### `richview asset put`

Upload a data or media file and print its integrity-pinned reference

| Argument | Required | Description |
| --- | --- | --- |
| `file` | yes |  |
| `--to` | yes | Store profile name |
| `--public` | no | Write under the public prefix with immutable caching (private by default) Values: `true`, `false`. |
| `--type` | no | Media type when the extension is ambiguous, for example audio/webm |
| `--stores` | no | Store profiles file [default: $RICHVIEW_STORES, then $XDG_CONFIG_HOME/richview/stores.yaml] |
| `--format` | no |  Values: `pretty`, `json`. |
| `-h, --help` | no | Print help |

### `richview asset verify`

Check stored objects against reference files (YAML or JSON)

| Argument | Required | Description |
| --- | --- | --- |
| `references` | yes |  |
| `--to` | no | Store profile that signs requests for private references |
| `--hash` | no | Stream each object and compare its SHA-256 Values: `true`, `false`. |
| `--stores` | no | Store profiles file [default: $RICHVIEW_STORES, then $XDG_CONFIG_HOME/richview/stores.yaml] |
| `--format` | no |  Values: `pretty`, `json`. |
| `-h, --help` | no | Print help |

### `richview asset abort`

Abort journaled multipart uploads (all, or those whose SHA-256 starts with a prefix)

| Argument | Required | Description |
| --- | --- | --- |
| `sha256` | no |  |
| `--to` | no | Only uploads to this store profile |
| `--stores` | no | Store profiles file [default: $RICHVIEW_STORES, then $XDG_CONFIG_HOME/richview/stores.yaml] |
| `--format` | no |  Values: `pretty`, `json`. |
| `-h, --help` | no | Print help |

### `richview image`

Search Unsplash and place a credited photo in a report

| Argument | Required | Description |
| --- | --- | --- |
| `-h, --help` | no | Print help |

### `richview image search`

Search Unsplash and list candidate photos (does not register a download)

| Argument | Required | Description |
| --- | --- | --- |
| `query` | yes |  |
| `--orientation` | no |  Values: `landscape`, `portrait`, `squarish`. |
| `--per-page` | no | Results to return, from 1 to 10 |
| `--format` | no |  Values: `text`, `json`. |
| `-h, --help` | no | Print help (see more with '--help') |

### `richview image use`

Choose a photo: register the download once and print the YAML with its credit

| Argument | Required | Description |
| --- | --- | --- |
| `photo_id` | yes |  |
| `--width` | no | Requested image width in pixels; the file is never enlarged past the original |
| `--alt` | no | Alt text; defaults to the photo's own description |
| `--as` | no | A fenced image block or a title_image frontmatter mapping Values: `block`, `title-image`. |
| `--format` | no |  Values: `text`, `json`. |
| `-h, --help` | no | Print help (see more with '--help') |



## MCP over standard input/output

Configure a stdio server with the absolute executable path and the argument `mcp`. Standard output carries newline-framed JSON-RPC replies. [MCP setup](https://richview.ai/docs/mcp) explains configuration and an example render request.

### `richview_learn`

Returns RichView's authoring guide, or one section of it. Call this first. Same text as `richview learn`.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `section` | `grammar`, `chart-contract`, `style`, `workflow`, `anti-slop` | no |  |

### `richview_validate`

Checks a report's structure and files without rendering it. With publish: true it adds the publish rules. Same result as `richview validate`.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `inputPath` | string | yes | The report's .rmd, saved in its own report folder |
| `publish` | boolean | no | Also apply the publish rules: title, description, version and a valid slug |

### `richview_check`

Renders the saved report and checks provenance and chart geometry: clipping, collisions and dropped labels. Read structuredContent.status and diagnostics, repair warnings/errors, and check again after the final edit. A report finding returns isError: false; status: clean means no warnings or errors. Same result as `richview check`.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `chartWidth` | number | no | Measure charts at this width in pixels instead of the widths readers get |
| `inputPath` | string | yes | The report's .rmd, saved in its own report folder |
| `styles` | array of string | no | Styles (a builtin name or a file in the report folder) replacing the source's `styles` for this call |

### `richview_render`

Writes the self-contained HTML report, or a PDF printed by a local Chromium-family browser, into the report folder's Rendered/. Run richview_check after the final source edit for geometry and provenance findings before generating. Its result has ok, status, output (the file written) and the render diagnostics. Same result as `richview generate`.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `inputPath` | string | yes | The report's .rmd, saved in its own report folder |
| `output` | `report`, `pdf` | no | report (default) or pdf |
| `outputName` | string | no | File name inside Rendered/; a .pdf name implies pdf |
| `page` | `a4`, `letter` | no |  |
| `styles` | array of string | no | Styles (a builtin name or a file in the report folder) replacing the source's `styles` for this call |

### `richview_publish`

Publishes a version of the report to the named RichView server. The token comes from the host environment (RICHVIEW_TOKEN), never from arguments. Same result as `richview publish`.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `inputPath` | string | yes | The report's .rmd, saved in its own report folder |
| `new` | boolean | no | Create a report address the server has not stored before |
| `server` | string | no | Server URL; defaults to RICHVIEW_SERVER and must equal it when that is set, so the token only goes to the configured server |
| `slug` | string | no |  |

### `richview_asset_put`

Upload a local data or media file to a configured S3-compatible store and return its integrity-pinned reference {url, bytes, sha256, type, visibility}. Private unless public is true. Calling again resumes an interrupted upload or reports the stored object. Progress notifications follow the request's progressToken.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `path` | string | yes | Local file to upload |
| `public` | boolean | no | Serve under the public prefix with immutable caching |
| `store` | string | yes | Store profile name from stores.yaml |
| `type` | string | no | Media type when the extension is ambiguous |

### `richview_asset_verify`

Check a stored object against its reference: HEAD status, size, type and range support; with hash, stream the object and compare its SHA-256. Private references need store.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `asset` | object | yes | Reference {url, bytes, sha256, type, visibility} |
| `hash` | boolean | no |  |
| `store` | string | no | Store profile that signs requests for private references |

### `richview_image_search`

Search Unsplash for photos. Returns candidates {id, description, author, author_url, width, height, color, thumb, regular, unsplash_url}. Show the user the photographer for each candidate and let them choose; searching does not register a download. Needs UNSPLASH_ACCESS_KEY in the server environment.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `orientation` | `landscape`, `portrait`, `squarish` | no |  |
| `per_page` | integer | no | Results to return (default 6) |
| `query` | string | yes | What the photo should show |

### `richview_image_use`

Use a chosen Unsplash photo: registers the download with Unsplash once (as the API guidelines require) and returns ready-to-paste YAML in `yaml`, an `image` block or a `title_image` frontmatter mapping, with a hotlinked src, width, height, the photo's dominant `color` (#rrggbb, omitted if the API gives none) and a visible credit (Photo by <name> on Unsplash). Reports may hotlink only credited images.unsplash.com photos. Paste the YAML into the .rmd unchanged and never download or rehost the image. Call it only for a photo that will appear in the report, once per photo. If it fails during download tracking it returns an error without YAML; retrying is safe but may count the download twice.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `alt` | string | no | Alt text; defaults to the photo's description |
| `as` | `block`, `title-image` | no | image fence (default) or title_image frontmatter |
| `photo_id` | string | yes | id from richview_image_search |
| `width` | integer | no | Image width in pixels (default 1600) |



## Results and diagnostics

Report operations carry `ok`, `status`, `output` and `diagnostics`; MCP exposes that JSON in `structuredContent`. `status: clean` means no warnings or errors. `ok: true` means no errors, so read diagnostics even after a successful operation. `isError` describes whether an MCP tool could execute. Lines and columns start at 1; a diagnostic's `file` names the data or style file when applicable, otherwise its location is in the `.rmd`.

`learn` prints text. `serve`, `server` and `mcp` remain running until stopped. `asset` and `image` have their own result objects and transfer exit codes. [Diagnostics and repair](https://richview.ai/docs/recovery) explains recovery; [data and storage](https://richview.ai/docs/data) describes asset transfer results.

## Use the VS Code extension

The extension is not on the Visual Studio Marketplace yet. Read the [VS Code guide](https://richview.ai/docs/vscode) for its native service, trusted workspace, preview, completion, formatting, export and publishing settings.

## A render tool call

MCP clients construct this request from an ordinary instruction to render a saved report:

```json
{"name":"richview_render","arguments":{"inputPath":"/absolute/path/to/first-report/report.rmd"}}
```