Troubleshooting

fgai: command not found

The installer writes fgai to PREFIX/bin, which is /usr/local/bin by default. If the shell cannot find it, PREFIX/bin is not on your PATH. Check where it landed and what the shell searches:

command -v fgai

Re-run the installer with a prefix you control, then add its bin to PATH:

curl -fsSL https://dl.flexgalaxy.ai/fgai/install.sh -o install.sh
PREFIX="$HOME/.local" bash install.sh

See Install for the full download and verification path.

fgai runs, but every command fails the same way

Check which binary answered and what version it is before anything else — an old copy earlier on PATH is the most common cause, and it fails in ways that look like a platform problem:

command -v fgai
fgai version

If the version is not the one on dl.flexgalaxy.ai, you are running a stale binary. Reinstall, and remove the old copy.

no signed credential configured

$ fgai org directory
fgai org directory: no signed credential configured: run `fgai configure` with
an AWS-shaped access key, static AKIA or temporary ASIA with a session token

Commands that read your account’s data need a credential. Public discovery commands do not — these work with no credential at all, which makes them a good first check that the network path itself is fine:

fgai marketplace list --json
fgai pki jwks --json
fgai signing-keys platform --json

Set up a credential with Configure.

fgai configure rejects a token

fgai configure accepts only static AK/SK or temporary STS credentials. Bearer tokens are intentionally rejected — a browser session bearer and a workload (RFC 8693) bearer alike. For an STS session, provide all three credential values:

fgai configure --profile prod --account-id "$ACCOUNT_ID" \
  --access-key-id "$STS_ACCESS_KEY_ID" \
  --secret-access-key "$STS_SECRET_ACCESS_KEY" \
  --session-token "$STS_SESSION_TOKEN"

profile "prod-intl" is deprecated; use "prod"

A credential you stored before the profiles were renamed still records the old name. The CLI does not brick on it — it resolves the old name to the current one and carries on, printing a one-line notice:

$ fgai org directory --auth ci-service-user
fgai: credential "ci-service-user" was configured for the retired profile
"prod-intl"; using "prod" instead.

fgai auth status still shows the stored value, so the row keeps reading prod-intl until you rewrite it. Make it permanent by re-running configure with the same credential name:

fgai configure --kind service-user --profile prod --name ci-service-user \
  --account-id "$ACCOUNT_ID" \
  --access-key-id "$ACCESS_KEY_ID" \
  --secret-access-key "$SECRET_ACCESS_KEY"

Passing a retired name on the command line is a different case, and is refused rather than resolved — see Profiles.

401 from every command at once, and nothing changed

A credential that worked yesterday and fails everywhere today is almost always an expired session rather than a revoked grant — a revocation would usually be narrower. Check what the CLI knows about its lifetime:

fgai auth status --name default

  • expires: 2026-08-19T12:00:00Z (in 42m0s) — still live; the 401 is something else.

  • expires: 2026-08-19T09:00:00Z (EXPIRED 1h13m ago) — that is the cause. The CLI refuses these before dispatch, naming the expiry, so you should not reach a 401 at all.

  • expires: unknown (pasted session) — the credential carries a session token that was pasted in without --expiration, so the CLI cannot tell you when it dies. An expiry is the likeliest explanation for the 401.

  • no expires: line at all — a static AKIA… credential, which does not expire. Look elsewhere.

Fix it by getting a new session (fgai auth workforce login), or re-paste one and record its lifetime this time:

fgai configure --profile prod --account-id "$ACCOUNT_ID" \
  --access-key-id "$STS_ACCESS_KEY_ID" \
  --secret-access-key "$STS_SECRET_ACCESS_KEY" \
  --session-token "$STS_SESSION_TOKEN" \
  --expiration 2026-08-19T12:00:00Z

403 on a command that used to work

A 403 is an authorization answer from the platform, not a CLI fault: the credential authenticated and the requested action was refused for that principal. A 401 means the opposite — the request was not authenticated at all, so check the credential before the permissions. Confirm which credential signed the call:

fgai auth status

Then have the account administrator review that principal’s grants. Narrow service users are refused fleet-wide reads by design.

Keeping test credentials out of your real configuration

Credential files live under the OS-native user config directory. Set FGAI_CLI_HOME to point the whole store somewhere disposable:

FGAI_CLI_HOME="$(mktemp -d)" fgai auth status

Nothing written under that home touches your normal credentials.