> ## 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 services
> Check live AWS ECS rollout status for every Fjall application service and gate CI smoke steps on the exit code.
`fjall services` reads the live ECS rollout state of every service in an application and exits non-zero unless all of them have finished rolling out.
The exit code is the point of the command. A CloudFormation deploy can report success while a background worker is still churning behind it. An ALB health endpoint only covers the web service. This command asserts that every service converged.
* **Signed in.** Run `fjall login`. Credentials live at `~/.fjall/auth.json` (or `$FJALL_CONFIG_DIR/auth.json`).
* **A connected AWS account.** Run `fjall connect` if you have not connected one yet.
* **A matching organisation binding.** Run the command inside your Fjall project. The command refuses to read services when the project is bound to a different organisation than the one you are signed in to.
* **A deployed application.** The probe reads running ECS services, so the application must have been deployed at least once. When it finds no services, the command fails with a message telling you to deploy the application first.
* **Node.js 22 or later.**
## Check rollout status
```bash theme={null}
fjall services
```
The `` positional argument is required.
```bash theme={null}
# Every service in the api application
fjall services api
# A single service
fjall services api --service worker
# Machine-readable output for a CI smoke step
fjall services api --json
# Probe a specific region
fjall services web --region eu-west-1
```
Wire it into a pipeline directly after a deploy:
```bash theme={null}
fjall deploy api
fjall services api --json
```
## What happens
1. The CLI resolves the application, its ECS cluster, and its service ARNs.
2. `--service ` filters that list. Matching is case-insensitive against the live ECS service name, by exact match or suffix, so `--service worker` matches `api-worker`.
3. ECS describes each service, and Fjall reads the `PRIMARY` deployment on each one.
4. The results print as one row per service, then a verdict line.
5. The process exits 0 only when every service completed.
The command is read-only. It describes ECS services and changes nothing.
### Completion rule
A service counts as complete when ECS reports `rolloutState: COMPLETED`.
Services on a deployment controller that does not report a rollout state fall back to steady-state arithmetic: exactly one active deployment, running count equal to desired count, and zero pending tasks. A service with no `PRIMARY` deployment is never complete.
### Human output
| Column | Meaning |
| --------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `SERVICE` | ECS service name |
| `STATE` | `COMPLETED`, `IN_PROGRESS`, or `FAILED` from ECS. Falls back to `STEADY` for a complete service that reports no rollout state |
| `DESIRED` | Desired task count |
| `RUNNING` | Running task count |
| `PENDING` | Pending task count |
| `DEPLOYS` | Active deployment count. A value above 1 means an old deployment is still draining |
Each row is prefixed with `✓` when that service completed and `✗` when it has not. An incomplete service prints the ECS rollout state reason on an indented line below its row.
The run ends with either `✓ All N service(s) completed their rollout` or `✗ Not all services have completed their rollout`.
### JSON output
`--json` writes a single JSON document to stdout and silences the surrounding step output. Diagnostics and error text stay on stderr, so stdout is safe to pipe into `jq`.
```json theme={null}
{
"target": "api",
"clusterArn": "arn:aws:ecs:eu-west-1:123456789012:cluster/api",
"services": [
{
"serviceName": "api-web",
"serviceArn": "arn:aws:ecs:eu-west-1:123456789012:service/api/api-web",
"desiredCount": 2,
"runningCount": 2,
"pendingCount": 0,
"rolloutState": "COMPLETED",
"taskDefinition": "arn:aws:ecs:eu-west-1:123456789012:task-definition/api-web:42",
"activeDeployments": 1,
"completed": true
}
],
"allCompleted": true
}
```
`rolloutState`, `rolloutStateReason`, `failedTasks`, and `taskDefinition` appear only when ECS supplies them. `rolloutStateReason` is AWS-authored prose and is masked before it reaches stdout.
The JSON document is written **before** the non-zero exit on an incomplete rollout, so a CI step can parse the result and still fail the build.
### Agent mode
`fjall services` has no agent output surface. Passing `--agent`, `--budget`, `--fields`, or `--full` on the command line is refused with an error naming the alternative:
```
`fjall services` has no agent output, so --agent would be ignored: `fjall services --json` emits the same data machine-readably.
```
Use `--json` instead.
## Exit codes
| Code | Meaning |
| ---- | ------------------------------------------------------------------ |
| `0` | Every discovered service's `PRIMARY` deployment completed |
| `1` | At least one service has not completed, or the probe itself failed |
Exit 1 covers both a genuine incomplete rollout and a failed probe. Failures that land on 1 include: not signed in, no connected AWS account, an organisation-binding mismatch, no ECS services found for the application, no service matching `--service`, and a failed ECS describe call.
Distinguish the two cases from the output rather than the code. With `--json`, a completed probe always emits the document and sets `allCompleted`. A failed probe emits nothing on stdout and writes the reason to stderr.
Without `--json`, an incomplete rollout writes `Rollout incomplete for api: api-worker` to stderr, naming each service that has not converged.
## Options
| Flag | Description | Default |
| ----------------------- | ----------------------------------------------- | ----------------------- |
| `--json` | Emit JSON to stdout (machine-readable) | Off |
| `--service ` | Restrict the check to a single service by name | All services |
| `-r, --region ` | AWS region override | Not set |
| `--non-interactive` | Force plain CLI output (no UI) | Off |
| `-v, --verbose` | Enable verbose output | Off |
| `--agent` | Enable agent output mode | Refused on this command |
| `--budget ` | Output budget: minimal, compact, or token count | Refused on this command |
| `--fields ` | Select exactly these output fields | Refused on this command |
| `--full` | Disable content truncation | Refused on this command |
## Next Steps
Deploy an application to AWS, then run this check against it.
Restart running services so rotated secrets take effect.
Review recorded releases and their image tags.
Run deploys and smoke checks from a CI pipeline.