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 never calls AWS: it deploys no CloudFormation stack and connects no AWS account. It does call the Fjall API, so it needs a login. Before it scaffolds anything, it confirms that your plan includes organisations and the governance profile you picked (Essentials needs no check), then records the regions you chose in the organisation config. 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.
  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).

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. From fjall 37 the note lists only the findings the workload you are creating can produce. An application at the standard tier creates an ECS cluster and no topic or bucket, so its note is the Container Insights line alone; the enterprise tier, which also writes VPC flow logs to a bucket, turns every default on and prints nothing. A custom application scaffolds nothing but its network, so its review step prints no note until resources are added with fjall add. 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 the same note from fjall 37, filtered to what the pattern builds. A Payload site at the standard or lightweight tier lists S3_VERSIONING_DISABLED for its media bucket, since neither tier versions buckets, and at the resilient tier lists nothing; a static site lists the same bucket line. Neither lists a cluster or topic finding, because a pattern deploys Lambda and CloudFront rather than an ECS service. Through fjall 36 the pattern flow printed no note.

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 repo root, the directory that holds the application’s `fjall/` marker
`--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 beside infrastructure.ts, in fjall/<app>/.

Where the output goes

From fjall 38 fjall create app and fjall create org write the scaffolded directory path to stdout. The path is the result, so a shell captures it with nothing to strip:

cd "$(fjall create app --name api --type standard --non-interactive)"

Everything else goes to stderr: the step lines, the summary that repeats the path under Location:, and warnings. --dry-run is the exception. The preview it prints is that run’s result, and nothing exists at the path to move into, so no path is written. fjall create account and fjall create domain print no path. Neither does fjall apps create, which otherwise runs the same flow. At a TTY the interactive wizard runs instead and writes no path line. The split above describes the non-interactive lane, which is the one a shell capture takes.

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.

Application limit reached

Your plan caps how many applications you can register. At the cap the API refuses the registration and fjall create carries on: the scaffold files are written, the application is not registered, and the run prints the API’s refusal. The command still exits 0, so a CI step at the cap passes with an unregistered application.

[warn] Failed to register with API: Application limit reached (2/1 on Free plan). Upgrade your plan to deploy more applications, or free a slot with `fjall apps deregister <app> --confirm <app>`. Destroying an application does not free its slot, because the registration is what the limit counts.

The refusal arrives as one line. A link to the Change plan page is appended to it when the server can build one. The line is printed twice on stderr, once as [warn] where the refusal happens and again as Warning: at the end of the run. Two cures:

Cure	How
Raise the cap	Change your plan from the Fjall dashboard
Free a slot	`fjall apps deregister <app> --confirm <app>`, one slot per run

fjall destroy does not free a slot. It removes the AWS infrastructure and leaves the registration behind, and de-registering is the only verb that frees one. See fjall apps. The files on disk are unaffected. Once a slot is free, register the tree you already have with fjall create app --name api --register-only instead of scaffolding again.

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 create never calls AWS, so it needs no AWS credentials and there is no AWS profile to configure for it. The commands that do call AWS get their credentials as AWS Profiles and Targets describes.

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

​Where the output goes

​After creating

​Troubleshooting

​Application already exists

​Application limit reached

​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

Where the output goes

After creating

Troubleshooting

Application already exists

Application limit reached

Scaffold files already exist with different content

Authentication fails

Region not available

Next Steps