Fjall Docs — deploy AWS infrastructure into your own account

Interactive command. At a TTY, fjall deploy renders a live step checklist, a change plan, and an approval prompt before anything is applied.

Overview

fjall deploy ships one application to AWS: its infrastructure (ECS, Lambda, RDS, Aurora, networking, load balancers) and its container image. The positional argument is the application name. Tier and domain deploys are separate noun-verb commands.

Prerequisites

Logged in with fjall login.
An AWS account connected with fjall connect.
An active deployment target selected with fjall target set <name>, unless your organisation has exactly one target.

Usage

fjall deploy <app> [service] [options]

Pass the optional service positional to deploy a single service inside a multi-service application.

# Deploy the whole application
fjall deploy api

# Deploy one service within it
fjall deploy api worker

What each command deploys

Command	Deploys
`fjall deploy <app>`	Application infrastructure and code: compute, databases, networking, load balancers
`fjall org deploy`	AWS Organization root, organisational units, policies. Cascades by default
`fjall platform deploy`	The platform tier: IAM Identity Center, shared services
`fjall account deploy`	A single member account stack
`fjall domain deploy <name>`	A managed domain’s hosted zone, records, and certificates

fjall deploy organisation, fjall deploy platform, fjall deploy account and fjall deploy domain were removed. Each fails before authentication with a teaching error naming the noun-verb cure, so nothing is validated and nothing is deployed. Use the noun-verb spellings above.

$ fjall deploy platform
'fjall deploy platform' is app-only now - tier deploys are noun-verb.
Nothing was validated or deployed. Cure: run fjall platform deploy

Tier deploys

# Deploy the organisation structure (cascades to platform, domains, accounts)
fjall org deploy

# Deploy the organisation stack alone
fjall org deploy --no-cascade

# Deploy the platform stack
fjall platform deploy

# Deploy one member account stack
fjall account deploy --target production-use1

fjall org deploy cascades: organisation, then platform, then domains, then every member account. fjall platform deploy and fjall account deploy never cascade. Each tier leaf registers only the flags that tier honours. The approval-gate family (--plan, --require-approval, --auto-approve, --approval-token) and the application-scoped build flags are rejected by Commander on tier commands.

Option	Tiers	Description
`-f, --force`	all	Redeploy even when no infrastructure changes are detected
`--skip-confirmation`	all	Skip the confirmation prompts
`--target <target>`	all	Override the active target. On `account deploy` this selects the member account
`--no-cascade`	org only	Skip the platform, domains and account deploys after the organisation deploy
`--skip-caa-preflight`	org only	Pre-answer the cascade’s delegated-domain CAA preflight
`--remediate <name=verb>`	org only	Named consent for a record-takeover ticket row in the cascade’s domains phase
`--allow-replace <name>`	org only	Shorthand consent, equivalent to `--remediate <name>=recreate`
`--destruction-consent-digest <digest>`	org only	Bind consents to the ticket digest from a prior withheld run
`-e, --environment <env>`	account only	Workload stage recorded for a standalone account registration

-e, --environment on fjall account deploy is a fixed choice list (production, staging, development, platform, compliance) and stamps the stage recorded for a standalone account. It is a different flag from -e, --environment on fjall deploy, which is a free-form build-arg tier selector. See Options.

Domain deploys

fjall domain deploy example.com

fjall domain deploy <name> is the only domain-deploy spelling. Full reference: fjall domain.

Option	Description
`--skip-caa-preflight`	Pre-answer the delegated deploy’s CAA preflight, when you have verified the CAA chain out of band
`--remediate <name/TYPE=verb>`	Named consent for a record-takeover ticket row, for example `--remediate 'www.example.com/A'=recreate`
`--destruction-consent-digest <digest>`	Bind consents to the ticket digest they were minted against
`--plan`	Print the change plan plus any record-takeover ticket, then stop before any mutation (exit `2` = pending)
`--approval-token <token>`	Resume an approved plan from a prior `--plan` run. The plan digest is re-verified before deploying
`-t, --target <name>`	Deployment target to deploy into, resolved and initialised before the deploy
`-r, --region <region>`	AWS region override for the resolved target

Domain-specific semantics:

A variant record set carries its SetIdentifier in the consent name. Weighted, latency, and failover variants are classified and consented per variant: --remediate 'www.example.com/A@blue'=recreate.
--allow-replace is not registered on domain deploys. Commander rejects it rather than dropping it silently. Consent to takeover rows with --remediate instead.
Exit 4 means the takeover consent was withheld. Nothing was released and nothing was deployed. See Destructive Changes.

Interactive mode

Run without arguments for a guided deploy:

fjall deploy

The picker offers two top-level rows, then a second picker:

? What would you like to deploy?
  > Application     Cloud applications
    Organisation    AWS Foundation

? Choose an application to deploy:
  > api
    web
    dashboard

Choosing Organisation opens a component picker:

? Choose an organisation component to deploy:
  > Organisation    AWS foundation setup
    Platform        Shared services
    Account         Environment resources

Selecting Organisation there raises a cascade confirmation (Deploy Organisation, Platform and Accounts?, default Yes). Platform and Account start that single stack’s deploy with no cascade question. The progress screen can still raise a change confirmation, and an environment prompt when no --environment was passed.

Options

Option	Description	Example
`-v, --verbose`	Show detailed deployment logs	`fjall deploy api -v`
`--infra-only`	Deploy infrastructure only, skipping code	`fjall deploy api --infra-only`
`--deploy-only`	Deploy code only, skipping infrastructure	`fjall deploy api --deploy-only`
`--skip-readiness-check`	Skip the pre-deploy target readiness probe. Application deploys only, recorded as skipped in the output	`fjall deploy api --skip-readiness-check`
`-f, --force`	Redeploy all stacks even when no infrastructure changes are detected	`fjall deploy api --force`
`--target <target>`	Override the active deployment target for this deployment	`fjall deploy api --target production-use1`
`--region <region>`	Deploy to a specific region within the target’s account	`fjall deploy api --region eu-west-1`
`--all-regions`	Deploy to every region configured for the target’s account	`fjall deploy api --all-regions`
`--skip-confirmation`	Skip the deployment confirmation prompts	`fjall deploy api --skip-confirmation`
`--non-interactive`	Force plain text output with no Ink UI	`fjall deploy api --non-interactive`

Build options

Option	Description	Example
`--skip-build`	Skip the Docker build. Use with `--deploy-only` when the image is already pushed	`fjall deploy api --deploy-only --skip-build`
`--image-tag <tag>`	Roll forward or back to an existing image tag. Skips the build and implies `--deploy-only`	`fjall deploy api --image-tag api-sha-a1b2c3d4e5f6`
`--build-arg <KEY=VALUE>`	Public build-time arg baked into the image. Repeatable, highest precedence in the build-arg ladder	`fjall deploy api --build-arg NEXT_PUBLIC_ENV=prod`
`--build-secret <id=ID,ssm=PATH>`	Ad-hoc build secret reference. Repeatable. `id=ID` with one of `ssm=PATH`, `secretsManager=NAME`, `env=VAR`	`fjall deploy api --build-secret id=npm,ssm=/api/npm-token`
`-e, --environment <env>`	Selects the `.env.<stage>` build-arg tier. See the note below	`fjall deploy api --environment staging`

-e, --environment <env> does not select an account, a region, a target, or the synthesis environment. Its only live effect is choosing which .env.<stage> file supplies build args. The account comes from the active target (or --target). The synthesis environment, which decides every removal policy, is derived from the target account’s own record. See Choosing the deploy account.

Fjall image tags are content-addressed: <service>-sha-<12 hex chars of the image digest>. Find the tags for an application in its ECR repository (AWS console or aws ecr list-images). Tags like v1.4.2 are not produced by Fjall builds and will not resolve.

Plan and approval options

Option	Description	Example
`--plan`	Compute and print the resource-level change plan, then stop before any mutation (exit `0` = no changes, `2` = changes pending approval, `1` = error)	`fjall deploy api --plan`
`--require-approval`	Engage the approval gate: refuse to mutate unless the plan is approved via `--auto-approve` or a prior `--approval-token`	`fjall deploy api --require-approval`
`--auto-approve`	Approve the computed plan without prompting. Use with `--require-approval`, or in CI to proceed past changes	`fjall deploy api --auto-approve`
`--approval-token <token>`	Resume an approved plan from a prior `--plan` run. The plan digest is re-verified before applying	`fjall deploy api --approval-token <token>`

Destructive-change and gate options

These satisfy the destruction gate when a deploy would destroy or replace a stateful resource.

Option	Description	Example
`--remediate <name=verb>`	Named consent for a pending destructive change. Repeatable, exact and case-sensitive physical name	`fjall deploy api --remediate api-db=recreate`
`--allow-replace <name>`	Shorthand consent to replace the named resource. Repeatable, equivalent to `--remediate <name>=recreate`	`fjall deploy api --allow-replace api-db`
`--destruction-consent-digest <digest>`	Bind consents to the `ticket digest:` line printed under the ticket, by a prior `--plan` run or by the withheld run that asked for consent. The deploy withholds if the pending destructive changes have changed since that digest was printed.	`fjall deploy api --remediate api-db=recreate --destruction-consent-digest <digest>`
`--acknowledge-immutable-vault-lock`	Acknowledge that `vaultLock: compliance` creates a permanently immutable backup vault. Required before that stack deploys	`fjall deploy api --acknowledge-immutable-vault-lock`

CI/CD options

Option	Description	Example
`--deployment-id <id>`	Deployment record ID used for progress tracking against fjall.io	`fjall deploy api --deployment-id dep_01hz…`
`--force-untracked`	Proceed when the deployment cannot be registered with fjall.io. The only escape hatch for a tracked-deploys organisation. Prints a warning and audits the deploy	`fjall deploy api --force-untracked`

Every command node also accepts the agent-output flags --agent, --budget <level>, --fields <list> and --full. See Agent mode.

Subcommands

Command	Description
`fjall deploy diff <idA> <idB>`	Compare two deployment records
`fjall deploy logs --deployment-id <id>`	Analyse the logs for a deployment record

Choosing the deploy account

A deploy lands in the active deployment target, an account plus region pair named <accountname>-<regionabbrev>, for example production-use1 or development-euw1.

Step	Command
List derived targets (active marked with `▸`)	`fjall target list`
Show the active target	`fjall target get`
Set the active target	`fjall target set production-use1`

At deploy time the account resolves through one fail-closed chain:

--target <name>, when present. An unknown name is a hard error listing the valid targets, never a silent fallback.
Otherwise the activeTarget recorded in .fjall/local.json.
Otherwise auto-select, when exactly one target exists, or the root account’s profile when there are none.
Otherwise refuse, listing the candidate targets.

--region overrides the region within the resolved target’s account. From fjall 38 a named --target resolves from an organisation config that is fresh or inside the five-minute cache TTL. An unreachable API with an expired cache fails with Failed to fetch organisation config: … rather than resolving from an older cached copy. Steps 2 to 4 keep the cache-first read with its stale fallback.

activeTarget lives in the gitignored .fjall/local.json, written by fjall target set. A legacy activeTarget inside the committed fjall-config.json is read only to print a deprecation warning and is ignored for resolution. Never commit or hand-edit an active target: a committed value that re-aims a CI pipeline is how a deploy lands in the wrong account.

Targets are derived at runtime from your organisation config, fetched from the Fjall API. Accounts, regions, OIDC role ARNs and SSO sessions are never authored by hand in a repository file. See Understanding Profiles. The synthesis environment is derived from the target account’s own record, not from a flag. The organisation tier resolves to root, and every other account resolves to its recorded stage. The deploy fails closed when that cannot be resolved, because the environment decides every removal policy: production retains data on stack deletion, every other stage destroys it.

What happens during a deploy

1. Pre-flight checks

Fjall validates AWS credentials and permissions, confirms the target exists, checks required dependencies, and probes the stacks for resources deleted outside CloudFormation. A confirmed out-of-band deletion blocks the deploy and points you at fjall drift. The same pre-flight refuses to start while any target stack is mid-operation or in a state it cannot classify. Each stack is checked in its own region, so an ApiUsEast1Certificates or ApiUsEast1CdnLogging stack busy in us-east-1 blocks the deploy. There is no --force bypass here: unlike fjall destroy, deploying over an in-flight operation is never a recovery.

2. Pre-deployment checklist

A full deploy streams a checklist of four steps, in this order:

✓ Detecting application pattern
✓ Synthesising infrastructure
✓ Comparing template hashes
✓ Validating SSM secrets

--deploy-only and --image-tag skip the checklist, SSM secrets validation included. No build appears in this checklist, for any application: a framework build, and a Payload app’s import map, run before it and outside it. On fjall 39.x, build a Payload app at the project root and deploy with --skip-build, as Build and deploy describes. Without --skip-build, the deploy writes the import map and builds in fjall/<app>, which fails for the layout fjall create app produces. Missing SSM secrets raise a Missing N of M required SSM secret(s) block and a Deploy anyway? confirmation, defaulting to No.

3. Change plan and approval gate

When nothing changed, the run short-circuits before the gate with an Already up to date message and applies nothing. With changes, the approval gate is engaged by default at a TTY. A bordered card renders the plan, then a Yes/No selector defaulting to No.

┌───────────────────────────────────────────────────────────────────────────┐
│ Deployment plan for api                                                   │
│                                                                           │
│ 2 to create, 1 to replace, 1 to destroy (2 destructive, 1 with data loss) │
│                                                                           │
│ + create  AWS::EC2::SecurityGroup  ApiNetwork/AlbSg                       │
│ + create  AWS::ECS::Cluster  ApiCompute/Cluster                           │
│ ± replace AWS::ECS::Service  ApiCompute/Service                           │
│ - delete  AWS::RDS::DBInstance  ApiDatabase/Db (data loss)                │
│                                                                           │
│ ! This plan includes destructive changes (replace or destroy).            │
└───────────────────────────────────────────────────────────────────────────┘

? Approve this plan and deploy?  ▸ Yes  No

Change symbols: + create, ~ update, ± replace, - delete, > read. --skip-confirmation and --auto-approve drop this prompt. Non-interactive and CI runs show no plan unless you pass --plan or --require-approval.

If the plan would destroy or replace a stateful resource, a further per-resource consent ceremony runs, with a typed resource name. No flag skips it. See Destructive Changes.

4. Deployment execution

Fjall creates or updates the CloudFormation stacks, streams per-resource events, handles stack dependencies, and reports errors as they arrive. Concurrent stacks render in a parallel panel.

5. Post-deployment

Fjall prints the application’s website URL, next steps, and a version banner. When the deploy replaced the database, it offers to restart the affected services so they reconnect.

Examples

Deploy an application

# Guided selection
fjall deploy

# Direct
fjall deploy api

# CI/CD
fjall deploy api --non-interactive --auto-approve

Infrastructure versus code

# Infrastructure changes only
fjall deploy api --infra-only

# Application code only, which is faster
fjall deploy api --deploy-only

# Roll back to a known-good image tag
fjall deploy api --image-tag api-sha-a1b2c3d4e5f6

Plan first, then approve

# Print the plan and stop. Exit 2 means changes are pending approval
fjall deploy api --plan

# Resume the approved plan
fjall deploy api --approval-token <token>

The plan is the run’s result, so it goes to stdout: the Deploy plan: <summary> line, one line per change, the destruction ticket and its ticket digest: line when the plan has destructive rows, and Approval token: <token>. The Plan computed for <app> — no infrastructure was modified. note, the consent instruction and the Apply with: line are conversation on stderr. So fjall deploy api --plan > plan.txt captures the plan, the ticket and the token, and nothing else. fjall domain deploy example.com --plan splits its output the same way.

Deploy the organisation for the first time

# Cascades to platform, domains, and accounts
fjall org deploy

# Or deploy each tier independently
fjall platform deploy
fjall account deploy --target production-use1

Understanding output

Where the output goes

On the non-interactive path (a pipe, a redirect, --non-interactive, or CI) a deploy splits its output across two streams.

Stream	Carries
`stdout`	The application’s website URL, and nothing else on an applying deploy
`stderr`	Progress, step headers, the summary, and the `Next Steps:` block

The URL is the deploy’s result, so a shell captures it with nothing to strip.

URL=$(fjall deploy api --non-interactive)

The Next Steps: block names the URL again on stderr, under Visit your site: or Visit your url:, or as Setup your account: with /admin appended, depending on the application pattern. A deploy writes nothing to stdout when the application has neither a load balancer nor a CloudFront distribution, such as a Lambda-only or queue-worker application. A failed deploy writes nothing to stdout either, so branch on the exit code rather than on whether stdout was empty. --plan is the exception. The plan is that run’s result, so the plan rows and the Approval token: line are what lands on stdout. See Plan first, then approve. At a TTY the interactive screen draws on stdout as usual. The split above describes the non-interactive lane.

Progress indicators

ApiStack | 0/12  | 10:45:23 AM | REVIEW_IN_PROGRESS
ApiStack | 2/12  | 10:45:45 AM | CREATE_IN_PROGRESS | AWS::EC2::VPC
ApiStack | 4/12  | 10:46:12 AM | CREATE_IN_PROGRESS | AWS::RDS::DBCluster
ApiStack | 12/12 | 10:52:33 AM | CREATE_COMPLETE

Handling failures

Symptom	Cause	Fix
`User does not have permission to create IAM roles`	The deploy role lacks IAM permissions	Grant the connected account’s deploy role `AdministratorAccess`
`Stack with id ApiStack already exists`	A stack of that name is already live	Run `fjall destroy <app>` first, or choose a different name
`Unable to locate credentials`	The AWS or Fjall session has expired	Run `fjall connect`, or `fjall login`
`InvalidBucketAclWithObjectOwnership` on the access-log bucket	From fjall 38 the stack’s shared access-log bucket is `BucketOwnerEnforced`. CloudFront’s legacy standard logging (fjall 33.0.0 to 37.x) left an `awslogsdelivery` `FULL_CONTROL` ACL grant on it that S3 will not flip over	Run `aws s3api put-bucket-acl --bucket <access-log-bucket-name> --acl private` once, then redeploy. Objects already in the bucket are unaffected
`No deployable ECS services or container-image Lambda functions found for api`	A code-only run (`--deploy-only`, or `--image-tag` / `fjall rollback`) found no live ECS services or container-image Lambda functions. The run applies nothing, reports no changes and exits `0`	Deploy the infrastructure first with `fjall deploy api`. Through fjall 37 a hyphenated application name landed here against a healthy deployment, which fjall 38 fixes
`Cannot start this deployment — a CloudFormation stack is not available`	A target stack is mid-operation, or in a state Fjall cannot classify	Wait for the in-flight operation to finish, then rerun. No flag bypasses this

If a deploy fails:

Read the error for the specific failure message.
Check the stack in the CloudFormation console for resource-level detail.
Let CloudFormation roll back, which it does automatically on failure.
Fix the cause and rerun.

Exit codes

Code	Meaning
`0`	Deployed, or nothing to change
`1`	A real error
`2`	Plan pending approval, or rejected at the approval gate (`--plan`, `--require-approval`)
`4`	The destruction ceremony stopped the deploy: consent withheld, declined, invalid, not yet executable, or a consented `pin` was applied and the deploy stopped for the config write-back. Nothing was applied to AWS
`64`	A prerequisite is missing (Docker buildx)

Best practices

Read the plan card before approving. It names every replace and every data-loss row.
Deploy to a non-production target first.
Run --plan in CI and gate the apply on the returned token.
Back up data before a change that replaces a database.

Next Steps

Destructive changes

Understand the consent ceremony and exit code 4.

Understanding profiles

See how authentication and account selection are derived.

Detect drift

Find and repair resources changed outside CloudFormation.

Roll back a release

List recorded releases and roll back to a known-good one.

A first deployment typically takes 10 to 15 minutes. Later deploys are faster, because only changed resources are modified.

​Overview

​Prerequisites

​Usage

​What each command deploys

​Tier deploys

​Domain deploys

​Interactive mode

​Options

​Build options

​Plan and approval options

​Destructive-change and gate options

​CI/CD options

​Subcommands

​Choosing the deploy account

​What happens during a deploy

​1. Pre-flight checks

​2. Pre-deployment checklist

​3. Change plan and approval gate

​4. Deployment execution

​5. Post-deployment

​Examples

​Deploy an application

​Infrastructure versus code

​Plan first, then approve

​Deploy the organisation for the first time

​Understanding output

​Where the output goes

​Progress indicators

​Handling failures

​Exit codes

​Best practices

​Next Steps

Destructive changes

Understanding profiles

Detect drift

Roll back a release

Overview

Prerequisites

Usage

What each command deploys

Tier deploys

Domain deploys

Interactive mode

Options

Build options

Plan and approval options

Destructive-change and gate options

CI/CD options

Subcommands

Choosing the deploy account

What happens during a deploy

1. Pre-flight checks

2. Pre-deployment checklist

3. Change plan and approval gate

4. Deployment execution

5. Post-deployment

Examples

Deploy an application

Infrastructure versus code

Plan first, then approve

Deploy the organisation for the first time

Understanding output

Where the output goes

Progress indicators

Handling failures

Exit codes

Best practices

Next Steps