> ## Documentation Index
> Fetch the complete documentation index at: https://site.aspect.build/llms.txt
> Use this file to discover all available pages before exploring further.

# aspect run

> Build a Bazel target and execute its binary with aspect run, integrating the Aspect CLI task lifecycle, retries, and CI status updates over bazel run.

`aspect run` builds a target and executes the resulting binary — the same job `bazel run` does, but routed through the Aspect task lifecycle so it gets the same retry-on-transient-error, status updates, and CI integrations as `aspect build` and `aspect test`.

```shell theme={null}
aspect run //tools/codegen:gen
aspect run //services/api:server -- --port 9090 --verbose
```

Arguments after `--` are forwarded to the target binary unchanged. Arguments before `--` are interpreted by the task itself.

## Forwarding Bazel flags

Pass build-time Bazel flags with `--bazel-flag` (repeatable):

```shell theme={null}
aspect run --bazel-flag=--config=debug //services/api:server
aspect run --bazel-flag=--config=debug --bazel-flag=--keep_going //tools/codegen:gen
```

Startup flags use `--bazel-startup-flag`. Note that changing startup flags restarts the Bazel server:

```shell theme={null}
aspect run --bazel-startup-flag=--host_jvm_args=-Xmx2g //tools/heavy:thing
```

## When to use `aspect run`

* **Local development** — same lifecycle as `aspect build` / `aspect test`, so debug output looks the same.
* **CI smoke tests** — running a binary as a pipeline step works exactly like a build or test step. No special wrapping required.
* **One-off scripts** — invoke a binary built from source without writing a wrapper script.

For long-running services in CI, prefer running a daemon outside the Bazel build graph. `aspect run` waits for the spawned binary to exit before completing.

## Comparison with `bazel run`

|                                    | `bazel run` | `aspect run`             |
| ---------------------------------- | ----------- | ------------------------ |
| Builds the target                  | Yes         | Yes                      |
| Runs the resulting binary          | Yes         | Yes                      |
| Transient build error retry        | No          | Yes (configurable)       |
| Task lifecycle hooks fire          | No          | Yes                      |
| Status check / annotation surfaces | No          | Yes (when authenticated) |
| Forwards binary args after `--`    | Yes         | Yes                      |