Fjall Docs — deploy AWS infrastructure into your own account

Fjall provisions and deploys AWS infrastructure from TypeScript you own. This page takes you from an empty directory to a running application.

Prerequisites

AWS account: create one if you do not have one
Node.js 22+: download (the fjall package declares engines.node >=22.0.0)
npm: included with Node.js
Fjall account: sign up

Quick Start

Fjall’s single-account setup is three commands in a fixed order: create, connect, deploy. Run every command from the same project directory.

1. Install the CLI

npm install -g fjall

Verify the installation:

fjall --version

2. Log in to Fjall

fjall login

The CLI checks for saved credentials, then starts the browser device-code flow. When credentials already exist it asks “You already have credentials saved. Overwrite them?” and defaults to No. While it waits for the browser, press E to type an API key instead. For CI and other non-interactive shells, pass the key directly:

fjall login --api-key fj_your_api_key

Credentials land in ~/.fjall/auth.json, or in $FJALL_CONFIG_DIR/auth.json when you relocate the state root.

3. Create the account project

mkdir acme && cd acme
fjall create account

This scaffolds fjall/account/infrastructure.ts, the declaration of everything Fjall manages in one AWS account, and records your primary region against the organisation. It writes files only, so no AWS resource exists yet.

4. Connect your AWS account

fjall connect

fjall connect installs Fjall’s OIDC trust in the AWS account. Interactively it asks up to three questions first:

Prompt	Skipped when
Select your primary AWS region	The organisation already has a primary region (step 3 writes it), or you pass `--region`
Select the environment for this account	You pass `--environment`. The accepted values are lowercase: `production`, `staging`, `development`, `platform`, `compliance`
What should this AWS account be called?	You pass `--name`. Leave the answer blank to inherit the AWS account’s own name

The CLI then runs four steps: Checking existing connections, Opening AWS CloudFormation, Waiting for CloudFormation, Validating OIDC connection. It opens your browser on a CloudFormation Quick Create page and prints the URL as a fallback. Review the stack, choose Create stack, and the CLI detects the connection on its own. Pass --no-wait to return at the browser hand-off instead of blocking, then confirm later:

fjall connect status --external-id <id> --wait

5. Deploy account infrastructure

fjall account deploy

This provisions the account tier: deploy roles, logging, monitoring, compliance, and the container registry. Run it once per AWS account. Tier deploys use the noun-verb form. fjall deploy takes application names only, so fjall deploy account fails with an error naming the correct spelling.

6. Create your first application

fjall create app --name api

The wizard opens on “Choose your starting point?”, then asks for the application name, the database, and the services, and shows a review before writing anything. --name pre-fills the name. --type <tier> pre-selects the tier in the picker rather than skipping the prompt. Add --non-interactive to run without prompts. After the review confirm, the CLI settles the deployment target. It prompts when your organisation derives more than one target, auto-selects when exactly one exists, and skips the step when none do. Two files record the outcome:

File	Committed	Holds
`fjall/fjall-config.json`	Yes	The project’s `organisation` binding
`.fjall/local.json`	No (gitignored)	`activeTarget`, this checkout’s deployment target

The binding is what makes the project born bound. A command run here later with another organisation’s credential is refused rather than landing in the wrong account. fjall create app --target <name> chooses the target non-interactively.

7. Deploy

fjall deploy api

The first deployment takes 10 to 15 minutes while AWS provisions every resource. Later deployments are faster. On completion the CLI lists next steps, including your application URL:

Visit your url    http://api-1234567890.us-east-2.elb.amazonaws.com

Tier-based applications run on ECS behind an Application Load Balancer, so the URL is an ALB DNS name. Put a custom domain in front of it with fjall domain.

For multi-account setups, run fjall create organisation in place of step 3, then continue with fjall connect (step 4) and fjall org deploy in place of fjall account deploy. The order stays create, connect, deploy. See the Organisation Guide.

Choose a tier

Each tier configures compute, networking, and database resources for one use case. The picker shows all six options at once, in the order below. Standard is the recommended starting point.

Tier	Picker description	Resources	Monthly cost
Standard	Production-ready · Multi-AZ, Fargate ECS, RDS	3 AZ, 1 NAT, Fargate, RDS Instance (t4g.large)	~$340
Lightweight	Streamlined · Single-AZ, Instance-backed ECS, RDS	2 AZ, 1 NAT, Fargate Spot, RDS Instance (t4g.small)	~$35
Resilient	High-availability · Multi-AZ, Encrypted, Fargate ECS, Aurora	3 AZ, 3 NAT, Aurora with readers, KMS encryption, RDS Proxy, 30-day backup	$200-600+
Enterprise	Maximum capability · All features enabled, Aurora	3 AZ, 3 NAT, Aurora with readers, KMS, VPC endpoints, maximum compliance	$300-800+
Tinkerer	Free experimental · Single-AZ, Free tier ECS, RDS	2 AZ, no NAT, ECS on EC2 (t4g.micro), RDS Instance (t4g.micro), free-tier eligible	$0 in free tier
Custom	Blank canvas · Build your way	Full control over all configuration	Varies

Resilient requires a Pro plan and Enterprise requires an Enterprise plan. Picking a gated tier without the entitlement shows the plan message and offers to select a different tier. Create an application on a specific tier:

fjall create app --name api --type tinkerer

On a terminal this still opens the wizard with Tinkerer pre-selected. Add --non-interactive to skip the prompts.

Patterns

Patterns scaffold a framework-specific application through a separate flow, reached from interactive fjall create by choosing Patterns. The picker lists the two deployable patterns:

Pattern	Value	Description
Payload CMS	`payload`	Headless CMS with Next.js, serverless
Static site	`staticsite`	Pre-built folder on S3 and CloudFront, ~$0/mo

Payload then offers four tiers: Standard, Lightweight, Resilient, and Custom. Static site skips tiers and asks for its source directory, build command, and output directory instead. --pattern has a long form only, with no -p short flag, and it only takes effect in non-interactive mode. The wizard drops pattern flags and lands in the six-tier picker, so pair --pattern with --non-interactive:

fjall create app --non-interactive --name web --pattern payload

staticsite requires all three of its inputs:

fjall create app --non-interactive --name docs --pattern staticsite \
  --source site \
  --build-command "npm run build" \
  --output-dir out

The nextjs pattern is not deployable, so the picker does not offer it and --pattern nextjs is refused at create time. Use --pattern payload for a Next.js application, or --pattern staticsite for a pre-built static export.

What happens during deployment

When you run fjall deploy api, the CLI:

Authenticates with AWS using credentials minted for the resolved target
Synthesises CloudFormation templates from your infrastructure code
Bootstraps the CDK toolkit stack (first run only)
Builds your application and pushes Docker images to ECR
Presents a plan and waits for approval
Deploys the network, storage, database, and compute stacks
Reports the application URL and next steps

The approval gate is on by default in a terminal. The CLI renders the plan one row per resource change (+ create, ~ update, ± replace, - delete), then asks “Approve this plan and deploy?” with No as the default. Rejecting the plan changes nothing. Pass --skip-confirmation or --auto-approve in CI. Destructive rows add a per-resource typed-name consent step that no flag bypasses. See Destructive Changes. When nothing changed since the last deploy, the run ends early and reports the application as already up to date.

Troubleshooting

Command not found

fjall: command not found

Solution: put the npm global bin directory on your PATH:

export PATH="$PATH:$(npm config get prefix)/bin"

AWS credentials error

Error: Unable to resolve AWS account

Solution: check the connection:

fjall connect status

fjall connect verifies an existing connection or starts a new one. Expired credentials trigger a re-authentication prompt on your next deployment command.

Deployment timeout

First deployments take 10 to 15 minutes. If a deploy times out, check the CloudFormation console for stack status, then retry:

fjall deploy api

Need help?

Read the CLI Reference for command detail
Join the Discord community
Email support@fjall.io

Next Steps

Add Resources

Extend your application with databases, storage, and messaging

Deploy an Application

Learn the full deploy surface, flags, and safety gates

CLI Reference

Browse every Fjall command

Targets and Profiles

Understand deployment targets, accounts, and regions

Install & Setup

Application Deploy

Deployment Errors

Organisation Setup

Organisation Deploy

Getting Started

Prerequisites

Quick Start

1. Install the CLI

2. Log in to Fjall

3. Create the account project

4. Connect your AWS account

5. Deploy account infrastructure

6. Create your first application

7. Deploy

Choose a tier

Patterns

What happens during deployment

Troubleshooting

Command not found

AWS credentials error

Deployment timeout

Need help?

Next Steps

Add Resources

Deploy an Application

CLI Reference

Targets and Profiles

​Prerequisites

​Quick Start

​1. Install the CLI

​2. Log in to Fjall

​3. Create the account project

​4. Connect your AWS account

​5. Deploy account infrastructure

​6. Create your first application

​7. Deploy

​Choose a tier

​Patterns

​What happens during deployment

​Troubleshooting

​Command not found

​AWS credentials error

​Deployment timeout

​Need help?

​Next Steps

Add Resources

Deploy an Application

CLI Reference

Targets and Profiles

Prerequisites

Quick Start

1. Install the CLI

2. Log in to Fjall

3. Create the account project

4. Connect your AWS account

5. Deploy account infrastructure

6. Create your first application

7. Deploy

Choose a tier

Patterns

What happens during deployment

Troubleshooting

Command not found

AWS credentials error

Deployment timeout

Need help?

Next Steps