Publish: walkthrough

A RichView server stores rendered reports, their source and their resources. Each published version has a permanent address; the report’s shorter address follows its highest release version unless the owner pins another. The public richview.ai website serves docs, examples and the playground. It is not a self-service report server.

Prepare the report

Use the first-report/ created in your first report. Publication requires a nonempty title, description and version. The starter has these. Keep the version as text shaped like 0.0.1, and raise it when the content changes. Validation runs again during publication.

Test a publishing server on loopback

This Bash example uses openssl and curl as well as richview. Run it in the working folder containing first-report/. It creates a disposable token without printing it and stores reports only in tmp/local-publish-store/.

export RICHVIEW_SERVER=http://127.0.0.1:4820
export RICHVIEW_TOKEN="$(openssl rand -hex 24)"
richview server --data-dir tmp/local-publish-store \
  --port 4820 --public-url http://127.0.0.1:4820 \
  --report-port 4821 --report-origin http://localhost:4821 \
  --default-visibility public &
richview_test_pid=$!
trap 'kill "$richview_test_pid"; unset RICHVIEW_TOKEN RICHVIEW_SERVER' EXIT
curl --fail --silent --show-error --retry 10 --retry-connrefused --retry-delay 1 \
  http://127.0.0.1:4820/health && echo
richview publish first-report/report.rmd \
  --server http://127.0.0.1:4820 --slug first-report --new --format json

The server keeps running in the background. Open the report URL from the publication result. This disposable loopback example selects anyone with the link so you can read it without creating a user. A server’s normal default is private; use that default when setting up a real service. A new address needs --new; another version at the same address does not.

The application uses 127.0.0.1 and the report uses localhost so they have different hostnames. Different ports on the same hostname would share cookies. Use another pair of free ports consistently if these are occupied.

Publish and inspect safely

With that server still running, identical publication is safe to repeat:

richview publish first-report/report.rmd \
  --server http://127.0.0.1:4820 --slug first-report --format json
richview report regenerate first-report 0.0.1 \
  --server http://127.0.0.1:4820 --format json

The identical version returns created: false and keeps its original artifact. Regeneration renders the retained source with the running engine and reports differences; it stores nothing. To revise the report, edit its source, increase version, validate and publish again. Different content under an existing version is refused as publish.version-exists.

Pin the version you want the short address to serve, then restore version ordering:

richview report pin first-report 0.0.1 --server http://127.0.0.1:4820 --format json
richview report unpin first-report --server http://127.0.0.1:4820 --format json

For this disposable example only, you can delete the stored version when finished. Its immutable address becomes a tombstone and that version number cannot be published again:

richview report delete first-report 0.0.1 --yes --server http://127.0.0.1:4820 --format json

Stop only this example’s server when finished:

kill "$richview_test_pid"
trap - EXIT
unset RICHVIEW_TOKEN RICHVIEW_SERVER

Choose the right link

Use a versioned address in a decision record or citation. Use the short address when readers should follow revisions. Read publishing and access for permissions, pins, deletion, quotas, API routes and hosting. HTML and PDF export is the simpler path when a file is enough.

Use a server beyond your machine

With no server chosen, the interactive CLI offers RichView-operated Cowork at https://app.richview.ai, a self-hosted server, or cancel. It remembers your explicit choice without storing your token. To change that choice, unset RICHVIEW_SERVER and run richview publish <report> --choose-server. An explicit --server takes precedence over RICHVIEW_SERVER, which takes precedence over the saved choice. A noninteractive command with no choice fails without uploading. A saved choice is per user account on that machine.

Hosted Cowork is planned and is not yet available. To request an author account and token, email the contact listed at RichView’s contact page. Once access is available and you receive a token, set RICHVIEW_SERVER=https://app.richview.ai and RICHVIEW_TOKEN to that token in your shell or MCP host. The environment token is sent only to RICHVIEW_SERVER; use another server’s own --token when selecting a different server. The MCP tool cannot prompt and requires its host to configure both variables. New hosted reports are private to their owner by default; the operator can administer them, and owners can share them after signing in.

Keep tokens out of source and shared command history. Remote bearer-token requests require HTTPS; HTTP is allowed only on loopback. A self-hosted production service needs HTTPS origins, persistent storage, backups and an operating process. The CLI does not deploy that infrastructure for you.