> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fjall.io/llms.txt
> Use this file to discover all available pages before exploring further.
# fjall deployments
> Inspect, cancel and force-release Fjall deployments from the CLI, and free a wedged deployment slot on AWS.
* The Fjall CLI installed, running on Node 22 or newer.
* A signed-in session. Run `fjall login` first. Credentials live at `~/.fjall/auth.json` (or `$FJALL_CONFIG_DIR/auth.json`).
* At least one deployment triggered from the CLI, from CI, or from the web app.
* `cancel` and `force-release` act on a deployment id, which `fjall deployments list` prints in the `ID` column.
* `force-release` additionally requires the organisation `owner` or `admin` role.
## Inspect your organisation's deployments
```bash theme={null}
fjall deployments [id] [options]
```
| Subcommand | What it does |
| -------------------- | -------------------------------------------------------------------- |
| `list` | List your organisation's active and recent deployments |
| `cancel ` | Request cancellation of an occupying deployment by its id |
| `force-release ` | Force-release a wedged deployment slot (organisation admin, audited) |
A bare `fjall deployments` prints help.
```bash theme={null}
# See what is running and what ran recently
fjall deployments list
# Ask the deploying machine to stop
fjall deployments cancel clz8p1k4v0001qw3h7g2m9x5b
# Free a slot held by a machine that died mid-deploy
fjall deployments force-release clz8p1k4v0001qw3h7g2m9x5b \
--confirm clz8p1k4v0001qw3h7g2m9x5b \
--reason "build agent terminated"
# Structured output for an agent or a script
fjall deployments list --agent --fields id,status,target
```
## What Happens
### `fjall deployments list`
Reads your organisation's deployments over the Fjall API and prints them most recent first. The server returns the 30 most recent rows. The command takes no filter or window flags.
| Column | Contents |
| -------- | --------------------------------------------------------------------------------------------------- |
| `STATUS` | Current deployment status |
| `TARGET` | Application name, `organisation` for an organisation-tier deploy, or the connected AWS account name |
| `SOURCE` | `cli`, `ci`, `webapp` or `worker` |
| `WHO` | Display name of the person who triggered it |
| `AGE` | Time since the deployment started |
| `ID` | Deployment id, the argument `cancel` and `force-release` take |
Rows print with a trailing count. With nothing to show, the command prints `No active or recent deployments` and exits 0. The read needs the `applications:read` scope, and a constrained token sees only rows whose application or account match its constraints.
### `fjall deployments cancel `
Writes a cancellation intent against the row. The outcome depends on what is holding the slot.
| Row | Result |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Web app or worker deployment | Flips to `cancelling`. The worker aborts the run in flight. |
| CLI or CI deployment with a live heartbeat | Flips to `cancelling`. The deploying machine reads the intent on its next beat and stops at the next safe point. CloudFormation operations already in flight complete first. |
| CLI or CI deployment with no live heartbeat | Refused, with the reason. Cancelling it here would report a stop that never happened. |
| Deployment paused on a destructive change | Declined rather than cancelled. The deployment does not proceed. |
| Deployment that already finished | Refused as already finished. |
When a refused row has reported no progress for more than five minutes, the CLI prints the exact `force-release` command to run next, including the id to retype as `--confirm`.
Cancellation is co-operative, so it is a request, not an instant kill. The command exits 0 on a refused remote cancel, because a refusal is an answered question rather than a failure. The API allows 10 cancels per minute per organisation.
### `fjall deployments force-release `
Marks a demonstrably silent occupying deployment as failed so a blocked deploy can claim the slot. Three gates apply, all server-side:
1. The caller holds the organisation `owner` or `admin` role.
2. `--confirm ` matches the deployment id exactly. A mismatch is refused.
3. The row has reported no progress, no status write and no event, for at least five minutes. A row that reported progress inside that window is refused, as is a paused row awaiting a human decision.
Every force-release writes an audit event carrying the actor, the deployment id and the masked `--reason` text. The API allows 10 force-releases per minute per organisation.
Force-release frees the Fjall slot. It does not stop the remote machine. If that machine is still alive it keeps deploying, and CloudFormation's per-stack lock is the only thing left protecting the stack. Run `fjall deployments cancel ` first and reach for force-release only when the machine is gone.
### Agent mode
Add `--agent` to any of the three subcommands for structured output. `deployments list` exposes `id`, `status`, `target`, `source`, `startedAt` and `triggeredBy`, plus a `total` aggregate. `--fields` selects exactly those names, and an invalid selection fails fast, before the authentication round-trip is spent.
None of the three commands has a dry-run flag. `list` is read-only, `cancel` writes an intent the deploying machine acts on, and `force-release` writes a terminal status.
An older Fjall server that does not offer one of these routes returns a capability notice and exit code 0 rather than an error, so a script can probe for support safely.
## Options
Every subcommand carries the shared flag set. `--confirm` and `--reason` belong to `force-release` only. The bare `fjall deployments` command carries `--non-interactive` and `-v, --verbose` alone.
| Flag | Description | Default |
| ------------------- | ----------------------------------------------------------------------------------- | --------------- |
| `--confirm ` | Retype the deployment id to confirm the force-release. Required on `force-release`. | none |
| `--reason ` | Optional audit reason recorded with the force-release. Capped at 500 characters. | none |
| `--non-interactive` | Force plain CLI output (no UI). | off |
| `-v, --verbose` | Enable verbose output. | off |
| `--agent` | Enable agent output mode. | off |
| `--budget ` | Output budget: minimal, compact, or token count. | none |
| `--fields ` | Select exactly these output fields. | schema defaults |
| `--full` | Disable content truncation. | off |
## Next Steps
Deploy an application, and read the flags that gate a destructive change.
List the recorded releases for an application and find the current one.
Restart running services so rotated secrets take effect, with no rebuild.
Understand slots, approval gates and how Fjall protects a live stack.