Skip to main content
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.
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 branch, build, time, device, and runtime scope. Graph and capture-listing follow-ups retain an active --recent-build-limit; exact observation and report reads remain exact evidence.

​
Branch scope

Atlas reads and atlas open show All branches (--all-branches) by default. Pass --branch <name> or --branch-id <id> to narrow the evidence to one branch, including a branch with no usable build. --build latest selects the newest usable build on one branch, even when the branch is pinned: --branch when given, otherwise your Git branch when it has a usable build, otherwise the app’s default branch. An exact --build <id> keeps that build’s scope. A version string passed to --build <version> selects the newest upload whose version matches exactly, within an explicit branch when provided and across branches otherwise. Package names and partial version matches are excluded. An unavailable version fails; it never falls back to another build. All branches stays within the selected app and organization, with the same pagination, time windows, and recent-build limits. A recent-build limit counts builds across the selected scope: 20 means 20 in total across All branches, not 20 per branch. Branch-scoped responses include projection.branch_id, and suggested follow-up commands keep that branch with --branch-id. Follow-ups from All branches use --all-branches when no exact build is selected. Branches filter observed evidence. Screen merges, hiding, and identity-root choices remain app-wide; evidence without a known build appears only in All branches. See Build branches for defaults, pins, and saved choices. To keep a shared main or staging map current, see Keep main or staging current.

​
Read the graph

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:
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.
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. Graph inspection JSON responses include a versioned contract and projection.data_source. summary identifies the compact graph model and evidence identifies a focused observation read.

​
Agent investigations

Use revyl tools search "device logs" to discover operations and revyl tools describe reports.logs to inspect their JSON inputs. The catalog includes report diagnostics, build executions, Atlas traversal and grounded annotations. revyl build runs <build-id> --page 1 --limit 20 --json provides paginated executions attributed to a selected build. revyl test query --app <app-id> --search onboarding --limit 25 --json filters tests before pagination. revyl test inspect <test-id> --json reads current instructions, device targets and saved configuration; those settings may differ from the version and overrides used by a past execution. revyl atlas from-reports --app <app-id> --reports <report-id> --json projects selected reports upward into Atlas and retains unmapped evidence. Missing evidence does not establish that a feature was removed. Supported tool calls accept --view to return data with a read-only query recipe. revyl tools hydrate - reads that recipe from stdin and re-runs it under the caller’s current authorization. A consuming interface supplies the native renderer; the agent supplies a query, never executable UI code. Install the Atlas skill to make this media-first graph workflow the agent default: