> ## 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 before_session and auth_bypass attach when you run revyl device start

When `.revyl/config.yaml` declares `before_session` and/or `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. **Resolve project config** from the current working directory by walking up
   to the nearest directory that owns `.revyl/`, then loading
   `.revyl/config.yaml`.
2. **Run `before_session`** (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 `auth_bypass.launch_vars`**. When you did not pass `--launch-var`,
   the CLI attaches the configured org launch-variable keys. Keys that
   `before_session` 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.
5. **Fire `auth_bypass.deep_link`** (if configured and you did not pass
   `--app-link`). Placeholder substitution must use either only
   `before_session` values or only org launch variables — never a mix.

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

## Config Reminder

`before_session` and `auth_bypass` are top-level siblings of `build`:

```yaml theme={null}
before_session:
  script: "./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

Config is found by walking **up** from your cwd to a parent that owns
`.revyl/`. 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 — `before_session` and `auth_bypass`
are skipped silently.

## Overrides And Precedence

| Source                                     | Role                                               |
| ------------------------------------------ | -------------------------------------------------- |
| `before_session` stdout                    | Session-scoped launch env (highest for those keys) |
| `--launch-env KEY=VALUE`                   | Wins over minted and org values for the same key   |
| `auth_bypass.launch_vars` / `--launch-var` | Org launch-variable keys attached at boot          |
| `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 `before_session` runs fresh.

## What Does Not Run `before_session`

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 `before_session` 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 `before_session` key **names** and state only —
never token values.