> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fjall.io/llms.txt
> Use this file to discover all available pages before exploring further.

# fjall target

> List, inspect and set the active Fjall deployment target: the AWS account and region pair that every deploy lands in.

<Info>
  **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. From fjall 32, naming a target
  sets it directly either way; on fjall 31 a name at a terminal opens the
  pickers anyway, so setting a named target there takes `--non-interactive`.
</Info>

## 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`](/cli/deploy) lands and which credentials [`fjall aws exec`](/cli/aws) mints.

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](/deployment/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`](/cli/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 prints a name when the organisation config cannot be fetched. It adds `(Could not fetch organisation config for details)` instead of the account and region.

## Usage

```bash theme={null}
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](/cli/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. From fjall 32, 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`  |

<Note>
  **Asia Pacific target names change in fjall 32.** `ap-southeast-*`,
  `ap-northeast-*`, `ap-south-*`, `af-south-1`, `eu-south-*` and `me-south-1`
  abbreviated to a single direction letter before that, which gave
  `ap-southeast-1` and `ap-south-1` the same name. The table above carries the
  fjall 32 names; on fjall 31 those regions still take the single letter, so
  `ap-southeast-2` is `aps2` rather than `apse2`. From fjall 32 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.
</Note>

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

```bash theme={null}
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`](/deployment/deploy-organisation), or [`fjall account deploy`](/deployment/deploy-account) 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

```bash theme={null}
fjall target get --non-interactive
```

```
==> [1/1] Loading active target
  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
```

With no active target, the command prints `No active target set. Use 'fjall target set <name>' to set one.` 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.

## Set the active target

```bash theme={null}
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
```

<Note>
  From fjall 32, naming a target sets it directly, at a TTY or not. On fjall 31
  add `--non-interactive`, or the pickers open and the name is ignored. Run
  `fjall target set` with no name to choose the account and region from pickers
  instead.
</Note>

### 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.

<Tabs>
  <Tab title="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.
  </Tab>

  <Tab title="Non-interactive">
    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:

    ```bash theme={null}
    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
    ```
  </Tab>
</Tabs>

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.

<Warning>
  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.
</Warning>

### 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.

<Warning>
  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.
</Warning>

## Agent output

`--agent` emits structured records for all three subcommands.

| Command       | Default fields                                                             | Extra fields via `--fields`                       |
| ------------- | -------------------------------------------------------------------------- | ------------------------------------------------- |
| `target list` | `name`, `environment`, `accountName`, `region`, `readiness`                | `accountId`, `active`                             |
| `target get`  | `name`, `status`, `environment`, `accountName`, `region`                   | `accountId`, `warning`                            |
| `target set`  | `name`, `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.

## Handling failures

| Message                                                      | Cause                                                 | Fix                                               |
| ------------------------------------------------------------ | ----------------------------------------------------- | ------------------------------------------------- |
| `Failed to fetch organisation config`                        | Not signed in, or the organisation has no config yet  | [`fjall login`](/cli/login)                       |
| `Authentication required`                                    | `target set` needs a session to write the region back | [`fjall login`](/cli/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

<CardGroup cols={2}>
  <Card title="Understanding profiles" icon="user-gear" href="/deployment/understanding-profiles">
    How a target becomes an AWS profile, and how a deploy resolves its account.
  </Card>

  <Card title="Run AWS commands" icon="terminal" href="/cli/aws">
    Use `fjall aws exec --target <name>` to run any AWS command with minted credentials.
  </Card>

  <Card title="Deploy an application" icon="rocket" href="/cli/deploy">
    Ship an application to the active target.
  </Card>

  <Card title="Connect an account" icon="plug" href="/cli/connect">
    Add the AWS accounts that targets are derived from.
  </Card>
</CardGroup>