# swb run-deploy

Deploys the versions an environment was offered — now, or at a time you
choose.

## Synopsis

```
usage: swb run-deploy <deploy-id>... --env <env> [--at <time>] [--json]
```

## Arguments and flags

| Argument or flag | Takes | Default |
|---|---|---|
| `<deploy-id>...` | One or more **deploy ids**, as [`swb deploys --status UPDATE_AVAILABLE`](/command-line/deploys) prints them: each a version the environment was offered. Required. | — |
| `--env` | An environment's **name or id**; a name is matched first. Every deploy named must be of this environment. Required. | — |
| `--at` | An **ISO-8601 time** such as `2026-10-14T09:00:00Z`; a time with an offset is read as the moment it names. The deploys wait until then. A time at or before now runs them now. | now |
| `--json` | Nothing. Prints the deploys as the API answered them instead of the table. | off |
| `--help`, `-h` | Prints the command's help and exits. | off |

## What it does

An environment that takes its versions by hand is offered each new version as
a deploy reading `UPDATE_AVAILABLE`. `swb run-deploy` takes the offer: it calls
`Mutation.runDeploy` for one deploy and `Mutation.runDeploys` for several, with
a fresh client token, so a repeated call is one run rather than two.

Each deploy moves to `QUEUED`, and you become the one who asked for it. It
deploys the install's settings as they stand when you run it. With no `--at` it
starts as soon as the install is free; with `--at` it waits until that time,
and [`swb unschedule-deploy`](/command-line/unschedule-deploy) takes the time
back. Several deploys run together or not at all: if any of them is no longer
offered — a newer version replaced it, or someone ran or cancelled it — none
of them moves.

The time is bounded by what AWS EventBridge Scheduler accepts, and nothing
else; a time it refuses is refused with its own words.

## What it prints

```
ID                                                  APP           VERSION  STATUS  AT                BY
crew-signout#beta0925#2026-09-12T08:00:00.000Z#d1  crew-signout  1.4.0    QUEUED  2026-10-14 09:00  mruiz@lime-energy.com
```

— each deploy's id, its app and version, its status, the time it waits for
(a dash when it runs now) and who asked for it.

`--json` prints the deploys as the API answered them.

## The operation and the permission

`Mutation.runDeploy` for one deploy, `Mutation.runDeploys` for several. The
caller needs `swb.deploys.run` on the tenant. `swb run-deploy` also reads
`Query.me` once for the tenant and `Query.tenant` to turn the `--env` name
into an id.

## Refusals and exit status

Exit status is 0 once the deploys are queued, and 1 on every refusal below.

| Refusal | When |
|---|---|
| `swb run-deploy takes <deploy-id>...` | No deploy was named. |
| `swb run-deploy needs --env <env>` | `--env` was not given. |
| `--at takes an ISO-8601 time such as 2026-10-14T09:00:00Z, not "<time>"` | `--at` is not a time. |
| `no environment named "<env>" in tenant <tenant> (have: dev, staging, prod)` | No environment of the tenant has that name or id. |
| `not signed in or token expired — run swb login` | There is no usable credential. |
| `NotFound: Deploy <id> not found` | The tenant has no such deploy. |
| `ValidationFailed: …` | A deploy of another environment, a deploy named twice, or more deploys than one call carries (100). |
| `Conflict: <id> is <STATUS>: only an offered deploy (UPDATE_AVAILABLE) can be run` | A deploy is no longer offered; with several, each such deploy is named and none moved. |
| `Refused: <app> in <env> is held at <version> by <who> since <time>; …` | A deploy of another version of a held install; the hold's own deploy is the one that runs. None moved. |
| `ValidationException: …` | EventBridge Scheduler refused the time, in its own words; nothing moved. |
| `NotAuthorized: …` | The caller lacks `swb.deploys.run`. |

## Example

```console
$ swb deploys --env beta --status UPDATE_AVAILABLE
$ swb run-deploy crew-signout#beta0925#2026-09-12T08:00:00.000Z#d1 --env beta --at 2026-10-14T09:00:00Z
```