---
title: Trigger a Native Build
description: Trigger native iOS and Android builds in Capawesome Cloud from the CLI or the Console — from a Git repository or from local files, with full build options.
---

# Trigger a Build

Triggering a build hands your source code to Capawesome Cloud, which checks it out, installs your dependencies, compiles it on a hosted macOS machine, and hands back the finished artifact — an `.apk`/`.aab` for Android, an `.ipa` for iOS, or a `.zip` of web assets. You never have to keep a Mac or a build toolchain running yourself.

You can start a build two ways — with the [CLI](../cli/index.md) or in the [Console](https://console.cloud.capawesome.io){:target="_blank"} — and from two sources: your connected **Git repository** (recommended) or **local files** when you don't have a repository connection.

## Prerequisites

Before your first build, make sure you've [created an app](setup.md#step-1-create-an-app) and, for Git-based builds, [connected your repository](setup.md#step-2-connect-git-repository). Local builds (`--path`) work without a repository connection.

## Build from Git

Building from Git is the recommended path: the Cloud checks out the exact reference you specify, so what ships always matches what's committed.

=== "CLI"

    Use the [`apps:builds:create`](../cli/commands.md#appsbuildscreate) command and point it at a branch, tag, or commit SHA:

    ```bash
    npx @capawesome/cli apps:builds:create --platform ios --git-ref main --type development
    ```

    The CLI prompts for any values you don't pass, then streams the build status and prints the build number (e.g. `#42`) when it's done. Add `--detached` to return immediately without waiting, or `--yes` to skip all prompts — handy in scripts and CI.

=== "Console"

    Open the [Builds](https://console.cloud.capawesome.io/apps/_/builds){:target="_blank"} page, click **Build from Git**, then choose the Git reference (branch, tag, or commit), the platform, and the [build type](build-types.md). Click **Build** to start.

    ![Build from Git dialog in the Capawesome Cloud Console](../../assets/images/screenshots/cloud-app-builds-from-git.png)

## Build from local files

If you haven't connected a Git repository — or you want to build code that isn't committed yet — build straight from your machine by passing `--path` instead of `--git-ref`:

```bash
npx @capawesome/cli apps:builds:create --platform android --path . --type debug
```

The CLI zips up the given directory and uploads it as the build source. See [Build without Git](build-without-git.md) for the details and caveats.

## Choose what to build

A build is shaped by a handful of options. Pass them as flags on the CLI, or pick them in the Console dialog:

- **Platform** (`--platform`) — `android`, `ios`, or `web`. A web build produces the bundle used for [Live Updates](../live-updates/index.md).
- **Build type** (`--type`) — for Android, `debug` or `release`; for iOS, `simulator`, `development`, `ad-hoc`, `app-store`, or `enterprise`. Pick a debug/simulator type for quick testing and a signed type for distribution. See [Build types](build-types.md).
- **Signing certificate** (`--certificate`) — required for signed builds. See [Certificates](certificates/index.md).
- **Native configuration** (`--configuration`) — the app name and package name (application ID on Android, bundle ID on iOS) to apply to the native project before it's built. Android and iOS only. See [Native configurations](native-configurations.md).
- **Environment** (`--environment`) — the variables and secrets to expose during the build. You can also pass one-off values with `--variable key=value` or a `.env` file via `--variable-file`. See [Environments](environments.md).
- **Build stack** (`--stack`) — the macOS image (and its Xcode, Node.js, and Java versions) to build on. Defaults to the latest. See [Build stacks](build-stacks.md).

## After the build

Once a build finishes, you can:

- **Download the artifact.** The CLI can save it directly with `--apk`, `--aab` (Android), `--ipa` (iOS), or `--zip` (web) — optionally followed by a file path. In the Console, use the build's detail page.
- **Install it on a device.** Side-load the build onto a phone or tablet without the app store. See [Install on a device](install-on-device.md).
- **Run it on an emulator or simulator.** Download, install and launch the build on a local Android emulator or iOS simulator with a single command. See [Run on an emulator or simulator](run-on-emulator-or-simulator.md).
- **Share it with testers.** Send a public link so external testers can view and install the build without an account — pass `--share` to share automatically. See [Share a build](share-a-build.md).
- **Submit it to a store.** Pass `--destination` to send a native build to TestFlight or Google Play, or deploy a web build to a Live Update channel with `--channel`. See [App Store Publishing](../app-store-publishing/index.md).

If a build fails, the logs tell you why — see [Monitor a build](monitor-builds.md) and [Build Logs](build-logs.md). For the full list of flags, see the [`apps:builds:create` reference](../cli/commands.md#appsbuildscreate).

## Next steps

- [Monitor a build](monitor-builds.md) — watch status and read logs.
- [Install on a device](install-on-device.md) — download and side-load the artifact.
- [Share a build](share-a-build.md) — give external testers a public link.
- [Automate builds in CI/CD](integrations/index.md) — including the official [GitHub Action](integrations/github-actions.md).