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

> Connect an AWS account to Fjall via OIDC federation for secure, short-lived credentials. No long-term secrets stored.

<Info>
  **Interactive command.** Opens your browser to deploy an OIDC CloudFormation stack for secure, short-lived credentials.
</Info>

## Usage

```bash theme={null}
fjall connect [options]
```

`fjall connect` establishes a secure OIDC connection between Fjall and an AWS account. Use it to:

* Add another AWS account to your organisation.
* Connect an existing standalone account.
* Recover from AWS-side trust drift with `--force` (the IAM role was deleted but Fjall still tracks the connection as active).

The first account is connected automatically by `fjall create org`. Run `fjall connect` for every account you add after that.

## Prerequisites

* Authenticated with `fjall login`.
* Permission in the target AWS account to create IAM roles and CloudFormation stacks.

## What It Does

1. Opens your browser to deploy a CloudFormation stack in the target AWS account.
2. The stack creates an IAM OIDC provider and a role that Fjall assumes on demand.
3. Polls for stack completion.
4. Caches the connection locally and syncs it to the Fjall webapp.

## Options

| Option                | Description                                                                                                                                                                          | Default     |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| `--region <region>`   | AWS region for the CloudFormation stack                                                                                                                                              | `us-east-2` |
| `--environment <env>` | Environment label for this account: `production`, `staging`, `development`, `platform`, or `compliance` (`root` is reserved for scripted AWS Organizations management-account setup) |             |
| `--name <name>`       | Human-readable name for the AWS account (for example, `Production`)                                                                                                                  |             |
| `--force`             | Overwrite an existing matching `(region, environment)` connection with a fresh CloudFormation stack. Use to recover from trust drift                                                 |             |
| `--verbose`           | Enable verbose logging                                                                                                                                                               |             |
| `--non-interactive`   | Force plain CLI output (no UI)                                                                                                                                                       |             |

## Examples

### Interactive (recommended)

```bash theme={null}
fjall connect
```

The interactive flow:

1. Opens your default browser to deploy the OIDC CloudFormation stack.
2. Shows a progress indicator while waiting for stack completion.
3. Confirms the connection and displays account details.

### Connect a named staging account

```bash theme={null}
fjall connect --name Staging --environment staging --region ap-southeast-2
```

### Non-interactive

```bash theme={null}
fjall connect --region ap-southeast-2 --non-interactive
```

### Recover from trust drift

```bash theme={null}
fjall connect --force --region us-east-2 --environment production
```

### Typical workflow

```bash theme={null}
# 1. Log in to Fjall
fjall login

# 2. Connect your AWS account
fjall connect

# 3. Create account infrastructure
fjall create account

# 4. Create an application
fjall create app

# 5. Deploy your application
fjall deploy web
```

## Troubleshooting

### Browser does not open

If the browser fails to open automatically:

* Copy the URL from the terminal output and open it manually.
* Sign in to the correct AWS account in your browser.

### Stack deployment fails

If the OIDC CloudFormation stack fails:

* Check that your AWS account has permission to create IAM roles and CloudFormation stacks.
* Retry with `fjall connect` to re-open the browser flow.

### Connection already exists

If a matching connection already exists, `fjall connect` short-circuits the flow. To connect a different AWS account, run `fjall connect` with credentials for the new account. To overwrite an existing connection or recover from trust drift, add `--force`.

<Note>
  The OIDC connection provides short-lived credentials, so no long-term secrets are stored. Fjall assumes the IAM role on demand using OpenID Connect federation.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="fjall create" icon="plus" href="/cli/create">
    Provision account infrastructure or scaffold an application after connecting.
  </Card>

  <Card title="fjall deploy" icon="rocket" href="/cli/deploy">
    Deploy an application, organisation, platform, or account.
  </Card>

  <Card title="Understanding Profiles" icon="key" href="/deployment/understanding-profiles">
    See how AWS profiles are derived automatically from org config.
  </Card>

  <Card title="Create Application" icon="sparkles" href="/deployment/create-application">
    Scaffold a new application from a pattern.
  </Card>
</CardGroup>