Skip to main content
Users and access are declared in code. The fjall user verbs edit the identityCentre block of fjall/organisation/infrastructure.ts. They never call AWS directly. Changes take effect when you run fjall org deploy.

​
Overview

Your organisation’s users, groups and memberships live in the identityCentre config of your organisation infrastructure file. The fjall user verbs are safe, reviewable file editors. They modify the declaration, you commit the diff, and the next organisation deploy makes AWS IAM Identity Center match it.
Because the verbs edit a local file, they need no AWS credentials and no Fjall login. Authentication applies where it always did, at fjall org deploy. Only fjall user list --live and fjall user add --live touch AWS, and both are read-only.

​
Prerequisites

​
Identity source modes

The identityCentre config declares where user objects come from. The verbs adapt to the declared mode. See Users and Permissions for the config shapes and how to choose a mode.

​
Subcommands

​
Add a user or membership

The <email> positional and --group are both required. A missing value is a validation error, not a prompt. Three rules govern the name flags:
  • Pass both --first and --last, or neither. One alone fails with guidance.
  • In fjall-managed mode a new email needs both, because Fjall owns the user object.
  • In external mode --first, --last and --expires are all rejected. Your IdP owns user details, so add the person in Google Workspace first.
The default add is a pure file edit. Pass --live to opt in to a preflight that checks the email is already synced into the identity store.

​
Remove a user or membership

​
List declared users

A pure file read. It shows every declared user and membership, including membership-only entries (emails that appear in groups without a users entry), names, groups and any expires stamps.
--live adds drift columns by querying the identity store read-only. in-store means the email resolves in the identity store, not-synced means it does not. The drift column lists declared memberships that are not yet live in AWS, either pending a deploy or stale after an IdP change. Requires organisation AWS credentials.

​
Re-resolve external users

Bumps resolutionVersion in the config (1 becomes 2) so every external email lookup re-resolves on the next deploy. Use this when your IdP deleted and recreated a user, rotating the underlying user ID, and memberships need to re-bind to the new one.

​
What happens when you run a verb

In an interactive terminal:
  1. Fjall reads fjall/organisation/infrastructure.ts from the current directory.
  2. It plans the change. With --live, it preflights the email against the identity store first.
  3. A confirmation screen shows the target, the file and the plan, then asks Proceed with add user access on organisation "<name>"?. The default is No.
  4. The write lands, alongside a .bak backup and a history snapshot.
  5. Fjall prints Run fjall org deploy to apply the change and offers Deploy the organisation now to apply this change?. The default is No. Accept and the organisation deploy runs in the same session. Identity-only organisation deploys typically take 2 to 5 minutes.
With --non-interactive or --agent, the same substance prints as plain lines and there is no deploy offer. You get the hint to run fjall org deploy yourself.
Wrote the wrong thing? fjall undo -a organisation restores the most recent .bak sidecar. See fjall undo.

​
Setting up an identity source

If your identity store is not set up yet, the verbs fail with a prescriptive error rather than a generic AWS one. For Google Workspace, the guided runbook walks the whole SAML plus SCIM connection:

​
Default groups

Organisations deploy with four built-in permission sets and their matching groups. Add custom groups and permission sets in the identityCentre config, or set defaultPermissionSets: false to opt out. See Users and Permissions. ManagementAccountAccess is deliberately memberless by default, scoped to the management account alone, with 2-hour sessions. It grants nothing until someone joins it. If a deploy finishes and every group is memberless, the deploy summary reminds you to declare access with fjall user add <email> --group <group>.

​
Common workflows

​
Onboard a teammate (external IdP)

Sarah signs in through your IdP. The deploy grants her group’s access across your accounts.

​
Declare a user in fjall-managed mode

​
Grant a contractor time-boxed access

Past-expiry users still holding memberships fail the deploy at synth time, so expired access cannot silently persist. Remove the memberships or extend expires to clear it.

​
Remove all access

​
Audit declared access against AWS

​
Re-bind after an IdP recreates a user

​
Retired verbs

The imperative verbs that wrote directly to AWS were removed in fjall 2.24, along with the deprecated fjall user token alias. Their replacements are all file edits, so follow each one with fjall org deploy to apply.

​
Next Steps

Users and Permissions

The identityCentre config: modes, groups, permission sets, memberships.

Deploy an Organisation

Apply declared identity changes with fjall org deploy.

fjall token

Issue and manage personal and agent API tokens.

Agent Mode

Drive these verbs from AI agents with structured output.