Fjall Docs — deploy AWS infrastructure into your own account

Overview

Every deploy records a release: the image tag that went live for each service, the git commit and branch it was built from, and a monotonically increasing release number. Two commands work with that history:

Command	What it does
`fjall releases <app>`	List the recorded releases, newest first
`fjall rollback <app>`	Roll the running services back to a previous release’s recorded images

A rollback is a code-only operation. It re-registers each service’s task definition (or republishes the Lambda function) against images that already exist in ECR, then rolls the services. Nothing is rebuilt and your infrastructure is not re-synthesised.

Prerequisites

Requirement	How to satisfy it
A Fjall session	`fjall login`
A connected AWS account (rollback)	`fjall connect`
The project on disk (rollback)	Run from the project that owns the application, so `<app>/infrastructure.ts` resolves
Matching organisation binding	Run inside a project bound to the same organisation as your Fjall credential
A prior successful deploy	Releases are recorded by `fjall deploy`, so the history is empty until an application has deployed

fjall releases reads the Fjall API only, so it works from any directory. fjall rollback deploys, so it runs from the project.

List Releases

fjall releases api

  RELEASE   STATUS       COMMIT    BRANCH         AGE          SERVICES
▸ #12       live         ab12cd3   main           2h ago       api:api-sha-ab12cd3f9e01, worker:…
  #11       superseded   9f8e7d6   main           1d ago       api:api-sha-9f8e7d6c5b40, worker:…
  #10       rolled-back  5a4b3c2   main           3d ago       api:api-sha-5a4b3c2d1e98, worker:… (rollback)

  3 releases (--cursor 10 for more)

Column	Meaning
`RELEASE`	Release number. `▸` marks the release currently live
`STATUS`	`live`, `superseded`, or `rolled-back`
`COMMIT`	First 7 characters of the git commit the images were built from
`BRANCH`	Branch the deploy ran from
`AGE`	Relative time since the release was recorded, for example `2h ago`
`SERVICES`	`<service>:<imageTag>` per service, truncated to fit the column

A (rollback) suffix marks a release that restored an earlier one. Fjall derives image tags as <serviceName>(-<target>)?-sha-<12 hex digits>, so an api service built from digest sha256:ab12cd3f9e01… gets the tag api-sha-ab12cd3f9e01.

Options

Option	Description
`--json`	Emit the raw API response as JSON on stdout
`--limit <n>`	Maximum releases to return (default 20, maximum 100)
`--cursor <releaseNumber>`	Pagination cursor, an exclusive upper bound on the number
`-v, --verbose`	Show detailed output
`--non-interactive`	Force plain output with no UI
`--agent`	Refused, see Agent Mode
`--budget <level>`	Refused, see Agent Mode
`--fields <fields>`	Refused, see Agent Mode
`--full`	Refused, see Agent Mode

JSON Output

fjall releases api --json --limit 1

{
  "releases": [
    {
      "id": "rel_01J8K3XQ",
      "releaseNumber": 12,
      "status": "live",
      "commitSha": "ab12cd3f9e0142a7c8b5d6e3f0a1b2c3d4e5f607",
      "branch": "main",
      "createdAt": "2026-09-04T09:14:22.000Z",
      "assemblyDigest": "b7f3a1c9e2d4",
      "createdByDeploymentId": "dep_01J8K3XQ",
      "rollbackOfReleaseId": null,
      "services": [
        {
          "serviceName": "api",
          "imageTag": "api-sha-ab12cd3f9e01",
          "imageUri": "123456789012.dkr.ecr.eu-west-1.amazonaws.com/api:api-sha-ab12cd3f9e01",
          "imageDigest": "sha256:ab12cd3f9e0142a7c8b5d6e3f0a1b2c3d4e5f607",
          "taskDefinitionArn": "arn:aws:ecs:eu-west-1:123456789012:task-definition/api:41"
        }
      ]
    }
  ],
  "currentReleaseId": "rel_01J8K3XQ",
  "nextCursor": 12
}

nextCursor carries the last returned release number and is present only when more releases exist. Pass it back as --cursor to fetch the next page.

Roll Back

# Roll back to the release immediately before the current live release
fjall rollback api

# Roll back to a specific release
fjall rollback api --to 11

The CLI prints the resolved target before asking to proceed:

Rolling back api:
  From: #12
  To:   #11 (9f8e7d6)
          api: api-sha-9f8e7d6c5b40
          worker: worker-sha-9f8e7d6c5b40

Roll back api to release #11? (y/N):

The rollback is recorded as a new release pointing at the release it restored, so the history stays linear and auditable. The prompt appears only in an interactive terminal. --non-interactive skips it, and so does any invocation whose stdout is not a terminal, such as a pipe, a redirect or a CI job. Gate the command upstream in a pipeline.

Options

Option	Description
`--to <releaseNumber>`	Release to roll back to. Defaults to the highest release number below the current live release
`--skip-confirmation`	Skip the confirmation prompt
`-v, --verbose`	Show detailed output
`--non-interactive`	Force plain output with no UI, and proceed without the confirmation prompt
`--agent`	Refused, see Agent Mode
`--budget <level>`	Refused, see Agent Mode
`--fields <fields>`	Refused, see Agent Mode
`--full`	Refused, see Agent Mode

What a Rollback Does and Doesn’t

Does register a fresh task-definition revision per service pinned to the target release’s recorded image tag, then roll each ECS service. Container-image Lambda functions are updated and republished the same way.
Does reconcile the Compute stack’s <Service>ImageTag parameters afterwards, so the next full deploy does not silently revert the rollback.
Doesn’t build or push an image, run migrations, or synthesise and deploy your infrastructure. Only the running code moves.

Rollback Window

Fjall protects the AWS artefacts (ECR images and task definitions) referenced by the 25 most recent releases. Older releases still appear in the history, but their images may have been pruned and are no longer guaranteed to be rollable. --to resolves against the 100 most recent releases. If the number is outside that page, the CLI lists the release numbers it did find rather than guessing.

Refusals

fjall rollback fails closed before touching AWS when:

Condition	What the CLI reports
The application has no recorded releases	Nothing to roll back to
`--to` names a release outside the 100 most recent	Not found, with the available release numbers listed
No live release is recorded, or it is outside the fetched page	Asks you to name a target with `--to <releaseNumber>`
The current release is the oldest one	No earlier release to roll back to
The target is already the live release	Already live
The target release recorded no service artefacts	Nothing to roll back to

When the target release’s infrastructure assembly digest differs from the current release’s, the CLI prints a warning before the prompt: an image rollback does not restore infrastructure changes made since that release. A rollback cancelled at the prompt applies nothing. A rollback stopped by a remote cancel or an approval gate exits with code 2, which means “stopped by decision”, not “failed”. One outcome is not a refusal. When service discovery finds no ECS services and the manifest in <app>/cdk.out lists no container-image Lambda functions, the rollback applies nothing, still reports success, and exits with code 0:

  [warn] No deployable ECS services or container-image Lambda functions found for api
  [log] Rollback of api to release #11 completed successfully

The [warn] line is the verdict, not the success line that follows it. From fjall 38 an application name containing a hyphen resolves its ECS services correctly. Through fjall 37 a hyphenated name matched no …DeployableService export at all, so a rollback rolled only the application’s container-image Lambda functions, and landed here when it had none.

Rolling back restores code, not data. If the release you are leaving ran database migrations, check the older code against the current schema before rolling back.

Agent mode

Neither command has an agent output surface. Writing --agent, --budget, --fields, or --full on the command line is refused before the command runs, with an error naming the alternative:

`fjall releases` has no agent output, so --agent would be ignored: `fjall releases <app> --json` emits the same data machine-readably.

For fjall releases, use --json. fjall rollback has no machine-readable output at all. Run it without the flag, read the exit code, then confirm the active release with fjall releases <app> --json.

Next Steps

fjall rollout

Restart running services in place so rotated secrets take effect, with no image change.

fjall deploy

Build and deploy a new release to AWS.

fjall build

Build and push a service image without deploying it.

Deployment safety

Approval gates, plan mode, and the guards around a risky deploy.

Core Commands

Infrastructure Codemods

Insights

Management Commands

Build & CI

Environments & Data

Diagnostics & Recovery

Authentication

Agent Mode

fjall releases & rollback

Overview

Prerequisites

List Releases

Options

JSON Output

Roll Back

Options

What a Rollback Does and Doesn’t

Rollback Window

Refusals

Agent mode

Next Steps

fjall rollout

fjall deploy

fjall build

Deployment safety

​Overview

​Prerequisites

​List Releases

​Options

​JSON Output

​Roll Back

​Options

​What a Rollback Does and Doesn’t

​Rollback Window

​Refusals

​Agent mode

​Next Steps

fjall rollout

fjall deploy

fjall build

Deployment safety

Overview

Prerequisites

List Releases

Options

JSON Output

Roll Back

Options

What a Rollback Does and Doesn’t

Rollback Window

Refusals

Agent mode

Next Steps