> ## 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.

# Explore from the CLI

> Launch app exploration, follow each explorer, and produce an Atlas map from a terminal or CI job.

Use Explore when you want Revyl to discover an app and build or refresh its Atlas map.

## Start an exploration

Pass an exact app name or ID:

```bash theme={null}
revyl explore run "My App"
```

Without an app argument, the CLI uses the app mapping in `.revyl/config.yaml`. Add `--platform ios` or `--platform android` when the project has more than one mapped app.

```bash theme={null}
revyl explore run --platform android
```

Explore uses the latest uploaded build by default. Pin a build with `--build-id` when you need a reproducible map.

## Shape the run

```bash theme={null}
revyl explore run "My App" \
  --explorers 4 \
  --strategy surface-sweep \
  --instructions "Cover checkout and account settings" \
  --max-duration 20m \
  --open
```

Strategies are `balanced`, `surface-sweep`, `journey-focus`, and `hard-edges`. Revyl may lower the explorer count to match available device concurrency; the CLI reports the final count.

Use `--device-model`, `--os-version`, and `--idle-timeout` for runtime targeting. `--timeout` only limits how long the local CLI waits. It does not cancel a run that is still active.

## Authentication and launch variables

Give explorers plain-language sign-in guidance with `--auth-instructions`. Attach stored launch variables by key or ID:

```bash theme={null}
revyl explore run "My App" \
  --auth-instructions "Use the seeded test account" \
  --launch-var REVYL_AUTH_BYPASS_ENABLED \
  --launch-var REVYL_AUTH_BYPASS_TOKEN
```

<Warning>
  Store secret values in Revyl and reference them with `--launch-var`. Do not put secrets in `--launch-env`, shell scripts, logs, or committed workflow files.
</Warning>

## Monitor or cancel

The default command waits and prints explorer progress. Queue the run without waiting when another job will monitor it:

```bash theme={null}
revyl explore run "My App" --no-wait --json
revyl explore status <run-id>
revyl explore cancel <run-id>
```

Press `Ctrl-C` once while waiting to cancel the remote run. Press it again to stop waiting immediately.

With `--json`, progress stays on stderr and stdout contains one result object. The object includes the run and app IDs, execution and Atlas states, effective explorer counts, findings count, report URL, outcome, and success value.

## Outcomes and exit codes

Explore exits successfully when it produces a usable map. A partial map or a map with a setup blocker warns but still succeeds. Product findings are discoveries, not failed test assertions.

The command exits non-zero when the run fails, is cancelled, times out locally, or finishes without a usable map.

<Tip>
  Explore gates execution and map generation. Use Revyl tests and workflows when CI needs to assert product correctness.
</Tip>

Inspect the resulting map with the [Atlas CLI](/cli/atlas), or learn the [Explore UI workflow](/atlas/explore).