SSO & profiles

Every account you have access to, without quitting the tool

Most people do not have one AWS account. They have a production one, a staging one, a personal one, and a sandbox, each behind Identity Center, some reached by assumed role. orbit resolves credentials the same way the AWS CLI does, and lets you move between them mid-session.

Install orbit brew install doughlass/homebrew-tap/orbit

The credential chain

orbit does not implement its own authentication. It uses the standard AWS credential chain, in this order:

01 Environment variables
02 SSO / AWS Identity Center
03 Console login
04 ~/.aws/credentials
05 ~/.aws/config
06 IMDSv2, for running on an EC2 instance with an instance profile

The practical consequence is that if a credential works for the AWS CLI, it works for orbit. There is no separate login, no token to paste, and no config file of orbit's own to maintain.

AWS SSO and Identity Center

If your profile uses Identity Center, orbit handles the token for you. Run aws sso login as usual and orbit reuses the cached token, so you are not asked to authenticate twice. If the token has expired and you have not logged in again, orbit prompts you to authenticate from within the app.

This is the common failure mode for SSO tooling, and it is worth being explicit: a tool that cannot refresh an expired SSO session forces you to drop out, log in, and start again, losing your place. orbit reuses whatever the chain provides and only asks when there is genuinely nothing to reuse.

Switching accounts and regions mid-session

Switching is a command-mode action, not a restart. Press : and choose :profiles or :regions. The profile and region in use are always visible in the header, so you can tell at a glance which account you are looking at — which matters when the whole point is comparing accounts.

orbit --profile prod                 # start on a named profile
orbit --region eu-west-1             # start on a named region
:profiles                          # switch account mid-session
:regions                           # switch region mid-session
0–5                              # jump between regions by number

A common workflow this makes possible: open the same resource type, confirm the account in the header is staging, switch to production, and check whether the same instance type or security group exists there too.

Role assumption

Role assumption is fully supported through a normal profile in ~/.aws/config. Both patterns work: role_arn with source_profile, and role_arn with credential_source, including the EC2, ECS and Environment sources.

Because orbit signs requests with whatever the chain resolves, an assumed role does not need anything configured on the orbit side. If aws sts get-caller-identity --profile my-role returns the right account, orbit will see the same thing.

Environment variables

Four variables cover the cases where the chain is not enough.

Variable	Purpose
`AWS_PROFILE`	Default profile to use
`AWS_REGION`	Default region to use
`AWS_ENDPOINT_URL`	Custom endpoint, such as LocalStack
`AWS_CA_BUNDLE`	Corporate certificate bundle, for proxies doing SSL inspection

LocalStack and corporate proxies

Working against emulated AWS services locally needs one flag:

orbit --endpoint-url http://localhost:4566     # point at LocalStack

If you are behind a corporate proxy that inspects TLS, set AWS_CA_BUNDLE to your organisation's certificate bundle. Without it, orbit's API calls fail certificate validation, which presents as an opaque connection error rather than anything obviously about proxies.

Logs

When authentication is not behaving, orbit writes a debug log. Enable it with --log-level debug. The log lives at ~/Library/Application Support/orbit/orbit.log on macOS and ~/.config/orbit/orbit.log on Linux.

SSO and profile questions

Does orbit work with AWS SSO?

Yes, with no extra configuration. orbit uses the standard AWS credential chain, so Identity Center and SSO work as they do for the AWS CLI. If your profile uses Identity Center and the token has expired, orbit prompts you to authenticate. If you already ran aws sso login, orbit reuses the cached token rather than asking again.

Can I switch between multiple AWS accounts and profiles in orbit?

Yes. Press : and choose :profiles to switch AWS profile without restarting, and :regions to switch region. You can also start on a specific account with orbit --profile prod, and set the default with AWS_PROFILE. This makes it practical to compare the same resource type across several accounts in one session.

Does orbit support role assumption?

Yes. A profile that uses role_arn with source_profile is fully supported, as is credential_source, including the EC2, ECS and Environment sources. Whatever the standard AWS chain resolves is what orbit signs its requests with.

Can I use orbit with LocalStack?

Yes. Run orbit --endpoint-url http://localhost:4566 to point orbit at LocalStack instead of AWS, or set AWS_ENDPOINT_URL in your environment. This is useful for developing against emulated AWS services locally.

I am behind a corporate proxy with SSL inspection. Does orbit work?

Set AWS_CA_BUNDLE to the path of your corporate certificate bundle. orbit respects that variable, so TLS interception by a proxy does not break its API calls.