.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "AWSKEYRING" "5" "November 2022" "" ""
.
.SH "NAME"
\fBAwskeyring\fR \- is a small tool to manage AWS account keys in the macOS Keychain
.
.SH "SYNOPSIS"
awskeyring COMMAND [ACCOUNT|ROLE] [OPTIONS]
.
.P
awskeyring help COMMAND
.
.SH "DESCRIPTION"
The Awskeyring utility stores and manages AWS access keys and provides the facility to generate access tokens with combinations of assumed roles and multi\-factor\-authentication codes\. It includes autocompletion features and multiple validation checks for input parsing\. It also includes the ability for the AWS CLI to call it directly to provide authentication\.
.
.P
The commands are as follows:
.
.TP
\-\-version, \-v:
.
.IP
Prints the version
.
.br
.
.IP
\-r, \-\-no\-remote: Do not validate with remote api\.
.
.TP
add ACCOUNT:
.
.IP
Adds an ACCOUNT to the keyring
.
.br
.
.IP
\-k, \-\-key=KEY: AWS account key id\.
.
.br
\-m, \-\-mfa=MFA: AWS virtual mfa arn\.
.
.br
\-r, \-\-no\-remote: Do not validate with remote api\.
.
.br
\-s, \-\-secret=SECRET: AWS account secret\.
.
.TP
add\-role ROLE:
.
.IP
Adds a ROLE to the keyring
.
.br
.
.IP
\-a, \-\-arn=ARN: AWS role arn\.
.
.TP
awskeyring console ACCOUNT:
.
.IP
Open the AWS Console for the ACCOUNT
.
.br
.
.IP
\-b, \-\-browser=BROWSER: Specify an alternative browser\.
.
.br
\-o, \-\-no\-open: Do not open the url\.
.
.br
\-n, \-\-no\-token: Do not use saved token\.
.
.br
\-p, \-\-path=PATH: The service PATH to open\.
.
.TP
env ACCOUNT:
.
.IP
Outputs bourne shell environment exports for an ACCOUNT
.
.br
.
.IP
\-f, \-\-force: Force output to a tty\.
.
.br
\-n, \-\-no\-token: Do not use saved token\.
.
.br
\-u, \-\-unset, \-\-no\-unset: Unset environment variables\.
.
.TP
exec ACCOUNT command\.\.\.:
.
.IP
Execute a COMMAND with the environment set for an ACCOUNT
.
.br
.
.IP
\-b, \-\-no\-bundle: Unset Bundler environment variables\.
.
.br
\-n, \-\-no\-token: Do not use saved token\.
.
.TP
help [COMMAND]:
.
.IP
Describe available commands or one specific command
.
.TP
import:
.
.IP
Import an ACCOUNT to the keyring from ~/\.aws/credentials
.
.br
.
.IP
\-r, \-\-no\-remote: Do not validate with remote api\.
.
.TP
initialise:
.
.IP
Initialises a new KEYCHAIN
.
.br
.
.IP
\-n, \-\-keychain=KEYCHAIN: Name of KEYCHAIN to initialise\.
.
.TP
json ACCOUNT:
.
.IP
Outputs AWS CLI compatible JSON for an ACCOUNT
.
.br
.
.IP
\-f, \-\-force: Force output to a tty\.
.
.br
\-n, \-\-no\-token: Do not use saved token\.
.
.TP
list:
.
.IP
Prints a list of accounts in the keyring
.
.TP
list\-role:
.
.IP
Prints a list of roles in the keyring
.
.br
.
.IP
\-d, \-\-detail, \-\-no\-detail: Show more detail\.
.
.TP
remove ACCOUNT:
.
.IP
Removes an ACCOUNT from the keyring
.
.TP
remove\-role ROLE:
.
.IP
Removes a ROLE from the keyring
.
.TP
remove\-token ACCOUNT:
.
.IP
Removes a token for ACCOUNT from the keyring
.
.TP
rotate ACCOUNT:
.
.IP
Rotate access keys for an ACCOUNT
.
.TP
token ACCOUNT [ROLE] [CODE]:
.
.IP
Create an STS Token from a ROLE or an mfa CODE
.
.br
.
.IP
\-c, \-\-code=CODE: Virtual mfa CODE\.
.
.br
\-d, \-\-duration=DURATION: Session DURATION in seconds\.
.
.TP
update ACCOUNT:
.
.IP
Updates an ACCOUNT in the keyring
.
.br
.
.IP
\-k, \-\-key=KEY: AWS account key id\.
.
.br
\-r, \-\-no\-remote: Do not validate with remote api\.
.
.br
\-s, \-\-secret=SECRET: AWS account secret\.
.
.SH "ENVIRONMENT"
The AWS_DEFAULT_REGION environment variable will be used for AWS API calls where specified or fall back to us\-east\-1 when not\.
.
.SH "EXIT STATUS"
The Awskeyring utility exits 0 on success, and >0 if an error occurs\.
.
.SH "EXAMPLES"
First you need to initialise your keychain to hold your AWS credentials\.
.
.IP "" 4
.
.nf

awskeyring initialise
.
.fi
.
.IP "" 0
.
.P
Then add your keys to it\.
.
.IP "" 4
.
.nf

awskeyring add personal\-aws
.
.fi
.
.IP "" 0
.
.P
Now your keys are stored safely in the macOS keychain\. To print environment variables run\.\.\.
.
.IP "" 4
.
.nf

awskeyring env personal\-aws
.
.fi
.
.IP "" 0
.
.P
To open the AWS Console (web page) with your default browser simply run\.\.\.
.
.IP "" 4
.
.nf

awskeyring console personal\-aws
.
.fi
.
.IP "" 0
.
.P
Autocomplete is enabled in your current shell with the following command\.\.\.
.
.IP "" 4
.
.nf

complete \-C /usr/local/bin/awskeyring awskeyring
.
.fi
.
.IP "" 0
.
.SH "CONFIGURATION"
A Configuration file is stored in the users home directory at \fB~/\.awskeyring\fR as a JSON formatted file\. Most of the fields have a default value except the awskeyring field\.
.
.IP "" 4
.
.nf

{
  "awskeyring": "awskeyring",
  "browser":    ["FireFox", "Google Chrome", "Safari"],
  "console":    ["ec2/v2", "cloudwatch", "iam"],
  "keyage":     90
}
.
.fi
.
.IP "" 0
.
.IP "1." 4
The first field is the Keychain that your keys will be saved in\.
.
.br

.
.IP "2." 4
A list of your browsers to use the console command with\.
.
.br

.
.IP "3." 4
The next is the list of AWS Console pages autocomplete will present\.
.
.br

.
.IP "4." 4
The last field is the warning threshold for key age\.
.
.IP "" 0
.
.SH "HISTORY"
The motivation of this application is to provide a local secure store of AWS credentials using specifically in the macOS Keychain, to have them easily accessed from the Terminal, and to provide useful functions like assuming roles and opening the AWS Console from the cli\. It then expanded to include autocomplete and a desire to have an almost complete test coverage to prevent regressions in its functionality\. For Enterprise environments there are better suited tools to use like HashiCorp Vault \fIhttps://vaultproject\.io/\fR\.
.
.SH "SECURITY"
If you believe you have found a security issue in Awskeyring, please responsibly disclose by contacting me at \fItristan\.morgan@servian\.com\fR\. Awskeyring is a Ruby script and as such Ruby is whitelisted to access your "awskeyring" keychain\. Use a strong password and keep the unlock time short\.
.
.SH "AUTHOR"
Tristan Morgan \fItristan\.morgan@servian\.com\fR is the maintainer of Awskeyring\.
.
.SH "CONTRIBUTORS"
.
.IP "\(bu" 4
Tristan tristanmorgan \fIhttps://github\.com/tristanmorgan\fR
.
.IP "\(bu" 4
Adam Sir AzySir \fIhttps://github\.com/AzySir\fR
.
.IP "\(bu" 4
Vito Giarrusso thtliife \fIhttps://github\.com/thtliife\fR
.
.IP "" 0
.
.SH "LICENSE"
The gem is available as open source under the terms of the MIT License \fIhttps://opensource\.org/licenses/MIT\fR\.