Configuration

.revyl/config.yaml owns the build recipes used by both local and remote builds. revyl init writes a detected starting point. Edit the YAML directly, then run revyl config validate. Direct builds require a project config with named profiles. If the selected file is legacy config, revyl build stops and directs you to preview and run revyl config migrate; it does not translate or rewrite the file implicitly. Each invocation resolves exactly one named profile and one platform recipe:

revyl build --profile development --platform ios
revyl build --profile development --platform ios --remote

The local and remote commands above use the same inherited environment, secret references, setup commands, build commands, output path, app, and executable definition. --remote changes where the recipe runs and activates its remote image and caches; it does not select a different recipe. For Expo, the native prebuild recipes below run Xcode or Gradle directly and do not require Expo authentication. If you intentionally replace them with an EAS local-build command, install EAS CLI and add an encrypted EXPO_TOKEN reference for unattended remote builds.

A complete example

Expo
React Native
iOS
Android

build:
  framework: expo
  env:
    EXPO_PUBLIC_API_URL: https://staging.example.com
  profiles:
    development:
      ios:
        app_id: "<your-ios-app-uuid>"
        setup_commands:
          - bun install
          - bunx expo prebuild --platform ios
          - cd ios && pod install
        build_commands:
          - cd ios && xcodebuild -workspace YourApp.xcworkspace -scheme YourApp -configuration Release -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' -derivedDataPath build ARCHS=arm64
        output_path: ios/build/Build/Products/Release-iphonesimulator/*.app
        image: ios-macos-26-xcode-26.5
      android:
        app_id: "<your-android-app-uuid>"
        setup_commands:
          - bun install
          - bunx expo prebuild --platform android
        build_commands:
          - cd android && ./gradlew assembleRelease
        output_path: android/app/build/outputs/apk/release/*.apk

build:
  framework: react_native
  profiles:
    development:
      ios:
        app_id: "<your-ios-app-uuid>"
        setup_commands:
          - npm install
          - cd ios && pod install
        build_commands:
          - cd ios && xcodebuild -workspace YourApp.xcworkspace -scheme YourApp -configuration Release -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' -derivedDataPath build ARCHS=arm64
        output_path: ios/build/Build/Products/Release-iphonesimulator/*.app
        image: ios-macos-26-xcode-26.5
      android:
        app_id: "<your-android-app-uuid>"
        setup_commands:
          - npm install
        build_commands:
          - cd android && ./gradlew assembleRelease
        output_path: android/app/build/outputs/apk/release/*.apk

build:
  framework: ios
  profiles:
    development:
      ios:
        app_id: "<your-ios-app-uuid>"
        build_commands:
          - xcodebuild -project YourApp.xcodeproj -scheme YourApp -configuration Release -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' -derivedDataPath build ARCHS=arm64
        output_path: build/Build/Products/Release-iphonesimulator/*.app
        image: ios-macos-26-xcode-26.5

build:
  framework: android
  profiles:
    development:
      android:
        app_id: "<your-android-app-uuid>"
        build_commands:
          - ./gradlew assembleRelease
        output_path: app/build/outputs/apk/release/*.apk

Profiles and platform recipes

Profiles name a complete build intent such as development, pull-request, or release. Each profile may contain an ios recipe, an android recipe, or both. There is no active or default profile stored in the file or on the server. revyl build applies explicit --profile and --platform values first. When an omitted value has exactly one eligible choice, the CLI selects it. If multiple choices remain, an interactive terminal prompts and a non-interactive invocation fails with the valid choices and the flag to provide.

revyl build --profile development --platform ios
revyl build --profile release --platform android --remote

--platform accepts only ios or android; profile names are passed to --profile.

Build fields

build.framework is required when build is present and applies to every profile. Supported values are ios, android, react_native, expo, and flutter. Build-level env, secrets, and caches are inherited by every recipe. A recipe can add or override them as described below.

Recipe field	Direct build requirement	Description
`app_id`	Remote: yes. Local: optional before execution.	UUID of the Revyl app that receives the finished build. After a successful local build without one, Revyl lets you select or create an app and offers to save the binding into this recipe.
`build_commands`	Yes	Ordered shell commands. Every declared recipe contains this field.
`setup_commands`	No	Ordered preparation commands run before `build_commands`.
`output_path`	Local: yes. Remote: optional.	Artifact path or glob relative to the selected project root. When absent remotely, Revyl uses the platform’s existing default artifact glob.
`image`	No	Toolchain image used for remote execution.
`timeout_seconds`	No	Positive timeout for recipe execution.
`env`	No	Non-secret environment values merged over `build.env`.
`secrets`	No	Secret reference names merged with `build.secrets`.
`caches`	No	Configured path caches merged with `build.caches` by key. See Caching.

The authored contract permits app_id and output_path to be absent. A local build-and-upload requires output_path before running commands. A remote build may omit it and use the existing platform artifact-discovery default, but it requires app_id before submission. A local build may run without app_id; after producing its artifact, the existing app-selection flow selects or creates the destination and offers to save that app ID into the selected recipe. All setup and build commands run in order from the project root selected by the nearest .revyl/config.yaml (or by -C). Selecting a recipe never rewrites its commands, publishes project configuration, or registers saved-profile identity with the ordinary build API. The optional post-build local app binding is the only config write in this flow; remote builds require the binding up front and do not select, create, or save an app.

Inheritance

Build-level values are resolved into each recipe deterministically:

Recipe env entries replace build-level values with the same key.
Effective secrets are the ordered, de-duplicated build-level names followed by recipe names.
Caches merge by key. Paths are the ordered, de-duplicated build-level paths followed by recipe paths.
A name cannot be both an effective environment key and a secret reference.

Artifact resolution

After the last build command exits successfully, a local build resolves its required output_path. A remote build uses its authored output_path when present, or falls back to the existing platform default:

iOS: build/**/*.app; the result must be a simulator .app bundle or a supported authored archive containing one.
Android: **/build/outputs/apk/**/*.apk; .aab artifacts are unsupported. Use an .apk.

Use an explicit path or glob that identifies one artifact. Avoid broad globs over cached output directories that can also match stale products.

Environment variables

Non-secret values are exported into the selected recipe’s setup and build commands. Use them for public build configuration such as EXPO_PUBLIC_* or ENVFILE:

build:
  framework: ios
  env:
    NODE_ENV: development
  profiles:
    development:
      ios:
        build_commands: ["./scripts/build-ios"]
        output_path: build/App.app
        env:
          EXPO_PUBLIC_API_URL: https://staging.example.com

Override or add values for one remote invocation:

revyl build --profile development --platform ios --remote \
  --env EXPO_PUBLIC_API_URL=https://preview.example.com

--env is a remote-only flag. Its values take precedence over the inherited config environment. Local builds use the inherited config environment as authored. Do not put credentials or tokens in env or --env; use secret references instead.

Compilation cache controls

These reserved environment settings control automatic compilation caching:

Setting	Platform	Values
`REVYL_XCODE_COMPILATION_CACHE_ENABLED`	iOS	`"0"` or `"1"`
`REVYL_GRADLE_BUILD_CACHE_ENABLED`	Android	`"0"` or `"1"`
`REVYL_CCACHE_ENABLED`	Android	`"0"` or `"1"`

All three default to "1". revyl build --remote --no-cache forces them off for one remote build and also skips configured path caches. See Caching. Do not put credentials or tokens in env or --env; those values are part of the remote build request. Use encrypted build secrets instead.

Build secrets

Create or update an encrypted organization secret through the masked prompt:

revyl build secret set EXPO_TOKEN

For CI, send the value over stdin so it does not appear in process arguments or shell history:

printf '%s' "$EXPO_TOKEN" | revyl build secret set EXPO_TOKEN --stdin

Commit only the reference name:

build:
  framework: ios
  secrets:
    - EXPO_TOKEN
  profiles:
    development:
      ios:
        build_commands: ["./scripts/build-ios"]
        output_path: build/App.app
        secrets:
          - SENTRY_AUTH_TOKEN

Add references for one invocation with repeatable --secret flags:

revyl build --profile development --platform ios --remote \
  --secret EXPO_TOKEN --secret SENTRY_AUTH_TOKEN

Remote builds validate the names, decrypt the stored values only when the sandbox starts, and inject them into every setup and build command. Local builds read the same effective names from the current process environment and fail before running commands if a referenced value is missing:

set -a
source .env.local
set +a
revyl build --profile development --platform ios

Revyl does not parse .env.local automatically. Keep it out of version control. List or delete stored names without revealing their values:

revyl build secret list
revyl build secret delete EXPO_TOKEN

Remote source

revyl build --remote archives the active Git worktree, including its current unignored working-tree changes, and sends the selected project directory as the runner workdir. This preserves workspace files and shared packages for nested monorepo projects while commands and artifact paths remain relative to the project containing .revyl/config.yaml. It does not publish the config or send saved-profile identity. The profile name and platform remain invocation-local selection inputs.

CLI reference

revyl build [--profile <name>] [--platform ios|android] [--remote] [flags]

Flag	Description
`--profile <name>`	Select a named local profile. Required when profile selection remains ambiguous.
`--platform ios\|android`	Select the recipe inside the profile. Required when platform selection remains ambiguous.
`--remote`	Run the selected recipe on a Revyl cloud runner.
`--image <key>`	Override the selected recipe’s remote toolchain image.
`--env KEY=VALUE`	Remote environment override, repeatable.
`--secret NAME`	Secret reference, repeatable. Local builds read it from the process environment; remote builds use the stored organization secret.
`--timeout <seconds>`	Override the selected recipe’s remote timeout.
`--version <string>`	Version label for the registered build. Auto-generated when omitted.
`--detach`	Queue a remote build and return the job ID without waiting.
`--no-cache`	Run a cold remote build without compilation caches or configured path caches.
`--no-set-current`	Do not make the new version the app’s current build.
`--json`	Write the machine-readable result to stdout.
`--debug`	Stream detailed diagnostics and remote build logs.

Managing running remote builds:

revyl build status <build-job-id>
revyl build status <build-job-id> --follow
revyl build cancel <build-job-id>
revyl build list

Timeout

Remote builds are stopped by the server when they exceed their timeout: 60 minutes by default, up to a maximum of four hours. Set a recipe-specific value:

build:
  framework: ios
  profiles:
    release:
      ios:
        build_commands: ["./scripts/build-release"]
        output_path: build/Release.app
        timeout_seconds: 3600

Or override it for one invocation:

revyl build --profile release --platform ios --remote --timeout 3600

Ctrl-C stops following the build; the build keeps running in the cloud. Cancel it with revyl build cancel <build-job-id>.

Caching: compilation and configured path caches
Toolchain Images: available images and installed tools
Artifact Requirements: supported .app and .apk artifacts

Getting Started

CLI

Builds

Tests

Develop

Atlas

Integrations

Appendix

A complete example

Profiles and platform recipes

Build fields

Inheritance

Artifact resolution

Environment variables

Compilation cache controls

Build secrets

Remote source

CLI reference

Timeout

​A complete example

​Profiles and platform recipes

​Build fields

​Inheritance

​Artifact resolution

​Environment variables

​Compilation cache controls

​Build secrets

​Remote source

​CLI reference

​Timeout

​Related

A complete example

Profiles and platform recipes

Build fields

Inheritance

Artifact resolution

Environment variables

Compilation cache controls

Build secrets

Remote source

CLI reference

Timeout

Related