Wrapper command.
fjall aws exec spawns the command you give it with AWS
credentials injected into that child process. exec is the only subcommand.Overview
fjall aws exec is how you run an AWS command against an account Fjall manages without configuring anything locally. No ~/.aws/config profile, no aws sso login, no long-lived access keys on your laptop.
Fjall resolves the account you name, mints a short-lived STS session for it, and hands that session to your command as environment variables. The command runs, the process exits, the credentials go with it.
Anything that reads AWS credentials from the environment works: the aws CLI, terraform, a Node or Python script using the AWS SDK.
Prerequisites
Usage
-- between Fjall’s own flags and your command. Everything after the separator is passed to the child untouched, including its flags: fjall aws exec sets allowUnknownOption, so a flag such as --query or --output reaches the aws CLI rather than being rejected by Fjall.
fjall aws with no subcommand prints Available subcommands: exec and exits 1. So does any other subcommand name.
Choosing the account
Target names are derived as
<accountname>-<regionabbrev>, for example production-use2 or development-euw1. Discover them with fjall target list.
--target matching is exact and case-sensitive. An unknown name is a hard error naming the valid targets, never a silent fallback to a different account.
The management account
The reserved target namemanagement addresses your AWS Organizations management account. It requires an explicit second opt-in:
--confirm-management the command refuses and explains why. The guard exists because the management account is the one place where a mistyped command has organisation-wide blast radius, and because a bare word target reads like any other. Credentials for it are minted through the organisation OIDC connection and audited.
Solo-mode organisations have no management account, so --target management refuses there too.
Timeouts
The child is killed if it has not finished in time. The default deadline is 10 minutes.Why the ceiling is one hour. Fjall mints the STS session for 3600 seconds,
and the credentials are injected into the child as static environment
variables that nothing refreshes while it runs. A command
allowed to outlive its own session could not finish, it could only fail
partway through with an AWS auth error that says nothing about the timeout.
Capping at the session length keeps the deadline meaningful. Split longer work
into shorter phases.
--timeout is a refusal with a message naming the problem, not a silent fall back to the default.
A cached session is handed out with whatever validity it has left. When the remaining credential life is shorter than the timeout you asked for, Fjall prints a warning up front rather than letting you discover it from an auth failure mid-command.
What the child process receives
Fjall builds the child’s environment from your own, then:
Stripping the profile variables is load-bearing: leaving
AWS_PROFILE set makes the AWS SDK inside the child ignore the injected keys and resolve a profile from ~/.aws/credentials instead, which is how a command lands in the wrong account.
The credentials go to the child process and nowhere else. Fjall writes no AWS profile and no credentials file for this, and a child process cannot alter its parent’s environment, so nothing is exported into the shell you ran the command from. When the process exits, the session is gone, and it expires within the hour regardless.
stdin stays connected in every mode, so piping into the child keeps working:
Options
In agent mode the child’s stdout and stderr are framed as structured event blocks instead of streaming raw, so child bytes cannot interleave the output stream. See Agent mode.
What your token needs in CI
aws exec crosses two routes, so it needs two scopes: read to resolve the target, and deploy:oidc:mint to mint the session. The mint route applies a second, independent gate on the kind of token, not just its scopes: only a deploy token may mint AWS credentials.
A token that fails either gate gets a 403:
Exit codes
The wrapped command’s exit code becomes Fjall’s exit code, so CI can gate on it directly.Errors
Examples
Confirm identity before a write
Inspect storage in one region of a target
Run a long job with a raised deadline
Read the organisation’s account list
Next Steps
Deployment targets
List, inspect, and set the target that names an account and region.
Connect an AWS account
Set up the AWS connection the credentials are minted from.
Understanding profiles
See how accounts, regions, and roles are derived rather than authored.
Agent mode
Structured output for scripted and agent callers.