SAWS

Motivation

AWS CLI

Although the AWS CLI is a great resource to manage your AWS-powered services, it's tough to remember usage of:

• 70+ top-level commands
• 2000+ subcommands
• Countless command-specific options
• Resources such as instance tags and buckets

SAWS: A Supercharged AWS CLI

SAWS aims to supercharge the AWS CLI with features focusing on:

• Improving ease-of-use
• Increasing productivity

Under the hood, SAWS is powered by the AWS CLI and supports the same commands and command structure.

SAWS and AWS CLI Usage:

aws <command> <subcommand> [parameters] [options]

SAWS features:

• Auto-completion of:
  • Commands
  • Subcommands
  • Options
• Auto-completion of resources:
  • Bucket names
  • Instance ids
  • Instance tags
  • More coming soon!
• Customizable shortcuts
• Fuzzy completion of resources and shortcuts
• Fish-style auto-suggestions
• Syntax and output highlighting
• Execution of shell commands
• Command history
• Contextual help
• Toolbar options

SAWS is available for Mac, Linux, Unix, and Windows.

Index

Features

• Syntax and Output Highlighting
• Auto-Completion of Commands, Subcommands, and Options
• Auto-Completion of AWS Resources
  • S3 Buckets
  • EC2 Instance Ids
  • EC2 Instance Tags
  • TODO: Add More Resources
• Customizable Shortcuts
• Fuzzy Resource and Shortcut Completion
• Fish-Style Auto-Suggestions
• Executing Shell Commands
• Command History
• Contextual Help
  • Contextual Command Line Help
  • Contextual Web Docs
• Toolbar Options
• Windows Support

Installation and Tests

• Installation
  • Pip Installation
  • Virtual Environment and Docker Installation
  • AWS Credentials and Named Profiles
  • Supported Python Versions
  • Supported Platforms
• Developer Installation
  • Continuous Integration
  • Dependencies Management
  • Unit Tests and Code Coverage
  • Documentation

Misc

• Contributing
• Credits
• Contact Info
• License

Syntax and Output Highlighting

You can control which theme to load for syntax highlighting by updating your ~/.sawsrc file:

# Visual theme. Possible values: manni, igor, xcode, vim, autumn, vs, rrt,
# native, perldoc, borland, tango, emacs, friendly, monokai, paraiso-dark,
# colorful, murphy, bw, pastie, paraiso-light, trac, default, fruity
theme = vim

Auto-Completion of Commands, Subcommands, and Options

SAWS provides smart autocompletion as you type. Entering the following command will interactively list and auto-complete all subcommands specific only to ec2:

aws ec2

Auto-Completion of AWS Resources

In addition to the default commands, subcommands, and options the AWS CLI provides, SAWS supports auto-completion of your AWS resources. Currently, bucket names, instance ids, and instance tags are included, with additional support for more resources under development.

S3 Buckets

Option for s3api:

--bucket

Sample Usage:

aws s3api get-bucket-acl --bucket

Syntax for s3:

s3://

Sample Usage:

aws s3 ls s3://

Note: The example below demonstrates the use of fuzzy resource completion:

EC2 Instance Ids

Option for ec2:

--instance-ids

Sample Usage:

aws ec2 describe-instances --instance-ids
aws ec2 ls --instance-ids

Note: The ls command demonstrates the use of customizable shortcuts:

EC2 Instance Tags

Option for ec2:

--ec2-tag-key
--ec2-tag-value

Sample Usage:

aws ec2 ls --ec2-tag-key
aws ec2 ls --ec2-tag-value

Tags support wildcards with the * character.

Note: ls, --ec2-tag-value, and --ec2-tag-key demonstrate the use of customizable shortcuts:

TODO: Add More Resources

Feel free to submit an issue or a pull request if you'd like support for additional resources.

Customizable Shortcuts

The ~/.saws.shortcuts file contains shortcuts that you can modify. It comes pre-populated with several handy shortcuts out of the box. You can combine shortcuts with fuzzy completion for even less keystrokes. Below are a few examples.

List all EC2 instances:

aws ec2 ls

List all running EC2 instances:

aws ec2 ls --ec2-state running  # fuzzy shortcut: aws ecstate

List all EC2 instances with a matching tag (supports wildcards *):

aws ec2 ls --ec2-tag-key    # fuzzy shortcut: aws ectagk
aws ec2 ls --ec2-tag-value  # fuzzy shortcut: aws ectagv

List EC2 instance with matching id:

aws ec2 ls --instance-ids  # fuzzy shortcut: aws eclsi

List all DynamoDB tables:

aws dynamodb ls  # fuzzy shortcut: aws dls

List all EMR clusters:

aws emr ls  # fuzzy shortcut: aws emls

Add/remove/modify shortcuts in your ~/.saws.shortcuts file to suit your needs.

Feel free to submit:

• An issue to request additional shortcuts
• A pull request if you'd like to share your shortcuts (see contributing guidelines)

Fuzzy Resource and Shortcut Completion

To toggle fuzzy completion of AWS resources and shortcuts, use F3 key.

Sample fuzzy shortcuts to start and stop EC2 instances:

aws ecstop
aws ecstart

Note: Fuzzy completion currently only works with AWS resources and shortcuts.

Fish-Style Auto-Suggestions

SAWS supports Fish-style auto-suggestions. Use the right arrow key to complete a suggestion.

Executing Shell Commands

SAWS allows you to execute shell commands from the saws> prompt.

Command History

SAWS keeps track of commands you enter and stores them in ~/.saws-history. Use the up and down arrow keys to cycle through the command history.

Contextual Help

SAWS supports contextual command line help and contextual web docs.

Contextual Command Line Help

The help command is powered by the AWS CLI and outputs help within the command line.

Usage:

aws <command> <subcommand> help

Contextual Web Docs

Sometimes you're not quite sure what specific command/subcommand/option combination you need to use. In such cases, browsing through several combinations with the help command line is cumbersome versus browsing the online AWS CLI docs through a web browser.

SAWS supports contextual web docs with the docs command or the F9 key. SAWS will display the web docs specific to the currently entered command and subcommand.

Usage:

aws <command> <subcommand> docs

Toolbar Options

SAWS supports a number of toolbar options:

• F2 toggles output syntax highlighting
• F3 toggles fuzzy completion of AWS resources and shortcuts
• F4 toggles completion of shortcuts
• F5 refreshes resources for auto-completion
• F9 displays the contextual web docs
• F10 or control d exits SAWS

Windows Support

SAWS has been tested on Windows 7 and Windows 10.

On Windows, the .sawsrc file can be found in %userprofile%. For example:

C:\Users\dmartin\.sawsrc

Although you can use the standard Windows command prompt, you'll probably have a better experience with eit