Fjall Docs — Deploy Production-Ready AWS Infrastructure in Minutes

Prerequisites

Complete one of:

Connect AWS Account (account-mode users)
Deploy Organisation (organisation-mode users)

Overview

Authentication and the choice of which AWS account a deploy lands in are two separate concerns in Fjall. Neither is driven by a manual profile step or by a stage mapping in fjall-config.json.

Concept	What it does	Where it comes from
Authentication profile	Authenticates the CLI against an AWS account (OIDC or SSO)	Derived automatically from your organisation config
Deployment target	Selects the account and region a deploy lands in (organisation mode)	Derived from accounts, selected with `fjall target set`

Profiles are never authored by hand. There is no fjall profile command. Fjall fetches your organisation config from the API and derives every profile from it.

Authentication modes

Fjall supports two authentication modes, both derived from the same organisation config.

Account mode. You connected a single AWS account with fjall connect. The account carries its own OIDC role, so Fjall assumes that role directly. No ~/.aws/config entries are needed.
Organisation mode. You deployed a multi-account organisation with fjall create organisation. Non-root member accounts authenticate via AWS SSO through the root account’s IAM Identity Centre. Fjall derives one SSO profile per account and region.

OIDC is preferred whenever an account carries its own oidcRoleArn. SSO applies to organisation members that lack their own OIDC role. The rest of this page covers organisation-mode profile derivation and target selection. In account mode, authentication is automatic via OIDC and you do not manage profiles or targets.

How profiles are derived

Fjall derives profiles from your organisation config with deriveProfiles(orgConfig). The org config (accounts, regions, OIDC roles, SSO sessions) is fetched from the API, not read from any local file. Two rules apply:

Account	Profile name	Auth
Root (Organizations management account)	`<rootname>`	OIDC, single profile
Non-root with its own `oidcRoleArn`	`<account>-<regionabbrev>`	OIDC, per region
Non-root organisation member	`<rootname>-<account>-<regionabbrev>`	SSO, per region

The region abbreviation collapses an AWS region to a short token: us-east-1 becomes use1, us-east-2 becomes use2, eu-west-1 becomes euw1. SSO profiles use the sso-<rootname> session from your organisation config and the AdministratorAccess role.

Inspecting profiles in ~/.aws/config

Organisation-mode SSO profiles are written to your ~/.aws/config file. Inspect them directly:

aws configure list-profiles

After deploying your organisation, the file contains entries like this (for an organisation named exampleorg):

[profile exampleorg-production-use2]
region = us-east-2
sso_account_id = 111111111111
sso_role_name = AdministratorAccess
sso_session = sso-exampleorg

[profile exampleorg-staging-use2]
region = us-east-2
sso_account_id = 222222222222
sso_role_name = AdministratorAccess
sso_session = sso-exampleorg

[sso-session sso-exampleorg]
sso_region = us-east-2
sso_start_url = https://d-**********.awsapps.com/start

If your SSO session has expired, Fjall prompts you to authenticate through your browser at deploy time:

SSO token expired or not found. Initiating SSO login...
Opening browser for SSO authentication...
If the browser doesn't open automatically, visit: https://d-**********.awsapps.com/start/#/device?user_code=***-***

SSO login prompt.

Selecting a deployment target

In organisation mode, the active deployment target decides which account and region a deploy lands in. A target is an account and region pair with a canonical name, <accountname>-<regionabbrev>, for example production-us-use1. Root accounts are excluded from the target list. Manage targets with the fjall target command:

# List all derived targets (the active one is marked with ▸)
fjall target list

# Show the active target's account and region
fjall target get

# Set the active deployment target
fjall target set production-us-use1

fjall target set validates the name against the derived targets and persists it as activeTarget in your fjall-config.json. At deploy time, Fjall resolves the account in this order:

A per-deploy --target <name> flag wins, if present.
Otherwise the activeTarget from local config is used. If exactly one target exists, Fjall selects it silently. If several exist and none is active, Fjall errors and asks you to run fjall target set.

The environment flag is not a target selector

fjall deploy accepts an optional -e, --environment <env> flag, but it does NOT select an account or region.

fjall deploy api --environment production

This value is a free-form CI/CD label. It flows through to the CDK synthesis as a context value (-c environment=<env>). It plays no part in profile or target resolution. To choose the deploy account, use fjall target set or the --target flag.

What fjall-config.json contains

fjall-config.json is governed by a strict schema and holds exactly two optional fields:

{
  "activeTarget": "production-us-use1",
  "domains": [{ "name": "example.com", "type": "apex" }]
}

There is no deploy mapping, no environments block, and no stage field. Account, region, OIDC, and SSO data lives in your organisation config, which Fjall fetches from the API and injects into the deploy. It is never stored in fjall-config.json.

Next Steps

Deploy Platform

Deploy your platform account in organisation mode.

Deploy Application

Deploy an application to your selected target.

Deploy Organisation

Set up a multi-account organisation.

Connect AWS Account

Connect a single account in account mode.

Install & Setup

Application Deploy

Organisation Setup

Organisation Deploy

AWS Profiles and Targets

Overview

Authentication modes

How profiles are derived

Inspecting profiles in ~/.aws/config

Selecting a deployment target

The environment flag is not a target selector

What fjall-config.json contains

Next Steps

Deploy Platform

Deploy Application

Deploy Organisation

Connect AWS Account

​Overview

​Authentication modes

​How profiles are derived

​Inspecting profiles in ~/.aws/config

​Selecting a deployment target

​The environment flag is not a target selector

​What fjall-config.json contains

​Next Steps

Deploy Platform

Deploy Application

Deploy Organisation

Connect AWS Account

Overview

Authentication modes

How profiles are derived

Inspecting profiles in ~/.aws/config

Selecting a deployment target

The environment flag is not a target selector

What fjall-config.json contains

Next Steps