Fjall Docs — deploy AWS infrastructure into your own account

Interactive command: run it bare and Fjall walks you through every choice. Every prompt has a flag equivalent for CI.

Overview

fjall create scaffolds infrastructure as CDK TypeScript on disk. It writes files and registers the result with Fjall. It does not call AWS and it does not deploy anything. Four targets:

Target	Scaffolds	Deploy with
`organisation`	`fjall/organisation/`, `fjall/platform/`, `fjall/account/`	`fjall org deploy`
`account`	`fjall/account/`	`fjall account deploy`
`application`	`fjall/<app>/` (alias `app`)	`fjall deploy <app>`
`domain`	`fjall/domains/<domain>/` plus an entry in `fjall-config.json`	`fjall domain deploy`

Usage

fjall create [target] [options]

Run it with no target and Fjall asks What would you like to build? with four choices: Application, Organisation, Domain, Patterns.

Where create fits

Creating is step one of three. Steps two and three touch AWS.

Single account
Organisation

fjall create account     # scaffold fjall/account/infrastructure.ts
fjall connect            # install Fjall's OIDC trust in the AWS account
fjall account deploy     # provision deploy roles, logging, guardrails

fjall create organisation  # scaffold organisation, platform and account tiers
fjall connect              # connect the AWS Organizations management account
fjall org deploy           # create member accounts, provision all tiers

Start with an account for standalone use. An organisation is an upgrade path, not a prerequisite.

Targets

Organisation

fjall create organisation
# alias
fjall create org

Scaffolds three components, each with its own infrastructure.ts, package.json and cdk.json:

fjall/organisation/ declares member accounts, IAM Identity Center and guardrails
fjall/platform/ declares shared services
fjall/account/ declares the per-account baseline

Organisation management requires a Pro plan. On a Free plan the flow stops with Organisation management requires a Pro plan. and a link to billing. The governance profile you pick, --security <tier>, is written into fjall/account/infrastructure.ts as securityTier. It does two things: it decides which security services the account scaffold enables, and it selects the content of the deploy-role permissions boundary. Those are independent. Choosing Essentials, which writes no securityTier at all, still leaves the boundary on at hardened — the tier changes which ceiling the deploy role has, never whether it has one.

fjall create organisation writes files only. It does not open a browser, deploy a CloudFormation stack, or connect AWS. Run fjall connect next.

Account

fjall create account

Scaffolds fjall/account/infrastructure.ts, the declaration of everything Fjall manages in one AWS account: deploy roles, monitoring, CloudTrail audit logging, ECR, and the OIDC connector for CI/CD. fjall account deploy provisions it. fjall create account has no --security flag, so a standalone account scaffold carries no governance profile and enables no security services. Its deploy role is still capped: the boundary defaults to hardened whenever no tier is set. To change the tier or opt out, edit the Account props directly — see Deploy Account.

Application

fjall create application
# alias
fjall create app

Scaffolds fjall/<app>/ with the CDK code for the tier you pick. See Application tiers.

Domain

fjall create domain --name example.com

Scaffolds fjall/domains/example.com/infrastructure.ts with a typed Domain construct and registers the domain in fjall-config.json so the organisation cascade picks it up. A name nested under an already-registered parent scaffolds the delegated-child variant instead of an apex. The fjall domain create <domain> spelling does the same work and takes the name positionally.

Application tiers

Six starting points. -t/--type selects one non-interactively and pre-highlights it in the picker.

Tier	Network	Compute	Database	Best for
`tinkerer`	2 AZs, no NAT	ECS on EC2 (t4g.micro, Arm)	RDS Instance t4g.micro	Learning, free tier
`lightweight`	2 AZs, 1 NAT	Fargate Spot (256 CPU, 512 MiB)	RDS Instance t4g.small	Small applications, side projects
`standard`	3 AZs, 1 NAT	Fargate (512 CPU, 1024 MiB)	RDS Instance t4g.large	Most production workloads
`resilient`	3 AZs, 3 NAT	Fargate (1024 CPU, 2048 MiB)	Aurora, 2 readers, CMK, RDS Proxy, 30-day backups	High availability
`enterprise`	3 AZs, 3 NAT, VPC endpoints, S3 flow logs (365-day)	Fargate (2048 CPU, 4096 MiB)	Aurora, 2 readers, CMK, RDS Proxy, 35-day backups	Mission-critical
`custom`	You pick a preset	Added after creation	Added after creation	Specific requirements

resilient requires a Pro plan and enterprise requires an Enterprise plan. Picking a gated tier interactively shows the plan message and offers Select a different tier?.

Interactive flows

Create an organisation

fjall create organisation

? Name your organisation? exampleorg
? Email for account setup? aws@example.com
? Select your primary AWS region? us-east-1
? Select secondary AWS regions (optional)? eu-west-1
? Enable disaster recovery for production deployments? Yes
? Select disaster recovery region? eu-west-2
? Governance profile
  > Essentials  Best for most teams · AWS-native protections, no extra cost
    Monitored   Adds threat detection · GuardDuty, Security Hub
    Regulated   Compliance-ready · Audit trails, vulnerability scanning
    Enforced    Maximum control · SCPs, access policies, config rules
? Create organisation with these settings? Yes

✓ Generating organisation structure
✓ Installing dependencies

Create an application

fjall create app

? Choose your starting point?
  > Standard    Production-ready · Multi-AZ, Fargate ECS, RDS
    Lightweight Streamlined · Single-AZ, Instance-backed ECS, RDS
    Resilient   High-availability · Multi-AZ, Encrypted, Fargate ECS, Aurora
    Enterprise  Maximum capability · All features enabled, Aurora
    Tinkerer    Free experimental · Single-AZ, Free tier ECS, RDS
    Custom      Blank canvas · Build your way

? Name your application? api
? Include database? Yes
? Restore database from an existing RDS snapshot? No
? How many services? 1
? Name service 1 of 1? ApiService
? Provide Dockerfile for "ApiService"? Yes
? Dockerfile path for "ApiService"? ./Dockerfile
? Container port for "ApiService"? 3000
? Does "ApiService" need database connection? Yes
? Create application with these settings? Yes

Two prompts appear conditionally. Use suggested container '<dir>'? appears when Fjall infers a monorepo container and --container was not passed. Select a deployment target: appears when your organisation config yields more than one target. A single target selects itself. Picking Custom skips the database and service questions and asks Network configuration? instead, with five presets: Standard, Lightweight, Resilient, Tinkerer, No network.

The interactive wizard ignores --pattern, --tier and --pattern-tier. fjall create app --pattern payload in a terminal lands in the six-tier picker with the flag dropped. Pass --non-interactive for the pattern path, or reach patterns through bare fjall create → Patterns.

What the review step says about posture

From fjall 36, the review step of the application flow — the tier picker above — prints a note under the settings list before the final confirmation:

Posture findings this tier produces
  Choosing Standard keeps these defaults, and the first posture scan lists them. On a development or staging account a posture scan lists each as expected at this stage; on any other account it is open. Nothing is accepted on your behalf.
  SNS_TOPIC_NOT_ENCRYPTED (backup.tier on the app): the topic is unencrypted because the app's backup tier does not encrypt topics (the enterprise tier's shared customer-managed key costs about $1 to $3 a month per stack).
  ECS_CONTAINER_INSIGHTS_DISABLED (backup.tier on the app): Container Insights is off because the app's backup tier does not enable it (it bills per metric per cluster).
  S3_VERSIONING_DISABLED (backup.tier on the app): bucket versioning is off because the app's backup tier does not version buckets (every overwrite would keep a billed copy).

Each line is a finding the tier’s backup defaults produce, named by the rule the posture scan will list it under, with the setting that causes it and the expectation in the scan’s own words. The lead says where the scan lists them, which depends on your organisation’s posture setting: on a lenient organisation a development or staging account files them as expected at this stage and any other account as open; a strict organisation files them as open everywhere. Tiers that turn a default on drop its line, so resilient and enterprise print fewer lines or none, and custom reads the standard column. The note informs the choice and gates nothing: there is nothing to accept, and the settings it describes are the ones the tier table already declares. The posture setting is read live when the review step prints, never from a cached copy. If the wizard runs while logged out, the note says so instead of printing lines, because where a finding is listed depends on the organisation the application joins. If the control plane predates the posture field, or cannot be reached, the lead says the setting could not be read rather than promising a lane. The pattern flow (bare fjall create → Patterns) prints no note: a pattern deploys Lambda and CloudFront rather than an ECS service, so the application tiers’ findings do not describe it.

Non-interactive examples

# Organisation
fjall create organisation \
  --name exampleorg \
  --email aws@example.com \
  --primary-region us-east-1 \
  --secondary-regions eu-west-1,ap-southeast-2 \
  --non-interactive

# Standard-tier application
fjall create app --name api --type standard --non-interactive

# Payload CMS pattern
fjall create app --name cms --pattern payload --non-interactive

# Static site from a pre-built folder
fjall create app \
  --name web \
  --pattern staticsite \
  --source ../.. \
  --build-command "npm run build" \
  --output-dir out \
  --non-interactive

# Restore the database from an RDS snapshot
fjall create app \
  --name dashboard \
  --type standard \
  --database \
  --snapshot-identifier rds:my-production-snapshot \
  --snapshot-username postgres \
  --non-interactive

# Apex domain plus one delegated child per workload account
fjall create domain --name example.com --per-account --non-interactive

The application flow is also spelled fjall apps create, which takes the same flags. It is not agent-only: the difference is that apps create never routes to the interactive wizard, so it is the flag-driven path in both human and agent mode. In agent mode it returns TOON output.

Options

Every target

Option	Description
`--non-interactive`	Skip all prompts and read every value from flags
`-v, --verbose`	Print detailed progress
`--agent`	Agent-mode output (TOON)

Organisation

Option	Description
`--email <email>`	Required. Admin email for the organisation. Use a monitored inbox, because AWS root password recovery delivers reset links here
`-n, --name <name>`	Organisation name. Optional: resolves from your Fjall API identity when omitted
`--primary-region <region>`	Primary AWS region
`--secondary-regions <regions>`	Comma-separated additional regions
`--disaster-recovery-region <region>`	Region for cross-region replication
`--security <tier>`	Governance profile: `foundation` (Monitored), `compliance` (Regulated), `hardened` (Enforced). Omit for Essentials. Also selects the deploy-role permissions boundary, which stays at `hardened` when you omit it
`--force`	Overwrite scaffold files that already exist with different content. Identical files are skipped, so re-runs stay idempotent

Account

Option	Description
`--primary-region <region>`	AWS region for account infrastructure
`--force`	Overwrite scaffold files that already exist with different content

Application

Option	Description
`-n, --name <name>`	Application name. Lowercase letters, numbers and hyphens, 2 to 50 characters, starting with a letter
`-t, --type <type>`	Tier: `tinkerer`, `lightweight`, `standard`, `resilient`, `enterprise`, `custom`
`--pattern <pattern>`	Pattern: `payload` or `staticsite`
`--tier <tier>`	Pattern infrastructure tier: `lightweight`, `standard`, `resilient`, `custom`
`--pattern-tier <tier>`	Alias for `--tier`
`--pattern-domain <domain>`	Custom domain for the pattern
`--source <dir>`	Static-site source directory. The build runs here and assets upload from here
`--build-command <cmd>`	Static-site build command
`--output-dir <dir>`	Static-site build output directory, relative to `--source`
`--routing <mode>`	Static-site routing: `multipage` (`/about` serves `/about.html`), `directory` (`/about/index.html`), `spa` (unknown paths fall back to `/index.html`)
`--forms-to <email>`	Static-site contact-form recipient. Requires `--pattern-domain`, the verified SES sender identity
`--cors-origin <origin>`	Static-site forms CORS allow-origin. Defaults to the site domain
`--database`	Include a database
`--snapshot-identifier <id>`	RDS snapshot to restore the database from
`--snapshot-username <user>`	Master username from the snapshot. Immutable, and it must match the original
`--dockerfile [path]`	Path to a custom Dockerfile
`--container-port <port>`	Container port
`--services <json>`	Service config as a JSON array
`--owner <owner>`	Owner identifier
`--network <preset>`	Network preset: `none`, `tinkerer`, `lightweight`, `standard`, `resilient`, `enterprise`
`--template <template>`	Starter template
`--into <path>`	Scaffold into an existing repo instead of `./fjall/<name>`
`--container <dir>`	Monorepo container directory between the repo root and the application’s `fjall/` marker, such as `apps` or `services`. Blank or whitespace-only values are rejected
`--target <name>`	Deployment target for this command. Persists as the active target in `.fjall/local.json`
`--dry-run`	Preview the scaffold without writing files, calling the API, or installing dependencies
`--offline`	Scaffold with no network at all: no authentication, no Fjall API call, no npm install. Files are written but the application is not registered, and only free tiers are available
`--register-only`	Register an existing application tree with Fjall without scaffolding. Run it from the application’s package root
`--file-override <relpath=base64>`	Override a planned scaffold file with base64-encoded content. Repeatable, and the path must match a file the generator was about to write
`--git`	Initialise a git repository
`--github`	Create a GitHub repository
`--github-org <org>`	GitHub organisation for the repository
`--repo-visibility <visibility>`	GitHub repo visibility: `public` or `private`

--offline conflicts with --github. --register-only conflicts with --dry-run and --offline.

Domain

Option	Description
`-n, --name <name>`	Domain name, such as `example.com`
`--hosted-zone-id <id>`	Adopt an existing Route53 hosted zone. Omit to create a new zone
`--parent <zone>`	Parent zone for a delegated scaffold. `none` forces an apex. The default derives the longest-suffix registered parent from `fjall-config.json`
`--account <account>`	Home AWS account pin: a 12-digit account id or a provider-account name. A delegated child inherits its parent entry’s pin
`--region <region>`	Home region pin. Inherited like `--account`, otherwise recorded by the first deploy
`--per-account`	Fan out one delegated child per workload account (`<accountname>.<domain>`) after the apex scaffold, each pinned to its account. Idempotent, and solo-account organisations fan out nothing

Patterns

Two patterns are deployable today:

Pattern	What it is	Required flags
`payload`	Payload CMS on Next.js and OpenNext, serverless	none beyond `--pattern payload`
`staticsite`	Pre-built folder on S3 and CloudFront	`--source`, `--build-command`, `--output-dir`

The nextjs pattern is not deployable. It is hidden from the picker, and --pattern nextjs is refused at create time with a pointer to --pattern payload. For a Next.js application use payload, or staticsite for a pre-built static site.

What gets created

fjall/
├── organisation/
│   ├── infrastructure.ts
│   ├── package.json
│   └── cdk.json
├── platform/
│   ├── infrastructure.ts
│   ├── package.json
│   └── cdk.json
├── account/
│   ├── infrastructure.ts
│   ├── package.json
│   └── cdk.json
└── fjall-config.json

fjall/
├── account/
│   ├── infrastructure.ts
│   ├── package.json
│   └── cdk.json
└── fjall-config.json

fjall/
└── api/
    ├── infrastructure.ts
    ├── package.json
    ├── tsconfig.json
    ├── cdk.json
    └── cdk.context.json

fjall/
├── domains/
│   └── example.com/
│       └── infrastructure.ts
└── fjall-config.json

An application that builds containers also gets a Dockerfile. The Payload pattern adds open-next.config.ts at the project root.

After creating

Review the generated code

cat fjall/api/infrastructure.ts

Add resources

Resource names are PascalCase by convention and take letters and digits only.

fjall add database --app api --name AppDb --type Aurora --databaseName appdb

Deploy

fjall deploy api

For tiers, use the noun-verb spelling: fjall org deploy, fjall platform deploy, fjall account deploy.

Troubleshooting

Application already exists

Pick a different name, or delete the existing scaffold with rm -rf fjall/<app> and re-run.

Scaffold files already exist with different content

fjall create organisation and fjall create account skip identical files and refuse to overwrite changed ones. Pass --force to overwrite. This is the flag to reach for when upgrading a standalone fjall/account scaffold to an organisation.

Authentication fails

Run fjall login to refresh your Fjall credentials, then re-run. Fjall derives every AWS credential from that one session, so there is no AWS profile to configure.

Region not available

Not every AWS service exists in every region. Check the region’s service list, prefer us-east-1 for the widest availability, and add secondary regions for resilience.

fjall create generates CDK TypeScript. Edit the generated infrastructure.ts files directly to go beyond what the flags cover.

Next Steps

Connect AWS

Install Fjall’s OIDC trust in the AWS account you just scaffolded.

Deploy

Ship an application to AWS, or run a tier deploy.

Add resources

Add a database, storage, or compute to an application’s infrastructure.ts.

Manage domains

Deploy, verify, and delegate the domains you create.

​Overview

​Usage

​Where create fits

​Targets

​Organisation

​Account

​Application

​Domain

​Application tiers

​Interactive flows

​Create an organisation

​Create an application

​What the review step says about posture

​Non-interactive examples

​Options

​Every target

​Organisation

​Account

​Application

​Domain

​Patterns

​What gets created

​After creating

​Troubleshooting

​Application already exists

​Scaffold files already exist with different content

​Authentication fails

​Region not available

​Next Steps

Connect AWS

Deploy

Add resources

Manage domains

Overview

Usage

Where create fits

Targets

Organisation

Account

Application

Domain

Application tiers

Interactive flows

Create an organisation

Create an application

What the review step says about posture

Non-interactive examples

Options

Every target

Organisation

Account

Application

Domain

Patterns

What gets created

After creating

Troubleshooting

Application already exists

Scaffold files already exist with different content

Authentication fails

Region not available

Next Steps