Repository files navigation

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

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

SAWS aims tosupercharge the AWS CLI with features focusing on:

• Improving ease-of-use
• Increasing productivity

Under the hood,SAWS ispowered by the AWS CLI and supports thesame commands andcommand structure.

SAWS andAWS 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, andWindows.

• 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
  • 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

• Contributing
• Credits
• Contact Info
• License

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, fruitytheme = vim

SAWS provides smart autocompletion as you type. Entering the following command will interactively list and auto-complete all subcommandsspecific only toec2:

aws ec2

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 resourcesunder development.

Option fors3api:

--bucket

Sample Usage:

aws s3api get-bucket-acl --bucket

Syntax fors3:

s3://

Sample Usage:

aws s3 ls s3://

Note: The example below demonstrates the use offuzzy resource completion:

Option forec2:

--instance-ids

Sample Usage:

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

Note: Thels command demonstrates the use ofcustomizable shortcuts:

Option forec2:

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

Sample Usage:

aws ec2 ls --ec2-tag-keyaws ec2 ls --ec2-tag-value

Tags support wildcards with the* character.

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

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

The~/.saws.shortcuts file contains shortcuts that you can modify. It comes pre-populated with severalhandy shortcuts out of the box. You can combine shortcuts withfuzzy 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 ectagkaws 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 (seecontributing guidelines)

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

Sample fuzzy shortcuts to start and stop EC2 instances:

aws ecstopaws ecstart

Note: Fuzzy completion currently only works with AWSresources andshortcuts.

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

SAWS allows you to execute shell commands from thesaws> prompt.

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.

SAWS supports contextual command linehelp and contextual webdocs.

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

Usage:

aws <command> <subcommand> help

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

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

Usage:

aws <command> <subcommand> docs

SAWS supports a number of toolbar options:

• F2 togglesoutput syntax highlighting
• F3 togglesfuzzy completion of AWS resources and shortcuts
• F4 togglescompletion of shortcuts
• F5 refreshesresources for auto-completion
• F9 displays thecontextual web docs
• F10 orcontrol d exitsSAWS

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 eithercmder orconemu.

SAWS is hosted onPyPI. The following command will installSAWS along with dependencies such as theAWS CLI:

$ pip install saws

You can also install the latestSAWS from GitHub source which can contain changes not yet pushed to PyPI:

$ pip install git+https://github.com/donnemartin/saws.git

If you are not installing in avirtualenv, run withsudo:

$ sudo pip install saws

Once installed, startSAWS:

$ saws

It is recommended that you install Python packages in avirtualenv to avoid potentialissues with dependencies or permissions.

To viewSAWSvirtualenv andDocker installation instructions, clickhere.

There is a known issue with Apple and its included python package dependencies (more info atpypa/pip#3165). We are investigating ways to fix this issue but in the meantime, to install saws, you can run:

$ sudo pip install saws --upgrade --ignore-installed six

Configure your credentials with the AWS CLI:

$ aws configure

If you'd like to use a specific named profile withSAWS, run the following commands on OS X, Linux, or Unix:

$ export AWS_DEFAULT_PROFILE=user1$ saws

Or as a one-liner:

$ AWS_DEFAULT_PROFILE=user1 saws

Windows users can run the following commands:

> set AWS_DEFAULT_PROFILE=user1> saws

Command line options for startingSAWS with a specific profile areunder development. For more details on how to install and configure the AWS CLI, refer to the followingdocumentation.

• Python 2.6
• Python 2.7
• Python 3.3
• Python 3.4
• Pypy

Light testing indicates thatSAWS also seems to be compatible with Python 3.5.

Pypy3 is not supported due tolack of support fromboto.

• Mac OS X
  • Tested on OS X 10.10
• Linux, Unix
  • Tested on Ubuntu 14.04 LTS
• Windows
  • Tested on Windows 7 and 10

If you're interested in contributing toSAWS, run the following commands:

$ git clone https://github.com/donnemartin/saws.git$ pip install -e .$ pip install -r requirements-dev.txt$ saws

Continuous integration details are available onTravis CI.

Dependencies management details are available onGemnasium.

Run unit tests in your active Python environment:

$ python tests/run_tests.py

Run unit tests withtox on multiple Python environments:

$ tox

Source code documentation is available onReadthedocs.org.

Run the following to build the docs:

$ scripts/update_docs.sh

Contributions are welcome!

Review theContributing Guidelines for details on how to:

• Submit issues
• Submit pull requests

• AWS CLI byAWS for poweringSAWS under the hood
• Python Prompt Toolkit byjonathanslenders for simplifying the creation ofSAWS
• Wharfee byj-bennet for inspiring the creation ofSAWS and for some handy utility functions

Feel free to contact me to discuss any issues, questions, or comments.

• Email:donne.martin@gmail.com
• Twitter:donne_martin
• GitHub:donnemartin
• LinkedIn:donnemartin
• Website:donnemartin.com

I am providing code and resources in this repository to you under an open source license. Because this is my personal repository, the license you receive to my code and resources is from me and not my employer (Facebook).

Copyright 2015 Donne MartinLicensed under the Apache License, Version 2.0 (the "License");you may not use this file except in compliance with the License.You may obtain a copy of the License at   http://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, softwaredistributed under the License is distributed on an "AS IS" BASIS,WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.See the License for the specific language governing permissions andlimitations under the License.