# Build commands

> Upload iPhone and Android builds and read how Rehearsal checked them.

Source: https://rehearsal.dev/docs/reference/cli-builds

`rehearsal builds upload` sends a simulator build of an iPhone app or an APK of an Android app. `rehearsal builds list` and `rehearsal builds show` read how Rehearsal checked it, so that an exploration can install it.

`rehearsal explore` installs the newest ready build, and asks which one when the app has several. [iPhone, Mac and Electron apps](https://rehearsal.dev/docs/cli/native-apps.md) follows a build from upload to exploration.

## rehearsal builds upload

Upload a build of an iPhone or Android app.

Takes an APK for Android, up to 500 MB. For iPhone it takes a zipped `.app` from Xcode, Flutter or React Native, or the `.tar.gz` an Expo simulator build makes. An iPhone build joins the iPhone app with the same bundle id. An APK joins the Android app with the same package. Otherwise the build adds a new app. With `--app` it is a newer build of that app; a saved app in `rehearsal.config.json` is not used. The workspace and project come from the flags, `REHEARSAL_WORKSPACE_ID` and `REHEARSAL_PROJECT_ID`, or `rehearsal.config.json`. Without any of them, the CLI uses your only workspace and project, or asks you to pick one. Where it cannot ask, such as with `--json`, name them with `--workspace` and `--project`. The command waits while Rehearsal checks the build, then says what it found.

```sh
rehearsal builds upload <file> [flags]
```

| Argument | Description |
| --- | --- |
| `<file>` | The build file to upload. |

| Flag | Description |
| --- | --- |
| `--workspace <workspace-id>` | Workspace ID. Defaults to `REHEARSAL_WORKSPACE_ID` or `rehearsal.config.json`, then to your only workspace or the one you pick. |
| `--project <project>` | Project ID, slug or name. Defaults to `REHEARSAL_PROJECT_ID` or `rehearsal.config.json`, then to the workspace's only project or the one you pick. |
| `--app <app>` | A phone app in the project, by name or ID. Leave it out to join the app with the same id on the same phone, or to add a new app. |
| `--timeout <time>` | How long to wait for the check, such as 90s or 5m. The default is 10m, at most 1h. |
| `--dry-run` | Ask and check everything, then stop before anything starts or changes, and say what would happen. Off by default. |
| `--platform <platform>` | With `--app`, which kind of app: web, electron, ios or android. Needed only when two apps share a name. |

Needs a sign-in with the `testing:run` scope and permission to manage projects.

Ctrl+C stops the upload, or stops waiting once the file is in. Rehearsal keeps checking a build whose file is in.

```sh
# Upload a build
rehearsal builds upload Parcel.zip

# Upload an Android build
rehearsal builds upload Parcel.apk

# Upload a newer build of one app
rehearsal builds upload Parcel.zip --app Parcel

# Upload from a script
rehearsal builds upload Parcel.zip --workspace <workspace-id> --project parcel --json

# Check the file and where it goes, and upload nothing
rehearsal builds upload Parcel.zip --dry-run
```

## rehearsal builds list

List a phone app's builds, newest first.

With no app selected, it lists the builds that belong to no app yet, such as a first build still being checked or one that was refused. The build marked as used by default is the one an exploration installs when you pick none.

```sh
rehearsal builds list [flags]
```

| Flag | Description |
| --- | --- |
| `--app <app>` | The phone app whose builds to list, by name or ID. Defaults to `REHEARSAL_APP_ID` or `rehearsal.config.json`. |
| `--limit <count>` | How many to return, 1 to 100. The default is 20. |
| `--cursor <cursor>` | Continue from the cursor the last page returned. |
| `--workspace <workspace-id>` | Workspace ID. Defaults to `REHEARSAL_WORKSPACE_ID` or `rehearsal.config.json`. |
| `--project <project>` | Project ID, slug or name. Defaults to `REHEARSAL_PROJECT_ID` or `rehearsal.config.json`. |
| `--platform <platform>` | With `--app`, which kind of app: web, electron, ios or android. Needed only when two apps share a name. |

Needs a sign-in with the `testing:read` scope and permission to read projects.

```sh
# List an app's builds
rehearsal builds list --app Parcel

# Read them in a script
rehearsal builds list --app Parcel --json
```

## rehearsal builds show

Show one build and what Rehearsal found in it.

```sh
rehearsal builds show <build-id> [flags]
```

| Argument | Description |
| --- | --- |
| `<build-id>` | The build's ID, from `rehearsal builds upload` or `rehearsal builds list`. |

| Flag | Description |
| --- | --- |
| `--workspace <workspace-id>` | Workspace ID. Defaults to `REHEARSAL_WORKSPACE_ID` or `rehearsal.config.json`. |
| `--project <project>` | Project ID, slug or name. Defaults to `REHEARSAL_PROJECT_ID` or `rehearsal.config.json`. |

Needs a sign-in with the `testing:read` scope and permission to read projects.

```sh
# Show a build
rehearsal builds show <build-id>

# Read it in a script
rehearsal builds show <build-id> --json
```
