Fjall Docs — deploy AWS infrastructure into your own account

An organisation sits at the top of the Fjall hierarchy. Deploying one provisions a multi-account AWS Organizations structure, organisational units, and the governance baseline your applications build on. The order is create, connect, then deploy. Scaffolding writes files only. fjall connect establishes OIDC trust with AWS. fjall org deploy is the first command that changes anything in AWS.

Prerequisites

Install the Fjall CLI (requires Node 22 or later)
Sign in with fjall login. Credentials land in ~/.fjall/auth.json (or $FJALL_CONFIG_DIR/auth.json)
A Pro plan or above. Organisation management is gated on it, and the CLI stops with “Organisation management requires a Pro plan.” otherwise

Do not run fjall connect before fjall create organisation. The first connect after an organisation scaffold binds the AWS Organizations management account. Without the fjall/organisation scaffold on disk, the same connect falls through to the workload stage picker and registers the account as an ordinary workload account.

1. Create the organisation

Run this at the root of your project:

fjall create organisation

2. Answer the prompts

The interactive flow asks for, in order:

Prompt	Detail
Name your organisation?	Scaffold identifier. Seeded from your Fjall identity when you omit `--name`
Email for account setup?	Admin email tied to AWS account creation, for example `engineering@example.com`
Select your primary AWS region?	Default region for IAM Identity Center and IPAM pools. Suggested from your timezone
Select secondary AWS regions (optional)?	Multi-select, maximum 10. Can be left empty
Enable disaster recovery for production deployments?	Yes or no, defaults to yes
Select disaster recovery region?	Shown only when disaster recovery is enabled
Governance profile	Essentials, Monitored, Regulated, or Enforced

A review list follows, then a final “Create organisation with these settings?” confirmation.

Your primary region and secondary region set are written to the organisation config the moment you confirm. That write is an organisation-wide lock: a later create passing a different primary region fails rather than moving it. Choose the region you intend to keep.

Use a monitored inbox for the account email. With centralised root access enabled (the default), member accounts hold no root credentials, and AWS root password recovery (the “Allow password recovery” privileged task) delivers its reset link to this address.

Governance profiles

Interactive label	`--security` value	What it adds
Essentials	none	AWS-native protections, no extra cost
Monitored	`foundation`	Threat detection: GuardDuty, Security Hub
Regulated	`compliance`	Audit trails, vulnerability scanning
Enforced	`hardened`	SCPs, access policies, config rules

Profiles above Essentials are checked against your plan before any file is written. The profile also selects the content of the deploy-role permissions boundary that every member account’s deploy role is capped with. That cap is on regardless of the profile you choose: Essentials writes no securityTier, and a scaffold with no tier still renders the boundary at hardened. The profile decides which ceiling the deploy role gets, and which security services the account scaffold enables — never whether there is a ceiling at all.

What happens after you confirm

The CLI runs two steps, “Generating organisation structure” and “Installing dependencies”. It scaffolds fjall/organisation, fjall/platform and fjall/account, runs npm install in each, and records the organisation id in fjall-config.json so the project is bound to one organisation. An npm install failure is not fatal. It surfaces as a warning with a “Run ‘npm install’ in each fjall/ subdirectory” follow-up.

Creating an organisation deploys nothing to AWS and opens no browser. The completion screen points at fjall connect, which is where OIDC trust is established.

Figure: Creating your organisation via the Fjall CLI.

3. Review the infrastructure file

Fjall generates the organisation definition at fjall/organisation/infrastructure.ts. The default layout is five accounts, each mapped to its organisational unit:

Account	Stage
Production	production
Staging	staging
Development	development
BusinessContinuity	compliance
Platform	platform

Edit infrastructure.ts to change this layout before deploying.

Figure: The generated organisation infrastructure file.

4. Connect the management account

fjall connect

The first connect after an organisation scaffold registers the AWS account as the AWS Organizations management account. It skips the region and stage pickers, asks only for an account name, opens a CloudFormation Quick Create link in your browser, then polls until the stack completes and OIDC trust validates. Full walkthrough: Connect AWS.

5. Deploy the organisation

fjall org deploy

Tier deploys are noun-verb. fjall deploy takes application names only, and fjall deploy organisation fails with a teaching error before it authenticates. Fjall resolves the AWS account itself. Profiles are derived in memory from your organisation config, so there is no manual profile step and nothing is written to ~/.aws/config. See Understanding Profiles.

The cascade

By default fjall org deploy deploys the organisation root stack, then cascades through platform, domains, then accounts. Pass --no-cascade to deploy the root alone. The run shows these steps:

Step	When it appears
Authenticating with AWS	Always
Configuring organisation	Always
Prepare environment	Always
Deploying organisation	Only when the root template changed
Deploying platform	Only with a platform account
Deploying accounts	Only with member accounts

Domains deploy between platform and accounts. That phase has no step of its own. “Configuring organisation” opens a live sub-task panel covering organisation creation, policy types, centralised root access, RAM sharing, IPAM delegated admin, account creation, organisational units, cost allocation tags, IAM Identity Center, delegated security services and domains. The accounts phase opens a tabbed panel with one tab per account and region, switched with the number keys (1-9, then a-z for further tabs), Tab / Shift+Tab to cycle, and 0 for the overview.

There is no diff-review or “deploy these changes?” confirmation on a tier deploy. The domains-phase CAA check is an automatic fail-closed preflight, not a prompt.

When the deploy boundary reaches each account

Two roles per account and region carry the boundary: FjallDeploy<orgId>, and the CDK execution role that Fjall’s bootstrap creates. The second can only be capped once FjallDeployBoundary<orgId> already exists in the account, so whether an account converges in one pass or two depends on what created the policy first.

Account	When the policy appears	When the execution roles are capped
One you connected with `fjall connect`	At connect, from the quick-create stack	The first deploy that bootstraps each region
One the cascade creates for you	When its account stack lands	The next deploy into that region — a second `fjall org deploy` (`--force` is enough, no template change), or the first application deploy there

Regions the cascade did not touch converge on their own schedule: the first deploy into a new region caps that region’s execution role. Nothing is retroactive and nothing is silent — each bootstrap logs whether it applied the boundary, and why not when it did not. The management account is capped from the moment you connect it, because its deploy role comes from the quick-create stack rather than from the cascade. The flip side is that the cascade never re-renders that stack, so the management account cannot heal itself: an account connected before the boundary shipped carries no policy until its connector stack is updated, which here means re-running fjall connect --force. Deploy Account has the per-account detail and the get-role commands for checking where each role stands.

Options

Option	Description
`--no-cascade`	Deploy the organisation root only, skipping platform, domains and accounts
`--skip-caa-preflight`	Pre-answer the delegated-domain CAA preflight when you have verified the CAA chain yourself
`-f, --force`	Redeploy even when no infrastructure changes are detected
`--remediate <name=verb>`	Named consent for one record-takeover row in the domains phase (repeatable)
`--allow-replace <name>`	Shorthand for `--remediate <name>=recreate` (repeatable)
`--destruction-consent-digest <digest>`	Bind consents to the ticket digest from a prior withheld run
`--skip-confirmation`	Registered for symmetry with the other tiers. This path has no confirmation prompt
`--non-interactive`	Skip the interactive UI and stream plain output

--target is registered on the leaf but refused for organisation deploys. Organisation infrastructure always deploys to the management account.

Partial failure

The cascade runs to completion, then the deploy fails as a whole.

A failed platform skips the member fan-out with “Skipping account cascade — platform deployment failed; platform is a prerequisite for member accounts.”
A withheld domain record takeover halts before members and exits 4. Cure it with --remediate <name>=<verb> or --allow-replace <name>.
Member failures are recorded per account and region, and the run reports “Organisation root deployed, but the cascade failed for N target(s):” with a per-target list.

A half-deployed estate always exits non-zero.

Success output

An interactive run finishes on a summary screen: the title Deploying organisation: organisation, a tick-list of the steps above, and a Next Steps block. After a full cascade:

Next Steps:
  Review applications   fjall/<app>/infrastructure.ts
  Deploy applications   fjall deploy
  Learn more            https://docs.fjall.io/deployment

After --no-cascade it points at the platform tier instead:

Next Steps:
  Review infrastructure   fjall/platform/infrastructure.ts
  Deploy platform         fjall platform deploy
  Learn more              https://docs.fjall.io/deployment/deploy-platform

A non-interactive run prints a summary block:

── Summary ──────────────────────────────────────
  Result:   ✓ organisation deployed successfully
  Duration: 12m 4s
  Accounts: 4/4 deployed
  Platform: 1/1 deployed
  Domains:  1 deployed
──────────────────────────────────────────────────

When there is nothing to do, the run reports “No changes to deploy. Your infrastructure is up to date.”

Create without prompts

Pass options to skip the interactive flow:

fjall create organisation \
  -n acme \
  --email engineering@example.com \
  --primary-region us-east-2 \
  --secondary-regions us-west-2,eu-west-1 \
  --non-interactive

Option	Description
`--email <email>`	Required. Admin email address for the organisation
`-n, --name <name>`	Organisation name. Resolves from your Fjall identity when omitted
`--primary-region <region>`	Primary AWS region, for example `us-east-2`
`--secondary-regions <regions>`	Comma-separated secondary regions, maximum 10
`--disaster-recovery-region <region>`	Disaster recovery region for cross-region replication
`--security <tier>`	Governance profile: `foundation`, `compliance`, or `hardened`
`--force`	Overwrite scaffold files that already exist with different content
`--non-interactive`	Skip interactive prompts

The interactive governance labels map to --security values: Monitored is foundation, Regulated is compliance, Enforced is hardened. Essentials applies no preset.

fjall create organisation has no --account-name option and no --container option. --container belongs to fjall create application, and passing it here is rejected. The root account name follows the organisation name unless you override it in infrastructure.ts.

Next Steps

Connect AWS

Establish OIDC trust between Fjall and your AWS management account

Deploy the Platform

Deploy the platform tier on its own after a --no-cascade organisation deploy

Understanding Profiles

See how Fjall derives AWS profiles and deployment targets from your organisation config

Deploy an Application

Deploy your first application into the organisation

Install & Setup

Application Deploy

Deployment Errors

Organisation Setup

Organisation Deploy

Deploy Organisation

Prerequisites

1. Create the organisation

2. Answer the prompts

Governance profiles

What happens after you confirm

3. Review the infrastructure file

4. Connect the management account

5. Deploy the organisation

The cascade

When the deploy boundary reaches each account

Options

Partial failure

Success output

Create without prompts

Next Steps

Connect AWS

Deploy the Platform

Understanding Profiles

Deploy an Application

​Prerequisites

​1. Create the organisation

​2. Answer the prompts

​Governance profiles

​What happens after you confirm

​3. Review the infrastructure file

​4. Connect the management account

​5. Deploy the organisation

​The cascade

​When the deploy boundary reaches each account

​Options

​Partial failure

​Success output

​Create without prompts

​Next Steps

Connect AWS

Deploy the Platform

Understanding Profiles

Deploy an Application

Prerequisites

1. Create the organisation

2. Answer the prompts

Governance profiles

What happens after you confirm

3. Review the infrastructure file

4. Connect the management account

5. Deploy the organisation

The cascade

When the deploy boundary reaches each account

Options

Partial failure

Success output

Create without prompts

Next Steps