Artifacts

An artifact is a record of something Ravi or an agent produced: a generated image, a report, a trace, a folder with a small website. This page shows how to find and inspect artifacts, how versions work, and when to publish one to Ravi Pages with ravi artifacts publish instead of the usual ravi pages ship.

What an artifact holds

Artifacts live in Ravi’s local database (~/.ravi/ravi.db), with a copy of each file in ~/.ravi/artifacts/blobs/. Their IDs look like art_.... Each one can carry:

Identity: id, an optional kind (image, report, trace, …), title, summary, status, tags.
Content: a file or a whole directory (a package with an entrypoint), a URI, or structured output, with MIME type, size and sha256.
How it was made: provider, model, prompt, command, duration, token counts and cost when known.
Where it was made: agent, session, task, channel, chat and message, filled in automatically when a command runs inside a session.
Structured data: metadata, metrics, lineage, input and output (JSON).
Links to tasks, sessions, messages, projects or any other target, and a timeline of events (created, updated, queued, completed, failed, published, …).

Ravi creates artifacts on its own in two places:

ravi image generate records one kind=image artifact per image, before the provider is even called, and moves it through pending, running, completed or failed. See Media.
Every publish to Ravi Pages, including ravi pages ship, first stores the HTML (or the folder) as a local artifact and records the Console release on it as a published event.

Find and inspect

ravi artifacts list                          # newest first, 50 per page
ravi artifacts list --kind image --limit 10
ravi artifacts list --session main --json
ravi artifacts list --rich --lifecycle failed --json   # with stats and lineage

ravi artifacts show art_xxx                  # details, links, events, file path
ravi artifacts events art_xxx                # lifecycle timeline
ravi artifacts blob art_xxx > copy.png       # raw bytes

list also filters by --task, --tag and --agent (with --rich), pages with --limit/--offset, and hides archived artifacts unless you pass --include-deleted. With --json, follow pagination.nextCommand to get the next page.

Create, update and link

# Record a file you produced
ravi artifacts create --path ./diagram.png --kind image \
  --title "Architecture diagram" --provider openai --model gpt-image-2

# Record a folder as a package (entrypoint defaults to index.html)
ravi artifacts create --path ./site --title "Launch page"

# Edit fields (--metadata, --metrics and --lineage merge; the rest replace)
ravi artifacts update art_xxx --summary "Approved version" --metadata '{"approved":true}'

# Link to something else
ravi artifacts attach art_xxx task task-123 --relation evidence

# Add an event by hand
ravi artifacts event art_xxx failed --status failed --message "provider timeout"

# Archive (soft delete; still visible with --include-deleted)
ravi artifacts archive art_xxx

These commands write immediately. Only publish and release activate are dry-runs by default.

Versions

The artifact record shows the current state. Versions are immutable snapshots of its content.

Creating an artifact with a file, directory, URI or output creates version 1.
Updating content (--path, --uri, --output, --mime) creates the next version.
Metadata-only edits do not create a version. Run ravi artifacts snapshot when you want one.
Restoring a version copies it back as the current content and records the restore as a new version, so history is never lost.

ravi artifacts versions art_xxx
ravi artifacts version art_xxx --version 1 --json
ravi artifacts snapshot art_xxx --label "before edit"
ravi artifacts restore art_xxx --version 1

Artifacts and Ravi Pages

To put HTML on the web, use ravi pages ship. It is one command that uploads, mounts the page at a route on your project’s host and activates it. See Publish pages.

ravi pages ship --title "Weekly report" --route /weekly --html ./report.html

ravi artifacts publish is the lower-level primitive underneath. Use it only when you need something ship does not do:

publish an artifact that already exists in the ledger (art_*), or a specific version of it (--artifact-version <n>);
upload without going live (--no-activate), or upload to Console without mounting a page (omit --site);
control the release: --replace-release (replace the host’s whole route map instead of merging into it), --reason, --idempotency-key for safe retries;
set package options: --entrypoint, --base-path, --asset-base, --name, --slug, --description.

It needs a Console login (see Log in to the Console) and an explicit --project. Find the site slug with ravi pages list --project <project>. Without --execute it only prints the plan and exits with code 3:

ravi artifacts publish ./site --project my-project --site <site-slug> --route /launch --visibility private
ravi artifacts publish ./site --project my-project --site <site-slug> --route /launch --visibility private --execute

The target can be a local art_* ID, a file, or a directory with an index.html. A file or directory is first stored as a new local artifact. On success the command prints the Console artifact, version, publish and release IDs, the URL, and Local: recorded on art_... v1.

ravi artifacts publish (like ravi pages publish) cannot declare --uses, so a data page backed by Bases that you republish with it loses its actions. On hosts with data pages, use ravi pages ship with the full --uses list. See Interactive pages with Bases.

Re-activate an older release

A release is a snapshot of the whole host: every route on it. Activating an older release puts every route back to that state, not just one page. The simplest way is the operator bar on the page (see Publish pages). From the terminal, activate the release recorded on a local artifact:

ravi artifacts events art_xxx                           # "published" events carry the release and site
ravi artifacts release activate art_xxx --version 1     # plan only (exit 3)
ravi artifacts release activate art_xxx --version 1 --execute

Pick the release with --version <n> (the release recorded for that artifact version) or --release <id>. A release that is not recorded on the artifact also needs --site <site>. There is no command that lists a site’s releases; read them from the artifact’s events or from the release history in the operator bar. To find the local artifact a ravi pages ship created, look for its title in ravi artifacts list --limit 10. The artifactId that ship prints is the Console’s ID, not the local art_*.

Command reference

Command	What it does
`list`	List artifacts (filters, paging, `--rich`)
`show <id>`	Details, links and events
`create`	Record a file, folder, URI or output
`update <id>`	Edit fields; content changes create a version
`attach <id> <targetType> <targetId>`	Link to a task, session, message, project or other target
`archive <id>`	Soft delete
`event <id> <eventType>`	Append a lifecycle event
`events <id>`	List lifecycle events
`versions <id>` / `version <id>`	List versions / show one
`snapshot <id>`	Create a version now
`restore <id> --version <n>`	Restore content from a version
`blob <id>`	Print the raw bytes
`publish <target>`	Upload to Console and optionally release to Pages (dry-run without `--execute`)
`release activate <id>`	Re-activate a recorded Pages release (dry-run without `--execute`)

All commands except blob accept --json. Run ravi artifacts <command> --help for all flags, or ravi skills show artifacts for the agent-facing guide. There is no automatic provider fallback for anything that generates artifacts: if the chosen provider fails, the command fails, and you retry with another --provider yourself.

CLI

System

Tools

What an artifact holds

Find and inspect

Create, update and link

Versions

Artifacts and Ravi Pages

Re-activate an older release

Command reference

​What an artifact holds

​Find and inspect

​Create, update and link

​Versions

​Artifacts and Ravi Pages

​Re-activate an older release

​Command reference

What an artifact holds

Find and inspect

Create, update and link

Versions

Artifacts and Ravi Pages

Re-activate an older release

Command reference