id = "aws-sso-cli"
name = "AWS SSO CLI"
homepage = "https://synfinatic.github.io/aws-sso-cli/"
description = "Securely manage AWS API credentials using AWS SSO"
executables = ["aws-sso"]

[dotfiles]

# The official configuration guide documents the current XDG location
# ~/.config/aws-sso/config.yaml and the legacy ~/.aws-sso/config.yaml. The
# application directory also contains cached credential/state material, so
# both supported directories are retained as secret content.
# https://synfinatic.github.io/aws-sso-cli/latest/config/
paths = [
  "~/.aws-sso/config.yaml",
  "[configHome]/aws-sso/config.yaml",
]
secret = [
  "~/.aws-sso/",
  "[configHome]/aws-sso/",
]

[commands]
format = 1
label = "AWS SSO CLI"
description = "Log in to IAM Identity Center, run commands or open the console with a role's credentials, and list roles. Process, ECS, setup and cache commands are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = false }

[[commands.source]]
id = "ref"
kind = "manual"
url = "https://github.com/synfinatic/aws-sso-cli/blob/main/docs/commands.md"
revision = "2026-10-27"
evidence = '''
* `--sso <name>`, `-S` -- Specify non-default AWS SSO instance to use (`$AWS_SSO`)
* `--level <level>`, `-L` -- Change default log level: [error|warn|info|debug|trace]
'''

[[commands.field]]
id = "sso"
label = "SSO instance"
description = "Name of a non-default SSO instance."
type = "string"
option = ["--sso", "-S"]
sources = ["ref"]

[[commands.field]]
id = "level"
label = "Log level"
type = "enum"
option = ["--level", "-L"]
choices = [{ value = "error", label = "Error" }, { value = "warn", label = "Warn" }, { value = "info", label = "Info" }, { value = "debug", label = "Debug" }, { value = "trace", label = "Trace" }]
sources = ["ref"]

[[commands.group]]
id = "basic"
label = "Basic"
fields = ["sso", "level"]

[[commands.subcommand]]
path = ["login"]
label = "Log in"

[[commands.subcommand.source]]
id = "ref"
kind = "manual"
url = "https://github.com/synfinatic/aws-sso-cli/blob/main/docs/commands.md"
revision = "2026-10-27"
evidence = '''
* `--url-action`, `-u` -- How to handle URLs for your SSO provider
* `--threads <int>` -- Number of threads to use with AWS (default: 5)
* `--force`, `-f` -- End the current SSO session and start a new one, resetting the
'''

[[commands.subcommand.field]]
id = "url_action"
label = "URL action"
description = "How to handle the SSO login URL."
type = "string"
option = ["--url-action", "-u"]
sources = ["ref"]

[[commands.subcommand.field]]
id = "threads"
label = "Threads"
type = "integer"
option = ["--threads"]
sources = ["ref"]

[[commands.subcommand.field]]
id = "force"
label = "Force a new session"
description = "Ends the current SSO session and starts a new one."
type = "boolean"
option = ["--force", "-f"]
sources = ["ref"]

[[commands.subcommand.task]]
id = "login"
label = "Log in"
fields = ["url_action", "force"]
required = []

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["url_action", "force", "threads"]

[[commands.subcommand]]
path = ["exec"]
label = "Run a command with a role"

[[commands.subcommand.source]]
id = "ref"
kind = "manual"
url = "https://github.com/synfinatic/aws-sso-cli/blob/main/docs/commands.md"
revision = "2026-10-27"
evidence = '''
* `--arn <arn>`, `-a` -- ARN of role to assume (`$AWS_SSO_ROLE_ARN`)
* `--account <account>`, `-A` -- AWS AccountID of role to assume (`$AWS_SSO_ACCOUNT_ID`)
* `--role <role>`, `-R` -- Name of AWS Role to assume (`$AWS_SSO_ROLE_NAME`)
* `--profile <profile>`, `-p` -- Name of AWS Profile to assume
* `--no-region` -- Do not set the [AWS_DEFAULT_REGION](config.md#defaultregion) from config.yaml
* `--overwrite-env`, `-O` -- Force overwriting existing `AWS_*` environment variables
* `--sts-refresh` -- Force refresh of STS Token Credentials
Arguments: `[<command>] [<args> ...]`
'''

[[commands.subcommand.field]]
id = "profile"
label = "Profile"
type = "string"
option = ["--profile", "-p"]
sources = ["ref"]

[[commands.subcommand.field]]
id = "arn"
label = "Role ARN"
type = "string"
option = ["--arn", "-a"]
sources = ["ref"]

[[commands.subcommand.field]]
id = "account"
label = "Account ID"
type = "string"
option = ["--account", "-A"]
sources = ["ref"]

[[commands.subcommand.field]]
id = "role"
label = "Role name"
type = "string"
option = ["--role", "-R"]
sources = ["ref"]

[[commands.subcommand.field]]
id = "no_region"
label = "Do not set default region"
type = "boolean"
option = ["--no-region"]
sources = ["ref"]

[[commands.subcommand.field]]
id = "overwrite_env"
label = "Overwrite existing AWS_* variables"
type = "boolean"
option = ["--overwrite-env", "-O"]
effect = "overwrite"
sources = ["ref"]

[[commands.subcommand.field]]
id = "sts_refresh"
label = "Refresh STS credentials"
type = "boolean"
option = ["--sts-refresh"]
sources = ["ref"]

[[commands.subcommand.field]]
id = "command"
label = "Command and arguments"
description = "Leave empty to start an interactive shell."
type = "string"
position = 0
multiple = true
sources = ["ref"]

[[commands.subcommand.task]]
id = "profile_shell"
label = "Shell with a profile"
fields = ["profile", "command"]
required = ["profile"]

[[commands.subcommand.task]]
id = "role_command"
label = "Command with an account and role"
fields = ["account", "role", "command"]
required = ["account", "role"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["profile", "account", "role", "command"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["arn", "no_region", "overwrite_env", "sts_refresh"]

[[commands.subcommand]]
path = ["console"]
label = "Open the AWS console"

[[commands.subcommand.source]]
id = "ref"
kind = "manual"
url = "https://github.com/synfinatic/aws-sso-cli/blob/main/docs/commands.md"
revision = "2026-10-27"
evidence = '''
* `--duration <minutes>`, `-d` -- AWS Session duration in minutes (default 60)
* `--prompt`, `-P` -- Force interactive prompt to select role
* `--region <region>`, `-r` -- Specify the `$AWS_DEFAULT_REGION` to use
* `--arn <arn>`, `-a` -- ARN of role to assume (`$AWS_SSO_ROLE_ARN`)
* `--account <account>`, `-A` -- AWS AccountID of role to assume (`$AWS_SSO_ACCOUNT_ID`)
* `--role <role>`, `-R` -- Name of AWS Role to assume (requires `--account`) (`$AWS_SSO_ROLE_NAME`)
* `--profile <profile>`, `-p` -- Name of AWS Profile to assume
* `--url-action`, `-u` -- How to handle URLs for your SSO provider
'''

[[commands.subcommand.field]]
id = "profile"
label = "Profile"
type = "string"
option = ["--profile", "-p"]
sources = ["ref"]

[[commands.subcommand.field]]
id = "prompt"
label = "Prompt to select a role"
type = "boolean"
option = ["--prompt", "-P"]
sources = ["ref"]

[[commands.subcommand.field]]
id = "account"
label = "Account ID"
type = "string"
option = ["--account", "-A"]
sources = ["ref"]

[[commands.subcommand.field]]
id = "role"
label = "Role name"
description = "Requires an account ID."
type = "string"
option = ["--role", "-R"]
sources = ["ref"]

[[commands.subcommand.field]]
id = "arn"
label = "Role ARN"
type = "string"
option = ["--arn", "-a"]
sources = ["ref"]

[[commands.subcommand.field]]
id = "region"
label = "Region"
type = "string"
option = ["--region", "-r"]
sources = ["ref"]

[[commands.subcommand.field]]
id = "duration"
label = "Session duration (minutes)"
type = "integer"
option = ["--duration", "-d"]
sources = ["ref"]

[[commands.subcommand.field]]
id = "url_action"
label = "URL action"
description = "What to do with the generated URL."
type = "string"
option = ["--url-action", "-u"]
sources = ["ref"]

[[commands.subcommand.task]]
id = "profile_console"
label = "Console for a profile"
fields = ["profile", "region", "duration", "url_action"]
required = ["profile"]

[[commands.subcommand.task]]
id = "pick_console"
label = "Console, choose a role interactively"
set = { prompt = [true] }
fields = ["prompt", "region", "url_action"]
required = []

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["profile", "prompt", "region", "url_action"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["account", "role", "arn", "duration"]

[[commands.subcommand]]
path = ["list"]
label = "List roles"

[[commands.subcommand.source]]
id = "ref"
kind = "manual"
url = "https://github.com/synfinatic/aws-sso-cli/blob/main/docs/commands.md"
revision = "2026-10-27"
evidence = '''
* `--list-fields`, `-f` -- List the available fields to print
* `--prefix <FieldName>=<Prefix>`, `-P` -- Filter results by the given field
* `--csv` -- Generate results in CSV format
* `--sort <FieldName>`, `-s` -- Sort results by the provided field name
* `--reverse` -- Reverse the sort order
Arguments: `[<field> ...]`
'''

[[commands.subcommand.field]]
id = "fields"
label = "Fields to show"
description = "Field names such as AccountIdPad, AccountAlias, RoleName, Expires."
type = "string"
position = 0
multiple = true
sources = ["ref"]

[[commands.subcommand.field]]
id = "list_fields"
label = "List available fields"
type = "boolean"
option = ["--list-fields", "-f"]
sources = ["ref"]

[[commands.subcommand.field]]
id = "prefix"
label = "Filter by field prefix"
description = "FieldName=Prefix"
type = "string"
option = ["--prefix", "-P"]
sources = ["ref"]

[[commands.subcommand.field]]
id = "csv"
label = "CSV output"
type = "boolean"
option = ["--csv"]
sources = ["ref"]

[[commands.subcommand.field]]
id = "sort"
label = "Sort by field"
type = "string"
option = ["--sort", "-s"]
sources = ["ref"]

[[commands.subcommand.field]]
id = "reverse"
label = "Reverse sort"
type = "boolean"
option = ["--reverse"]
sources = ["ref"]

[[commands.subcommand.task]]
id = "list"
label = "List roles"
fields = ["fields", "sort", "reverse"]
required = []

[[commands.subcommand.task]]
id = "csv"
label = "Export roles as CSV"
set = { csv = [true] }
fields = ["fields", "csv", "prefix", "sort"]
required = []

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["fields", "sort", "reverse", "csv"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["prefix", "list_fields"]