Fjall Docs — Deploy Production-Ready AWS Infrastructure in Minutes

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.

Prerequisites

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

fjall services <app>

The <app> positional argument is required.

# 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:

fjall deploy api
fjall services api --json

What happens

The CLI resolves the application, its ECS cluster, and its service ARNs.
--service <name> filters that list. Matching is case-insensitive against the live ECS service name, by exact match or suffix, so --service worker matches api-worker.
ECS describes each service, and Fjall reads the PRIMARY deployment on each one.
The results print as one row per service, then a verdict line.
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.

{
  "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 <app> --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 <name>`	Restrict the check to a single service by name	All services
`-r, --region <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 <level>`	Output budget: minimal, compact, or token count	Refused on this command
`--fields <fields>`	Select exactly these output fields	Refused on this command
`--full`	Disable content truncation	Refused on this command

Next Steps

fjall deploy

Deploy an application to AWS, then run this check against it.

fjall rollout

Restart running services so rotated secrets take effect.

fjall releases

Review recorded releases and their image tags.

fjall ci

Run deploys and smoke checks from a CI pipeline.

Core Commands

Infrastructure Codemods

Insights

Management Commands

Build & CI

Environments & Data

Diagnostics & Recovery

Authentication

Agent Mode

fjall services

Check rollout status

What happens

Completion rule

Human output

JSON output

Agent mode

Exit codes

Options

Next Steps

fjall deploy

fjall rollout

fjall releases

fjall ci

​Check rollout status

​What happens

​Completion rule

​Human output

​JSON output

​Agent mode

​Exit codes

​Options

​Next Steps

fjall deploy

fjall rollout

fjall releases

fjall ci

Check rollout status

What happens

Completion rule

Human output

JSON output

Agent mode

Exit codes

Options

Next Steps