# swb reject-deploy

Stops a deploy waiting at its gate, saying why.

## Synopsis

```
usage: swb reject-deploy <deploy-id> --env <env> --reason <text> [--json]
```

## Arguments and flags

| Argument or flag | Takes | Default |
|---|---|---|
| `<deploy-id>` | One **deploy id**, as [`swb deploys --status AWAITING_GATE`](/command-line/deploys) prints it: a deploy waiting for an approver. Required. | — |
| `--env` | An environment's **name or id**; a name is matched first. The deploy must be of this environment. Required. | — |
| `--reason` | Text: why you stop it. A rejection says why, so it is required. | — |
| `--json` | Nothing. Prints the deploy as the API answered it instead of the table. | off |
| `--help`, `-h` | Prints the command's help and exits. | off |

## What it does

`swb reject-deploy` calls `Mutation.rejectDeploy`: the deploy records who
rejected it, when and why, and its waiting execution ends. The deploy ends
`FAILED` with `GateRejected` and your reason, and nothing it would have
deployed changes: the install keeps running what it runs, and the install is
free for its next deploy. Deploying the version again is a new deploy.

The person who asked for a deploy never rejects it, as they never approve it;
see [`swb approve-deploy`](/command-line/approve-deploy) for who that is.

## What it prints

```
ID                                                    APP          VERSION  STATUS  APPROVED  REJECTED
switchboard#production0925#2026-10-20T10:00:00.000Z#d1  switchboard  9.10.0   FAILED  —         ana@lime-energy.com · 2026-10-20 11:00: wrong version
```

— the deploy as the control plane answered it. Its status reads `FAILED` once
its execution has ended it, a moment after the rejection.

`--json` prints the deploy as the API answered it.

## The operation and the permission

`Mutation.rejectDeploy`. The caller needs `swb.deploys.approve` on the tenant,
as an approval does. `swb reject-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 deploy is rejected, and 1 on every refusal below.

| Refusal | When |
|---|---|
| `swb reject-deploy takes <deploy-id>` | No deploy was named. |
| `swb reject-deploy needs --env <env>` | `--env` was not given. |
| `swb reject-deploy needs --reason <text>: a rejection says why` | `--reason` was not given, or is empty. |
| `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, an id that is no deploy's, or an empty reason. |
| `Conflict: …` | The deploy is not waiting at its gate, is still being planned, or someone approved or rejected it first. |
| `Refused: deploy <id> was asked for by you, …` | You asked for the deploy. |
| `TaskTimedOut: …`, `TaskDoesNotExist: …` | Step Functions refused the waiting deploy's token, in its own words. Nothing was recorded. |
| `NotAuthorized: …` | The caller lacks `swb.deploys.approve`. |

## Example

```console
$ swb reject-deploy switchboard#production0925#2026-10-20T10:00:00.000Z#d1 --env production --reason "wrong version"
```