Fjall Docs — Deploy Production-Ready AWS Infrastructure in Minutes

Interactive command. Guides you through selecting and deploying targets with real-time feedback.

Overview

fjall deploy ships your infrastructure to AWS. It handles organisation-level deployments (AWS Organization, SSO, accounts) and application deployments (compute, storage, networking).

Prerequisites

Logged in with fjall login.
An AWS account connected with fjall connect.
In organisation mode, an active deployment target selected with fjall target set <name>.

Usage

fjall deploy [target] [service] [options]

Deploy Targets

target accepts an application name, one of organisation, platform, or account, or domain <name>. All are standalone deployable targets.

Target	Deploys
`<app-name>`	Application infrastructure (ECS, Lambda), databases (RDS, Aurora, DynamoDB), networking, load balancers
`organisation`	AWS Organization root, organisational units, service control policies, cost allocation tags
`platform`	AWS SSO configuration, shared services, IPAM pools, transit gateways
`account`	A single member account stack
`domain <name>`	A managed domain’s hosted zone, records, and certificates (see below)

Cascade behaviour

organisation cascades: it deploys the organisation infrastructure, then the platform and every member account. Opt out with --no-cascade to deploy the organisation stack alone. platform and account never cascade. Each deploys its own stack only.

# Deploy an application
fjall deploy api

# Deploy the organisation structure (cascades to platform + accounts)
fjall deploy organisation

# Deploy the organisation stack only
fjall deploy organisation --no-cascade

# Deploy the platform stack alone
fjall deploy platform

Deploying a domain

fjall deploy domain example.com

fjall deploy domain <name> routes through the same operation as fjall domain deploy <name> — the two spellings have identical flags and exit semantics.

Option	Description
`--skip-caa-preflight`	Pre-answer the delegated deploy’s CAA preflight (you have verified the CAA chain out of band)
`--remediate <name/TYPE=verb>`	Named consent for a record-takeover ticket row when adopting a live zone (e.g. `--remediate 'www.example.com/A'=recreate`; a weighted/latency/failover variant row carries its SetIdentifier: `--remediate 'www.example.com/A@blue'=recreate`)
`--destruction-consent-digest <digest>`	Bind consents to the ticket digest they were minted against
`--plan`	Compute and print the resource-level change plan plus any record-takeover ticket, then stop before any mutation (exit `2` = changes pending approval)
`--approval-token <token>`	Resume an approved plan from a prior `--plan` run; the plan digest is re-verified before deploying

Domain-specific semantics:

--allow-replace is rejected on domain deploys — not silently dropped. Consent to takeover rows with --remediate '<name>/<TYPE>'=recreate — or --remediate '<name>/<TYPE>@<setIdentifier>'=recreate when the live record set carries a SetIdentifier (weighted, latency, and failover variants are classified and consented per variant).
Exit 4 means the takeover consent was withheld: success-shaped, nothing released, nothing deployed. See Destructive Changes.
--plan runs the same two-step as application deploys — a domain plan additionally prints any record-takeover ticket, exits 2 when changes are pending approval (nothing mutated), and resumes via --approval-token.

Interactive Mode

Run without arguments for guided deployment:

fjall deploy

The picker asks what to deploy, then which application:

? What would you like to deploy today?
  ❯ Application - Cloud applications
    Organisation - AWS foundation

? Select application to deploy:
  ❯ api
    web
    dashboard

Choosing Organisation shows a cascade confirmation (Deploy Organisation, Platform and Accounts?). Choosing Platform or Account deploys that single stack immediately with no cascade prompt.

Options

Option	Description	Example
`-v, --verbose`	Show detailed deployment logs	`fjall deploy -v`
`--infra-only`	Deploy infrastructure only (skip code)	`fjall deploy api --infra-only`
`--deploy-only`	Deploy code only (skip infrastructure)	`fjall deploy api --deploy-only`
`--skip-build`	Skip the Docker image build (use with `--deploy-only` when the image is already pushed)	`fjall deploy api --skip-build`
`--skip-migrations`	Skip database migrations during this deployment	`fjall deploy api --skip-migrations`
`--skip-readiness-check`	Skip the pre-deploy target readiness probe (application deploys only; the step is recorded as skipped in output)	`fjall deploy api --skip-readiness-check`
`-f, --force`	Redeploy all stacks even when no infrastructure changes are detected	`fjall deploy api --force`
`--image-tag <tag>`	Roll forward or back to an existing image tag (skips build, implies `--deploy-only`)	`fjall deploy api --image-tag api-sha-a1b2c3d4e5f6`
`--target <target>`	Override the active deployment target for this deployment	`fjall deploy api --target production-us-use1`
`--region <region>`	Deploy to a specific region within the target’s account	`fjall deploy api --region eu-west-1`
`--all-regions`	Deploy to all regions for the target’s account	`fjall deploy api --all-regions`
`-e, --environment <env>`	Free-form CI/CD label passed to CDK synthesis	`fjall deploy api --environment prod`
`--no-cascade`	Skip automatic platform and account deployment after an organisation deploy	`fjall deploy organisation --no-cascade`
`--skip-confirmation`	Skip the deployment confirmation prompt	`fjall deploy api --skip-confirmation`
`--non-interactive`	Force plain CLI output (no UI)	`fjall deploy api --non-interactive`

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>`

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, case-sensitive physical name)	`fjall deploy api --remediate api-db=recreate`
`--allow-replace <name>`	Shorthand consent: allow the named resource to be replaced (repeatable; equivalent to `--remediate <name>=recreate`)	`fjall deploy api --allow-replace api-db`
`--destruction-consent-digest <digest>`	Bind consents to the ticket digest from a prior `--plan` run; the deploy withholds if the pending destructive changes have changed since the plan	`fjall deploy api --remediate api-db=recreate --destruction-consent-digest <digest>`

-e, --environment <env> does not select an account or region. It is an optional free-form label for CI/CD that flows into CDK synthesis as a context value. The account is chosen by the active target (or --target), not by --environment.

Choosing the Deploy Account

In organisation mode, the account a deploy lands in is the active deployment target, an account plus region pair named <accountname>-<regionabbrev> (for example production-us-use1).

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-us-use1`

At deploy time the account resolves in this order:

The per-deploy --target <name> flag, when present.
Otherwise the activeTarget stored in fjall-config.json. With exactly one target it is selected automatically; with several you must run fjall target set first.

Targets are derived at runtime from your organisation config (fetched from the Fjall API), not authored by hand. See Understanding Profiles for how authentication and account selection fit together.

Deployment Process

1. Pre-flight Checks

Fjall validates:

AWS credentials and permissions
Target exists and is valid
Required dependencies installed
No conflicts with existing resources
The stacks are not wedged by resources deleted outside CloudFormation (a confirmed out-of-band deletion blocks the deploy and points you at fjall drift)

2. Infrastructure Synthesis

For each deployment, Fjall:

Compiles the TypeScript CDK code
Generates CloudFormation templates
Calculates resource changes
Identifies security implications

3. Deployment Preview

Deploying api...
Build complete
Synthesis complete

Resources to create:
  + AWS::ECS::Cluster (ApiCluster)
  + AWS::ECS::Service (ApiService)
  + AWS::RDS::DBCluster (ApiDatabase)
  + AWS::ElasticLoadBalancingV2::LoadBalancer
  + AWS::EC2::SecurityGroup (3)

Security Changes:
  New IAM policies will be created

Deploy? (y/N)

If the computed plan would destroy or replace a stateful resource, the deploy stops at an unconditional gate before anything is applied and asks for consent by exact resource name. No flag skips it. See Destructive Changes.

4. Deployment Execution

Fjall creates the CloudFormation stacks, monitors progress, handles dependencies, and reports errors immediately.

5. Post-Deployment

After a successful deployment, Fjall displays resource endpoints, connection strings, next steps, and updates local configuration.

Examples

Deploy the organisation first time

# Deploy organisation structure (cascades to platform + accounts)
fjall deploy organisation

# Or deploy each stack independently
fjall deploy platform
fjall deploy account

Deploy an application

# Interactive selection
fjall deploy

# Direct deployment
fjall deploy api

# Non-interactive (CI/CD)
fjall deploy api --non-interactive

Infrastructure vs code

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

# Application code only (faster)
fjall deploy api --deploy-only

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

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.

Understanding Output

Success output

Deployment complete

Outputs:
  LoadBalancerURL: http://api-123456.us-east-1.elb.amazonaws.com
  DatabaseEndpoint: api-db.cluster-abc123.us-east-1.rds.amazonaws.com

Your application is now live.

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

Common issues

Permission denied
User does not have permission to create IAM roles
Fix: Give your AWS user AdministratorAccess.
Resource already exists
Stack with id ApiStack already exists
Fix: Run fjall destroy first, or choose a different name.
Invalid credentials
Unable to locate credentials
Fix: Run fjall connect to re-establish your AWS connection, or fjall login to re-authenticate with Fjall.

Recovery steps

If a deployment fails:

Read the error for the specific failure message.
Check CloudFormation in the AWS Console for stack-level detail.
Roll back if needed (CloudFormation auto-rolls-back on failure).
Fix and retry once you have addressed the issue.

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

Review changes before confirming the deployment preview.
Deploy incrementally, starting with non-production targets.
Use verbose mode (-v) for troubleshooting.
Back up data before major changes.

Next Steps

List resources

Inspect the resources in an application’s infrastructure.

Add resources

Add a database, storage, or compute resource.

Manage secrets

Store and read application secrets in AWS.

Understanding Profiles

See how auth and account selection are derived.

First deployment typically takes 10-15 minutes. Subsequent updates are faster as only changed resources are modified.

Core Commands

Infrastructure Codemods

Management Commands

Authentication

Agent Mode

fjall deploy

Overview

Prerequisites

Usage

Deploy Targets

Cascade behaviour

Deploying a domain

Interactive Mode

Options

Plan and approval options

Choosing the Deploy Account

Deployment Process

1. Pre-flight Checks

2. Infrastructure Synthesis

3. Deployment Preview

4. Deployment Execution

5. Post-Deployment

Examples

Deploy the organisation first time

Deploy an application

Infrastructure vs code

Understanding Output

Success output

Progress indicators

Handling Failures

Common issues

Recovery steps

Exit Codes

Best Practices

Next Steps

List resources

Add resources

Manage secrets

Understanding Profiles

​Overview

​Prerequisites

​Usage

​Deploy Targets

​Cascade behaviour

​Deploying a domain

​Interactive Mode

​Options

​Plan and approval options

​Destructive-change consent options

​Choosing the Deploy Account

​Deployment Process

​1. Pre-flight Checks

​2. Infrastructure Synthesis

​3. Deployment Preview

​4. Deployment Execution

​5. Post-Deployment

​Examples

​Deploy the organisation first time

​Deploy an application

​Infrastructure vs code

​Understanding Output

​Success output

​Progress indicators

​Handling Failures

​Common issues

​Recovery steps

​Exit Codes

​Best Practices

​Next Steps

List resources

Add resources

Manage secrets

Understanding Profiles

Overview

Prerequisites

Usage

Deploy Targets

Cascade behaviour

Deploying a domain

Interactive Mode

Options

Plan and approval options

Destructive-change consent options

Choosing the Deploy Account

Deployment Process

1. Pre-flight Checks

2. Infrastructure Synthesis

3. Deployment Preview

4. Deployment Execution

5. Post-Deployment

Examples

Deploy the organisation first time

Deploy an application

Infrastructure vs code

Understanding Output

Success output

Progress indicators

Handling Failures

Common issues

Recovery steps

Exit Codes

Best Practices

Next Steps