Setup

After installing BMC, complete these setup steps to get everything working.

Step	Description
Shell integration	Required for `bmc profsel` to export `AWS_PROFILE`
Configuration	`~/.config/bmc/config.json` reference
MFA	Automatic MFA session refresh with TOTP

Run bmc doctor at any time to check your setup.

Shell Integration

Shell integration is required for bmc profsel to set AWS_PROFILE in your current shell session.

Install #

bmc install-shell-integration

This installs a shell wrapper function:

zsh / bash: appends to ~/.zshrc or ~/.bashrc
Fish: writes ~/.config/fish/functions/bmc.fish (auto-loaded, no restart needed)
NixOS + Fish: prints a programs.fish.functions snippet instead of writing files

After installation, restart your shell or source the config file.

Configuration

BMC is configured via ~/.config/bmc/config.json.

Example #

{
  "mfa": {
    "enabled": true,
    "totp_script": "/usr/bin/rbw get my-aws-mfa-entry --field totp",
    "copy_command": "wl-copy",
    "paste_command": "wl-paste | wtype -"
  },
  "ec2": {
    "auto_start_stopped": "prompt",
    "columns": ["InstanceId", "Name", "PrivateIP", "PublicIP", "State", "Hibernate", "Scheduler"]
  },
  "console": {
    "firefox_containers": true
  }
}

Reference #

Key	Type	Default	Description
`mfa.enabled`	bool	`false`	Enable MFA session management
`mfa.totp_script`	string	`""`	Shell command to generate a 6-digit TOTP code
`mfa.copy_command`	string	`""`	Command to copy TOTP to clipboard (receives code via stdin)
`mfa.paste_command`	string	`""`	Command to simulate paste keystroke 300ms after copy
`ec2.auto_start_stopped`	string	`"prompt"`	`always` / `never` / `prompt` — what to do when connecting to a stopped instance
`ec2.columns`	[]string	all columns	Columns to show in EC2 tables, in order
`console.firefox_containers`	bool	`false`	Open AWS console in Firefox container tabs via the Granted extension
`console.chrome_profiles`	bool	`false`	Open AWS console in isolated Chrome profiles per AWS account
`console.chrome_binary`	string	`"google-chrome"`	Chrome binary to use (`"chromium"`, `"brave-browser"`, etc.)

EC2 columns #

The ec2.columns field controls which columns appear in EC2 instance tables and in what order. Available values:

MFA

BMC handles MFA automatically. When you run bmc profsel or bmc console, BMC checks if your session credentials are still valid and refreshes them if needed — no separate command required.

Requirements #

Set mfa.enabled = true in ~/.config/bmc/config.json
Add a [profile-long-term] section to ~/.aws/credentials:

[technative-long-term]
aws_access_key_id     = AKIA...
aws_secret_access_key = ...
aws_mfa_device        = arn:aws:iam::123456789012:mfa/your-username

When the session expires, BMC prompts for a 6-digit TOTP code. If totp_script is configured, BMC runs it automatically to fetch the code.