Skip to main content
Interactive command. Authenticates the Fjall CLI and stores credentials in ~/.fjall/auth.json (or $FJALL_CONFIG_DIR/auth.json).
Login is optional for local-only work such as scaffolding and editing infrastructure files. It is required for any command that talks to Fjall’s cloud services or to AWS.

​
Usage

fjall login authenticates the CLI against your Fjall account and stores the credential locally. There are two paths:
  • Device-code (the default): a browser window confirms the login.
  • API key: paste a key from the dashboard, or pass --api-key.
The Fjall credential is the only one you supply. Everything AWS is derived from it. Fjall never reads or writes ~/.aws/config or ~/.aws/credentials, and aws sso login is never part of the flow.

​
Options

​
Authentication flow

​
Interactive login

The command loads any saved credential and revalidates it against the Fjall API. When no valid credential exists it starts the browser device-code flow straight away, opens your browser, and waits:
Approve in the browser to finish. To enter an API key instead, press E at this step. The CLI also falls back to API-key entry on its own if the device-code flow errors. There is no method picker. Interactive login always starts with the device-code flow, and API-key entry is the fallback. When a valid credential is already saved, the command asks first (a Yes/No selector defaulting to No):
Answer No to exit, Yes to continue into the device-code flow. This prompt appears whether or not you pass --force.

​
Device-code login without the UI

Add --non-interactive to run the same flow as plain text, which is what CI logs and agent transcripts show:
In a terminal, --device on its own changes nothing. It routes to the same interactive screen, which already starts with the device-code flow. The flag matters in non-interactive and agent shells, where it selects the browser path over the API-key path.

​
Choosing an organisation

One credential file holds one API key, so the CLI is signed in to exactly one organisation at a time. Pass --org to pick which one the device flow signs you in to:
Two rules apply:
  • --org requires --device. With the API-key path it is refused, because a key authenticates its own organisation.
  • --org forces the non-interactive path. The interactive screen has no organisation input, so routing there would drop the flag.
To work across two organisations from one machine, relocate the whole state root instead of re-logging in:

​
API-key login

Skip the browser entirely by passing a key:
Generate API keys from the Fjall dashboard. The key must start with fj_. Anything else is rejected before the network call with Invalid API key format. Must start with 'fj_'.

​
Agent mode

Agent mode emits a structured browser hand-off block carrying the verification URL, the user code, the expiry and the poll interval, then a result block on completion. See Agent mode.

​
How it works

  1. Loads any credential at ~/.fjall/auth.json and revalidates it against the Fjall API.
  2. Requests a device code, or validates the supplied API key.
  3. Opens your browser and polls until you approve, up to the 15-minute device-code expiry.
  4. Saves the credential with 0600 permissions inside a 0700 directory.
  5. Discovers and records your organisation identity.

​
Credential storage

Fjall writes the credential to its state root:
Set FJALL_CONFIG_DIR to relocate that root. It moves the whole root, credentials plus the connection, org-config and app-id caches, drift journals and CLI logs, so two organisations never share a coherent-looking mix of state. The credential:
  • Stays on your machine, never synced.
  • Authenticates API requests and mints the AWS credentials used to deploy.
  • Carries restrictive file permissions (0600).
  • Can be removed at any time.

​
CI/CD integration

Device-code login needs a human at a browser and does not work unattended. Use a CI deploy token instead. Mint one in the web app under Settings → CI/CD Tokens, then see CI/CD Integration. Environment variable (recommended)
The CLI reads FJALL_API_KEY before any stored credential, so no fjall login call is required. Non-interactive login
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, so unattended pipelines should use --api-key or FJALL_API_KEY.
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.

​
Security

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

​
Removing credentials

​
Troubleshooting

​
Authentication failed

​
Common errors

​
Not authenticated

If commands report you are not authenticated:
  • Run fjall login again.
  • Confirm ~/.fjall/auth.json exists.
  • Verify the file is readable by your user (0600).
  • Check whether FJALL_CONFIG_DIR is set in your shell, which moves the credential elsewhere.

​
Shared machines

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

​
Next Steps

Connect AWS

Link an AWS account before deploying.

Create an application

Scaffold an application and its infrastructure.

Deploy

Push your application to AWS.

Agent mode

Run the CLI as a coding agent with structured output.