AWS SSO CLI replaces the configure sso wizard and encrypts what the AWS CLI leaves in plain text

The problem is many accounts and many roles, not one login

AWS SSO CLI is described as a secure replacement for the aws configure sso wizard, with a focus on security and ease of use for organisations with many AWS accounts, or for users who have many IAM roles to assume.

That framing is the key to what it is and is not. It is not a general purpose AWS credential manager. It is aimed at a specific environment: an organisation that has adopted AWS IAM Identity Center, previously called AWS Single Sign-On, as its access model, and where the person at the keyboard has to move between dozens of accounts and dozens of roles.

The README says the tool shares a lot in common with aws-vault, but is more focused on the IAM Identity Center use case instead of static API credentials. That comparison is informative about the design. aws-vault deals with long lived keys and the roles you can assume with them. This deals with the temporary, role-per-application world that Identity Center creates, where the set of things you can do is discovered rather than configured.

The functional centre of the tool is role selection. You can select a role via $AWS_PROFILE, via CLI arguments with auto-completion, or through an interactive search, and selection can be filtered by user-defined tags and by tags the tool discovers itself, which it can then use to manage your ~/.aws/config file for you.

The other half of the value is the credential handling, and the README is unusually blunt about why it matters.

The SSO access token on disk is the real exposure

The security section of the README makes a specific argument, and it is worth reading as written rather than as marketing.

Unlike the official AWS CLI tooling, all authentication tokens and credentials used for accessing AWS and the SSO provider are encrypted on disk using your choice of secure storage solution, and the encryption is handled by the 99designs/keyring library, which is the same library aws-vault uses.

The README then lists what the standard AWS CLI leaves in the clear. The SSO ClientID and ClientSecret sit in ~/.aws/sso/cache/botocore-client-id-<region>.json. The SSO AccessToken sits in ~/.aws/sso/cache/<random>.json. And the profile access credentials sit in ~/.aws/cli/cache/<random>.json.

The argument is the important part. The README says that not only does the standard AWS CLI tool expose the temporary AWS access credentials to your IAM roles, but more importantly the SSO AccessToken, which can be used to fetch IAM credentials for any role you have been granted access to. So the access token in the cache is not a single role's credential, it is a key to every role you can reach. That is the argument for a tool that keeps the token in a keyring rather than in a JSON file in your home directory.

The Go dependency list backs the claim up. The keyring library is a direct dependency, and behind it sit the platform specific backends: wincred on Windows, go-libsecret for the freedesktop secret service on Linux, and dbus. The build defaults CGO_ENABLED to 0 so the binary stays static, and the Makefile notes that CGO must be enabled to get 1Password support on Linux, because that path produces a glibc-linked binary.

Three ways to pick a role, and tags to narrow them

The selection surface is where the daily friction lives, and the tool attacks it from three directions.

The first is the environment. Selecting a role via $AWS_PROFILE is the familiar path, and it means that a script or a Makefile target can select a role without any special support from this tool at all.

The second is the command line, with auto-completion. The Go dependency list shows how that is built: kong provides the command line parser, kongplete and complete provide the completion support, go-prompt provides the interactive prompt, and promptui provides the selection widgets. The result is that the set of roles you can assume is discovered from the Identity Center API and offered to you, rather than typed from memory.

The third is interactive search, where you filter a list rather than navigate a tree. And the filter is not only text. The tool can select roles based on user-defined tags, which you configure, and on auto-discovered tags, which it reads from the accounts themselves. That is a meaningful distinction in a large organisation, because auto-discovered tags are the only ones that stay correct without anyone maintaining them.

Around that there are the quality of life features the README lists. You can see how much longer your STS credentials remain valid for, which removes the most common cause of a script failing halfway through. There is a guided setup to configure aws-sso the first time you run it. There is advanced configuration for adjusting prompt colours, which sounds trivial and is not when you use a tool many times a day, and for generating named profiles via templates. And there is support for multiple active AWS Web Console sessions, so you can be signed in to several accounts in the browser at once.

The result is that a role in Identity Center is not a single string in a config file but an object with metadata, which is what makes the tag-based filtering possible in the first place.

A small server for handing credentials to containers

The one feature here that goes beyond the terminal is the ECS server, and it is unusual enough to deserve its own look.

The README says the tool supports sharing credentials via the AWS ECS Task IAM Role for containerised services. The repository's Dockerfile is the server rather than the client, and it says so in the entrypoint: the image runs ./aws-sso ecs server --docker.

The image is a two stage Alpine build. The builder stage uses golang:1.27-alpine with git, gcc, musl-dev and make, and runs make to produce the binary. The final stage is alpine:latest with curl added, and the built binary is copied in as /app/aws-sso.

The port is 4144, and the health check is written with a small piece of care:

HEALTHCHECK --interval=1s --timeout=2s --start-period=1s --retries=90 \
  CMD curl -fsk https://localhost:4144/healthcheck || curl -fs http://localhost:4144/healthcheck || exit 1
ENTRYPOINT ["./aws-sso", "ecs", "server", "--docker"]

The comment above it explains the logic. The server listens over HTTPS when an SSL cert and key are configured, so the health check tries TLS first and falls back to plaintext, and the -k flag is described as safe because this only ever talks to the loopback interface inside the container. The one second interval with up to 90 retries is a fast start-up probe, which suggests the server is expected to be ready quickly after the container starts.

This is the part of the project that changes the threat model. A credential helper on your laptop protects a token on your disk. A credential server that a task definition points at turns that into a service with a network endpoint, a lifecycle and a place where the role mapping lives.

One binary, no runtime dependencies, and a docs site

The distribution story is simple on purpose. The README says the tool is written in GoLang, so you only need to install a single binary with no dependencies, and that official prebuilt binaries are provided for Linux on amd64 and arm64, MacOS on amd64 and arm64, and Windows on amd64 and 386. Other operating systems supported by Go, including the BSDs, may work when building from source but may not be covered by release CI and testing.

That last caveat is worth noting. A binary that is not covered by the release pipeline is a binary you have to test yourself, and the README is honest that the coverage stops at the listed platforms.

The build is orchestrated by a Makefile that carries the version metadata. The project version is 2.4.0 in the Makefile, the licence string is GPLv3, and the linker flags stamp the version, the delta line count, the build timestamp, the git tag and the commit id into the binary. The module path is github.com/synfinatic/aws-sso-cli and the go.mod requires Go 1.26.4.

The documentation is a MkDocs site published from the repository, with a Dockerfile.mkdocs and Dockerfile.package beside the main Dockerfile, and the release workflow publishes the docs and builds the release binaries. The README links to the documentation, to a demos page, and to the changelog.

For the configuration itself, the tool uses koanf for configuration loading and goccy/go-yaml for YAML parsing, with sprig for templating, which is what makes the named profile templates and the tag driven filtering possible in the first place.

The Identity Center requirement is the boundary

There is one requirement that decides whether this tool applies to you at all, and the README states it directly: AWS SSO CLI requires your AWS accounts to be set up with AWS IAM Identity Center, which was previously known as AWS Single Sign-On. If your organisation is using the older SAML integration, typically with multiple tiles in OneLogin or Okta, then this will not work for you.

That is a hard boundary rather than a caveat. A SAML setup gives you a portal of applications and a role per application, and the roles are usually described in the identity provider rather than being enumerable in the way this tool needs. Identity Center gives you an account and permission set structure that the tool can enumerate, auto-complete and tag. If your organisation is still on SAML, this is the wrong tool, and no amount of configuration will change that.

The other boundary is the licence. The project is GPL-3.0, and the README badge and the Makefile both say GPLv3. For most organisations using the tool internally that is not an issue. If you plan to modify the source and ship the result inside a closed product, the copyleft obligation is a real consideration, and the sensible move is to read the LICENSE.md file in the repository.

One more constraint is worth repeating because it is easy to get wrong. The tool assumes the accounts are enrolled in Identity Center and that the role set is discoverable, and the README does not document a mode for static access keys. The comparison it draws with aws-vault is about shared philosophy, not about feature parity in credential types.

On cadence, the project is active. Versions 2.3.0, 2.3.1 and 2.3.2 were published in June and July 2026, and the last push was on 2026-10-06, with the Makefile already carrying a 2.4.0 version, which suggests the next release is close.

Editorial conclusion

Adopt AWS SSO CLI if your organisation runs many AWS accounts through IAM Identity Center and you want the SSO access token and the temporary credentials kept in an encrypted keyring rather than in the AWS CLI's plain JSON cache, or if your containerised services need a way to obtain role credentials. Do not adopt it if your identity provider is still the older SAML integration, which the README says it will not work with. Before you deploy, confirm every account is enrolled in IAM Identity Center, decide which keyring backend your platform provides, and read the migration notes for users of the standard aws configure sso flow.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. synfinatic/aws-sso-cli on GitHub