Fjall Docs — deploy AWS infrastructure into your own account

Interactive command. At a TTY, fjall target set with no name walks an account picker and a region picker, and fjall target list / fjall target get render the active target’s detail card. Pass --non-interactive for plain-text output. Naming a target sets it directly either way.

Overview

A target is a deployment destination: one connected AWS account paired with one of your organisation’s configured regions. The active target decides where fjall deploy lands, which credentials fjall aws exec mints, and which account fjall secrets reads and writes in. Each takes --target <name> to address a different one for a single command. fjall secrets gained the flag in fjall 38. aws exec and secrets also accept the -t short form, which deploy does not. Targets are derived at runtime from your organisation config, which Fjall fetches from the API. Accounts, regions and role ARNs are never authored by hand in a repository file. See Understanding Profiles for how a target becomes an AWS profile.

Prerequisites

Requirement	Why
Signed in with `fjall login`	`list` and `set` read the organisation config from the Fjall API
At least one connected account	Run `fjall connect` first, or there are no targets to derive
Run `set` inside a project	The active target is written to `.fjall/local.json`, which needs a `fjall-config.json`

fjall target get reads the local active target first, so it still names the target when the organisation config cannot be fetched. With --non-interactive, that name is on stderr as Active target: <name>, followed by (Could not fetch organisation config for details) instead of the account and region. Nothing reaches stdout on that lane, and the command still exits 0.

Usage

fjall target                  # same as fjall target list
fjall target list
fjall target get
fjall target set [name]

Subcommand	What it does
`list`	List every derived target and mark the active one with `▸`
`get`	Show the active target’s environment, account and region
`set [name]`	Set the active target for this checkout

Bare fjall target dispatches to list. Every subcommand also accepts -v, --verbose, --non-interactive, and the agent-output flags --agent, --budget <level>, --fields <list> and --full. See Agent mode.

Target names

A target name is the lowercased account name followed by an abbreviated region:

<accountname>-<regionabbrev>

The abbreviation is the first region segment, a short code for the compass direction, and the trailing number. Compound directions get two letters (southeast is se, northeast is ne) and so does south (so), which keeps ap-south-1 and ap-southeast-1 apart.

Region	Abbreviation	Example target name
`us-east-1`	`use1`	`production-use1`
`us-east-2`	`use2`	`production-use2`
`eu-west-1`	`euw1`	`staging-euw1`
`eu-west-2`	`euw2`	`development-euw2`
`eu-central-1`	`euc1`	`staging-euc1`
`ap-southeast-2`	`apse2`	`production-apse2`
`ap-south-1`	`apso1`	`production-apso1`
`ap-northeast-1`	`apne1`	`production-apne1`

Asia Pacific target names changed in fjall 32. ap-southeast-*, ap-northeast-*, ap-south-*, af-south-1, eu-south-* and me-south-1 previously abbreviated to a single direction letter, which gave ap-southeast-1 and ap-south-1 the same name. A target name using an old code is refused with the replacement to use, never resolved to a region you did not name. Run fjall target list for the current names, then fjall target set <name> to re-point. Every other region is unaffected.

Account names can contain hyphens, so acme-prod-use1 is the account acme-prod in us-east-1.

How the list is derived

Fjall crosses every connected account with every configured region:

Accounts: every connected account except the organisation (management) tier. Platform-tier accounts are included.
Regions: your organisation’s primary region, its secondary regions, and its disaster recovery region.
Order: environment, then account name, then region.

Adding a region to your organisation config therefore adds one new target per account.

List targets

fjall target list --non-interactive

==> [1/1] Fetching deployment targets
  ▸ production-use2  production · production · us-east-2  ✓ ready
    staging-euw1  staging · staging · eu-west-1  ! not ready — account stack missing

  Active: production-use2
<== [1/1] Fetching deployment targets (1.2s)

── Summary ────────────────────────────────────────
  Result:   ✓ Deployment targets listed successfully
  Duration: 1.2s
  Count:    2

Each row is the target name followed by its environment, account name and region. The active target carries a ▸ marker and a bold name.

Readiness annotations

fjall target list probes each target and annotates the row. The probe is advisory: it never fails the command.

Annotation	Meaning
`✓ ready`	The account’s governance stack is deployed in that region
`! not ready`	Followed by the first reason: `account stack missing` or `IPAM pool missing`
(nothing)	The probe could not run, for example with no AWS session

The IPAM pool is only part of the check for an organisation that has a management account. A solo connected account is judged on its stack alone. When some targets could not be probed, the output closes with a dim Readiness not checked for 1 of 2 targets: no AWS session line. Deploy the missing stack with fjall org deploy, or fjall account deploy when your organisation has no management account.

Empty results

Message	Cause
`No deployment targets available. Connect an AWS account first.`	No connected accounts outside the organisation tier
`Connected account(s) found, but no deployment regions are configured...`	Accounts exist, but no region is registered yet

The second case is not an error. Run fjall target set and pick a region: selecting one adds it to your organisation’s regions.

Show the active target

fjall target get --non-interactive

==> [1/1] Loading active target
production-use2
    Environment: production
    Account:     production (123456789012)
    Region:      us-east-2
<== [1/1] Loading active target (0.4s)

── Summary ────────────────────────────────────────
  Result:   ✓ production-use2 retrieved successfully
  Duration: 0.4s

The name alone is on stdout, because it is the result. The Environment, Account and Region lines are on stderr, so TARGET=$(fjall target get --non-interactive) captures just the name. With no active target, the command prints No active target set. Use 'fjall target set <name>' to set one. on stderr, writes nothing to stdout, and still exits 0. If the recorded name no longer resolves to a connected account, the status is stale and the output carries Target no longer exists in organisation config. That happens when the account was disconnected, renamed, or promoted to the organisation tier. Run fjall target set again. A name Fjall cannot resolve stays off stdout. The detail lines are replaced by Active target: <name> and the reason, both on stderr.

Set the active target

fjall target set production-use2

==> [1/1] Setting active target
  ✓ Active target set to production-use2
    Environment: production
    Account:     production (123456789012)
    Region:      us-east-2
  ✓ Target infrastructure is ready
<== [1/1] Setting active target (2.1s)

── Summary ────────────────────────────────────────
  Result:   ✓ production-use2 set successfully
  Duration: 2.1s

Naming a target sets it directly, at a TTY or not. Run fjall target set with no name to choose the account and region from pickers instead.

Options

Option	Description
`-y, --yes`	Add the target’s region to your organisation’s regions without prompting
`--create-config`	Create a new `fjall-config.json` here even though no Fjall project was found

Choosing a region your organisation has not registered

Target names are resolved against every AWS region, not only the configured ones. Setting a target in an unregistered region therefore has a side effect: the region is written back to your organisation config, where it becomes available to every account and is included in organisation deploys. Fjall never does that silently.

Interactive
Non-interactive

The region picker lists your configured regions plus an Other region… row. Picking an unregistered region raises a confirmation before anything is written:

? eu-west-1 isn't in your organisation's regions yet. Add it as a secondary region?
  > Add eu-west-1 and set target      Available to all accounts · included in organisation deploys
    Choose another region             Keep organisation regions unchanged

Confirming prints Adding eu-west-1 to your organisation's regions..., then the usual confirmation card.

The command fails and names the cure:

eu-west-1 is not in your organisation's configured regions. Re-run with --yes
to add eu-west-1 as a secondary region, or run 'fjall target set' interactively
to confirm.

Re-run with -y to accept:

fjall target set staging-euw1 --yes

  ✓ Active target set to staging-euw1
  ✓ Added eu-west-1 to your organisation's regions — available to all accounts and included in organisation deploys

The write is composed from a fresh read of the organisation config, so a region another machine or the web app added in the meantime is never reverted. If the region turns out to be configured already, nothing is written and the command succeeds.

When your organisation has no primary region yet, the region you pick becomes the primary region rather than a secondary one. The interactive prompt and the --yes advisory both say so, and the wording changes to <region> will become your organisation's primary region. Add it?. A primary region cannot be changed after your first successful deploy, so read the prompt before confirming.

Running outside a Fjall project

The active target is stored per checkout, so fjall target set needs a project to anchor it to. With no fjall-config.json in the current directory or any parent, the command refuses rather than planting a stray config:

No fjall project was found in this directory or any parent — 'fjall target set'
here would create '/Users/you/fjall/fjall-config.json'.

Fjall projects found in nearby directories:
  ./acme — apps: api, web; active target: production-use2

cd into your project directory and re-run, or re-run with --create-config to
create the config here deliberately.

Interactively the same situation raises a confirmation instead: Create the config here or Cancel. A freshly scaffolded fjall/<app>/infrastructure.ts layout is exempt, because its first target set legitimately writes the project’s first config.

Readiness after a set

Once the target is saved, Fjall probes it and prints one line:

Line	Meaning
`✓ Target infrastructure is ready`	The probe found everything it looks for
`! Target "..." is not ready in ...`	Names what is missing and the deploy that provisions it
`Readiness not checked: no AWS session`	The probe could not run

The unready line is a full sentence, for example:

! Target "production" is not ready in us-east-2: the Account stack was not found
in us-east-2. Run `fjall org deploy` — the cascade provisions every account and
creates the IPAM pool.

An unready target is a warning, not a refusal. The target is still set.

Where the active target is stored

fjall target set writes activeTarget to .fjall/local.json, a git-ignored file beside fjall-config.json. The choice is per developer and per checkout, so a colleague’s target and a CI pipeline’s never inherit yours.

An activeTarget inside the committed fjall-config.json is legacy. Fjall reads it only to print a deprecation warning, then behaves as if no target were set. Delete it from the committed file and run fjall target set <name> instead.

Agent output

--agent emits structured records for all three subcommands.

Command	Default fields	Extra fields via `--fields`
`target list`	`name`, `environment`, `accountName`, `region`, `active`, `readiness`	`accountId`
`target get`	`target`, `status`, `environment`, `accountName`, `region`	`accountId`, `warning`
`target set`	`target`, `environment`, `accountName`, `region`, `regionAdded`, `readiness`	`accountId`, `readinessAdvisory`, `readinessNote`

target get reports status as active, stale or none. target list also carries a totalCount aggregate and the active target’s name. The single-record blocks (target get and target set) name the target target, the same spelling every command accepts it under as --target, so an answer can be passed straight back. target list keeps name: each row is a target, so the identifier is the row’s own property. A --fields projection naming name on target get or target set fails with VALIDATION_ERROR before the command runs. The error names name as unknown and lists that command’s valid fields, which are the default and extra fields of its row above. Name target instead. fjall target list --fields name is unchanged.

Handling failures

Message	Cause	Fix
`Failed to fetch organisation config`	Not signed in, or the organisation has no config yet	`fjall login`
`Authentication required`	`target set` needs a session to write the region back	`fjall login`
`Target 'production-use3' not found`	The name matches no account and region pair	`fjall target list` and copy a name
`Target no longer exists in organisation config`	The saved target’s account is no longer connected	`fjall target set` again
`<region> is not in your organisation's configured regions`	The region is not registered for the organisation	Re-run with `-y`, or set the target interactively
`No fjall project was found in this directory or any parent`	`target set` outside a project	`cd` into the project, or pass `--create-config`

Next Steps

Understanding profiles

How a target becomes an AWS profile, and how a deploy resolves its account.

Run AWS commands

Use fjall aws exec --target <name> to run any AWS command with minted credentials.

Deploy an application

Ship an application to the active target.

Connect an account

Add the AWS accounts that targets are derived from.

Core Commands

Infrastructure Codemods

Insights

Management Commands

Build & CI

Environments & Data

Diagnostics & Recovery

Authentication

Agent Mode

fjall target

Overview

Prerequisites

Usage

Target names

How the list is derived

List targets

Readiness annotations

Empty results

Show the active target

Set the active target

Options

Choosing a region your organisation has not registered

Running outside a Fjall project

Readiness after a set

Where the active target is stored

Agent output

Handling failures

Next Steps

Understanding profiles

Run AWS commands

Deploy an application

Connect an account

​Overview

​Prerequisites

​Usage

​Target names

​How the list is derived

​List targets

​Readiness annotations

​Empty results

​Show the active target

​Set the active target

​Options

​Choosing a region your organisation has not registered

​Running outside a Fjall project

​Readiness after a set

​Where the active target is stored

​Agent output

​Handling failures

​Next Steps

Understanding profiles

Run AWS commands

Deploy an application

Connect an account

Overview

Prerequisites

Usage

Target names

How the list is derived

List targets

Readiness annotations

Empty results

Show the active target

Set the active target

Options

Choosing a region your organisation has not registered

Running outside a Fjall project

Readiness after a set

Where the active target is stored

Agent output

Handling failures

Next Steps