> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revyl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

The Atlas CLI exposes an app as a media-grounded knowledge graph. Screens are
nodes and observed relationships are edges. Begin with typed starting anchors,
inspect their real screenshots, and traverse relevant edges in both directions.
Everything in Atlas originated in observed run evidence. Generated semantics
are interpretations, so inspect unexpected evidence rather than discarding it.

Need to build or refresh Atlas first? Start with [Explore from the CLI](/cli/explore).

```bash theme={null}
revyl atlas apps --search "Riot"
revyl atlas brief --app "Riot"
revyl atlas graph --app "Riot"
```

Atlas inspection commands accept `--device-model` and `--runtime`, with
`--os-version` as an alias for `--runtime`. Either filter can be used alone;
when both are present, Atlas returns evidence that matches both exact,
case-sensitive values. JSON responses expose available combinations in
`facets.device_targets`, and suggested Atlas follow-up commands retain the
active build, time, device, and runtime scope.

```bash theme={null}
revyl atlas graph --app "Riot" --device-model "Pixel 7" --runtime "Android 14"
```

`brief` is a bounded orientation: product areas, starting anchors, highly
connected screens, and a representative visual sample. An anchor's reasons
(`curated_entry`, `semantic_entry`, or `observed_root`) explain why it is useful
for beginning traversal. They do not define a parent, hierarchy, or preferred
journey.

Download and actually inspect the visual sample before describing the UI:

```bash theme={null}
ATLAS_VISUAL_DIR=$(mktemp -d)
revyl atlas brief --app "Riot" --screenshots --screenshot-dir "$ATLAS_VISUAL_DIR" --json
```

Use the returned `local_screenshot_path`; screenshot filenames are opaque.
On Unix, new screenshot directories use mode `0700` and downloaded or reused
screenshots use `0600`. Existing output directories keep their permissions.
On Windows, existing file ACLs are preserved and new files inherit the output
directory's access controls. Choose a directory restricted to your account
when downloading private screenshots.

`graph` is the canonical flat contract: `starting_anchors`, `nodes`, and typed
edges between returned nodes, without a selected primary path. Check the
top-level `truncated` or `has_more` value before treating the response as the
complete app graph. `map` remains a compatibility alias for the same graph view.

Explore bottom-up with focused commands:

* `search <query>` finds candidate nodes.
* `screen <screen-id>` inspects one node and its incoming and outgoing edges.
* `observations <screen-id>` loads grouped screenshot evidence.
* `neighbors <screen-id>` continues graph traversal in either direction.
* `edge <source-id> <target-id> --runs --json` loads recorded transition clips.
* `area <product-area>` returns the area's subgraph plus its boundary edges.
* `observation <observation-id>` loads one exact screenshot observation.
* `report <screen-or-observation-id>` loads the report that produced evidence.

```bash theme={null}
revyl atlas search "settings social profile" --app "Riot" --json
revyl atlas screen <screen-id> --app "Riot" --screenshots --screenshot-dir "$ATLAS_VISUAL_DIR" --json
revyl atlas neighbors <screen-id> --app "Riot" --json
```

A screenshot path, semantic name, or generated summary is not visual
verification. Open the selected `local_screenshot_path` files. If an edge is
surprising or important, run
`revyl atlas edge <source-id> <target-id> --app <app-id> --runs --json`, open
the newest run's `active_video.video_url`, and watch the interval bounded by
`source_video_start` and `source_video_end`. If the cause remains unclear,
traverse backward through the source node's incoming edge and inspect that
preceding clip. If native video ingestion is unavailable, use `ffmpeg` to
extract the bounded interval at roughly two frames per second and open the
frames in chronological order.

Use `revyl atlas report <screen-or-observation-id> --app <app-id> --json` to
read the originating test goal, steps, actions, and workflow context. Screen
IDs use their representative observation; observation IDs resolve exact
evidence. For a misunderstood edge, use the exact run's `execution_id` or
`session_id` with `revyl test report` or `revyl device report` so the report
matches the transition clip. Keep signed URLs and downloaded media temporary
and out of logs and committed artifacts.

Every JSON response includes a versioned `contract` and
`projection.data_source`. `summary` identifies the compact graph model and
`evidence` identifies a focused observation read.

Install the Atlas skill to make this media-first graph workflow the agent
default:

```bash theme={null}
revyl skill install --name revyl-cli-atlas
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.