Configuration

Config file

bctl stores configuration at ~/.config/bctl/config.yaml.

tenant: acme                    # Britive tenant name (acme.britive-app.com)
default_region: us-east-1       # fallback AWS region
auth:
  method: browser               # browser | token

profiles:
  dev:
    profile_id: "abc123"        # set by 'bctl profiles sync'
    env_id: "xyz789"            # set by 'bctl profiles sync'
    britive_path: "App/Env/Profile"
    aws_profile: dev            # ~/.aws/credentials profile name
    cloud: aws
    region: us-east-1
    eks_clusters:
      - my-dev-cluster
  staging:
    profile_id: "def456"
    env_id: "uvw012"
    britive_path: "App/Staging/Profile"
    aws_profile: staging
    cloud: aws
    region: us-west-2

Tip

Run bctl profiles sync to populate profile_id and env_id automatically. The other fields can be customised by hand.

Environment variables

Environment variables override values in the config file.

Variable	Description
BCTL_TENANT	Override the tenant name
BCTL_TOKEN	Use this API token (skips keychain lookup)
BCTL_OUTPUT	Default output format (awscreds, json, env, process)
BCTL_REGION	Default AWS region
BCTL_NO_COLOR	Disable colour output
BCTL_KEYRING_BACKEND	Force the credentials backend. Set to file to skip the OS keychain and store the token in an encrypted file under the bctl config directory. Useful on WSL and other headless Linux environments without a keychain daemon.

Auth methods

Browser SSO

bctl init        # set method: browser
bctl login       # opens browser, stores token in keychain

Tokens are stored in the OS keychain (macOS Keychain, Windows Credential Manager, libsecret or KWallet on Linux). When the session JWT expires, the next bctl command automatically opens your browser for SSO, stores the new token, and continues with the original command -- no separate bctl login needed. On WSL and other headless Linux environments without a running keychain daemon, bctl falls back to an encrypted file under the bctl config directory; the same fallback can be forced anywhere by setting BCTL_KEYRING_BACKEND=file.

API token

bctl login --token <token>

Or set BCTL_TOKEN in your environment to bypass the keychain entirely. Useful for CI pipelines.

Profile aliases

Aliases are the short names you use with checkout, checkin, and eks connect. They are set by bctl profiles sync using a sanitised version of the Britive profile name, but you can rename or add profiles manually:

profiles:
  my-alias:           # whatever you want to type
    profile_id: "..."
    env_id: "..."
    aws_profile: my-alias
    cloud: aws
    region: us-east-1

EKS clusters

Add eks_clusters to any profile to enable bctl eks connect and bctl checkout --eks:

profiles:
  dev:
    aws_profile: dev
    region: us-east-1
    eks_clusters:
      - dev-cluster-1
      - dev-cluster-2

bctl runs aws eks update-kubeconfig for each cluster in sequence after checkout.