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

# Auth And Session Prep

> How session.before_script and session.auth_bypass attach when you run revyl device start

When `.revyl/config.yaml` declares `session.before_script` and/or
`session.auth_bypass`,
`revyl device start` (and `revyl dev`) apply them automatically. You do not
pass tokens on the command line.

For the app-side deep-link contract and mint-script shape, see
[Auth Bypass Deep Links](/builds/auth-bypass-deeplinks). This page covers what
the CLI does on device start.

## Attach Order On `revyl device start`

Every start goes through the same pipeline:

1. **Read optional session settings** from the nearest `.revyl/config.yaml`
   within the current Git worktree, or from the current directory outside Git.
   No config means command defaults and explicit flags. Legacy
   `defaults.timeout`, `before_session`, and `auth_bypass` settings work without
   migration; unrelated build and PR-review settings do not block device start.
   Malformed YAML and invalid session settings still fail before provisioning.
2. **Run `session.before_script`** (if configured). The script must finish before the
   device boots. `KEY=VALUE` lines on stdout become **session-scoped** launch
   environment for this start only. A non-zero exit aborts start — Revyl will
   not boot an unprepared app.
3. **Apply `session.auth_bypass.launch_vars`**. The CLI adds the configured org
   launch-variable keys to the explicit and inherited keys selected for this start. Keys that
   the before script already printed as inline values are not also looked up
   in org state.
4. **Boot the device** with that launch environment fixed for the session.
   For iOS, selected `--launch-arg-set` values are flattened in flag order and
   inline `--launch-arg` tokens are appended. These explicit tokens are placed
   before legacy `-KEY value` pairs. Android rejects explicit arguments.
5. **Fire `session.auth_bypass.deep_link`** (if configured and you did not pass
   `--app-link`). Placeholder substitution must use either only
   before-script values or only org launch variables — never a mix.

```mermaid theme={null}
flowchart TD
  A["revyl device start"] --> B["Read optional session settings"]
  B --> C{"session.before_script configured?"}
  C -->|yes| D["Run script → KEY=VALUE"]
  C -->|no| E["Skip mint"]
  D --> F["Merge launch env + session.auth_bypass.launch_vars"]
  E --> F
  F --> G["Boot device / install build"]
  G --> H{"session.auth_bypass.deep_link?"}
  H -->|yes| I["Open deep link"]
  H -->|no| J["Session ready"]
  I --> J
```

## Config Reminder

Both settings live under the `session` section:

```yaml theme={null}
session:
  before_script:
    script_path: "./scripts/prepare-test-session.sh"
    timeout_seconds: 120
  auth_bypass:
    launch_vars: [REVYL_AUTH_BYPASS_ENABLED, REVYL_AUTH_BYPASS_TOKEN]
    deep_link: "myapp://revyl-auth?token=${REVYL_AUTH_BYPASS_TOKEN}"
```

One produces values; the other consumes them. Full script contract:
[Mint The Token Per Session](/builds/auth-bypass-deeplinks#mint-the-token-per-session).

## Working Directory Matters

Inside Git, config is found by walking **up** from your cwd to the nearest
`.revyl/config.yaml`, stopping at the worktree root. Outside Git, only the
current directory is checked. Use `-C <project-dir>` to choose the directory.
In a monorepo where the Revyl project lives in a subdirectory
(for example `ios/.revyl/config.yaml`), run device commands from that
project directory (or below it):

```bash theme={null}
cd ios
revyl device start --platform ios --build-version-id <id> --json
```

If you start from the monorepo root and there is no root-level `.revyl/`,
the CLI will not load the nested config — `session.before_script` and
`session.auth_bypass`
are skipped silently.

## Overrides And Precedence

| Source | Role |
| - | - |
| `session.before_script` stdout | Session-scoped launch env |
| `--launch-env KEY=VALUE` | Wins over minted and org values for the same key |
| `session.auth_bypass.launch_vars` / `--launch-var` | Org launch-variable keys attached at boot |
| `--launch-arg-set <name-or-id>` | Stored ordered iOS argument sets, flattened in flag order |
| `--launch-arg=<token>` | Exact inline iOS token appended after stored sets; always non-secret |
| `session.auth_bypass.deep_link` | Post-launch navigate (after boot) |

Launch environment is fixed at boot. `revyl dev auth refresh` re-fires the
deep link with the **same** boot values; it does not remint. If the token
expired, stop and start again so the before script runs fresh.

## What Does Not Run `session.before_script`

The PR **preview link** in a GitHub comment has no checkout, so it cannot run
your mint script. That path still uses organization launch variables only.
Keep org vars fresh if reviewers rely on the preview link being signed in;
proof agents and local `revyl device start` use the before script instead.

## Verify

```bash theme={null}
# From the directory that owns .revyl/
revyl device start --platform ios --timeout 1800 --json
# Confirm the app is signed in (screenshot / validation), then:
revyl device stop
```

`revyl dev status` reports the runtime `before_session` key **names** and state only —
never token values.


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