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

> Authenticate the Fjall CLI with an API key or the browser device-code flow to run AWS deployment commands.

<Info>
  **Interactive command.** Authenticates the Fjall CLI and stores credentials in `~/.fjall/auth.json`.
</Info>

## Usage

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

`fjall login` authenticates the CLI against your Fjall account and stores credentials locally. There are two paths:

* **Device-code** (default in interactive mode): a browser window confirms the login.
* **API key**: paste a key from the dashboard, or pass `--api-key`.

There is no SSO or identity-provider integration.

## Options

| Option              | Description                                              | Example                     |
| ------------------- | -------------------------------------------------------- | --------------------------- |
| `--api-key <key>`   | Authenticate with an API key instead of the browser flow | `--api-key fj_0c57c208_...` |
| `--device`          | Force the browser device-code flow                       | `--device`                  |
| `-f, --force`       | Overwrite existing credentials                           | `--force`                   |
| `-v, --verbose`     | Show detailed output                                     | `-v`                        |
| `--non-interactive` | Disable prompts (requires `--api-key` or `--device`)     | `--non-interactive`         |

## Authentication Flow

### Interactive login

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

The command checks for saved credentials first. If none exist, it starts the browser device-code flow:

```
Open this URL to authorise:
  https://fjall.io/auth/device?code=WDJB-MJHT

Verification code: WDJB-MJHT

Waiting for approval...
```

Open the URL (the verification code is pre-filled) and approve. To enter an API key instead, press `e` during this step.

If you are already logged in, the command asks before overwriting (a Yes/No selector, defaulting to No):

```
? You already have credentials saved. Overwrite them?
```

### Device-code login

Force the browser flow even when credentials exist:

```bash theme={null}
fjall login --device --force
```

### API-key login

Skip the browser entirely by passing a key:

```bash theme={null}
fjall login --api-key fj_0c57c208_...
```

Generate API keys from the Fjall dashboard.

## How It Works

1. Checks for existing credentials at `~/.fjall/auth.json`.
2. Runs the browser device-code flow, or validates the supplied API key.
3. Stores credentials locally with `0600` permissions.
4. Confirms access to your Fjall account.

## Credential Storage

Fjall writes credentials to your home directory:

```
~/.fjall/
└── auth.json
```

These credentials:

* Stay on your machine, never synced.
* Authenticate API requests.
* Carry restrictive file permissions (`0600`).
* Can be removed at any time.

## CI/CD Integration

Device-code login needs an interactive browser and does not work in CI. Use a **CI deploy token** instead — mint one in the web app under **Settings → CI/CD Tokens** (see [CI/CD Integration](/deployment/ci-cd)):

**Environment variable (recommended)**

```bash theme={null}
export FJALL_API_KEY=fjall_dk_...
```

The CLI reads `FJALL_API_KEY` before stored credentials, so no `fjall login` call is required.

**Non-interactive login**

```bash theme={null}
fjall login --api-key fj_0c57c208_... --non-interactive
```

In non-interactive mode you must pass `--api-key` or `--device`; the command errors otherwise. `--device` still needs a human to open the printed URL and approve within 15 minutes (the poll times out otherwise), so unattended pipelines should use `--api-key` or `FJALL_API_KEY`.

<Note>
  `fjall login --api-key` accepts legacy `fj_` user keys only — it stores the
  key as your credential. Scoped tokens (`fjall_dk_` deploy tokens,
  `fjall_ak_` agent tokens) are not stored by `fjall login`; pass them via
  `FJALL_API_KEY` instead, which every command reads directly. For pipelines
  prefer a deploy token; for AI agents acting as you, use an agent token from
  [`fjall token create`](/cli/token).
</Note>

## Security

* Keep the `~/.fjall/` directory private.
* Generate a separate API key for each environment.
* Rotate keys on a regular schedule.

### Removing Credentials

```bash theme={null}
rm ~/.fjall/auth.json
```

## Troubleshooting

### Authentication failed

```bash theme={null}
Authentication failed, please check your credentials and try again.
```

Common causes and fixes:

| Cause             | Fix                                                      |
| ----------------- | -------------------------------------------------------- |
| Incorrect API key | Verify the key, or generate a new one from the dashboard |
| Expired API key   | Regenerate the key                                       |
| Network issues    | Check connectivity, then retry                           |

### Not authenticated

If commands report you are not authenticated:

* Run `fjall login` again.
* Confirm `~/.fjall/auth.json` exists.
* Verify the file is readable (`0600` for your user).

### Shared machines

Each OS user has separate credentials under their own home directory, so there are no conflicts between users.

## Next Steps

<CardGroup cols={2}>
  <Card title="Create an application" icon="cube" href="/cli/create">
    Scaffold an app and its infrastructure.
  </Card>

  <Card title="Connect AWS" icon="aws" href="/cli/connect">
    Link an AWS account before deploying.
  </Card>

  <Card title="Deploy" icon="rocket" href="/cli/deploy">
    Push your application to AWS.
  </Card>

  <Card title="List resources" icon="list" href="/cli/list">
    Inspect resources in an application's infrastructure.
  </Card>
</CardGroup>

<Note>
  Login is optional for local-only work. It is required for any command that talks to Fjall's cloud services.
</Note>