Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here


A supercharged AWS command line interface (CLI).

Subscribe to updates I use saws

Statistics on saws

Number of watchers on Github 3542
Number of open issues 23
Average time to close an issue 10 days
Main language Python
Average time to merge a PR 1 day
Open pull requests 5+
Closed pull requests 2+
Last commit almost 2 years ago
Repo Created over 4 years ago
Repo Last Updated almost 2 years ago
Size 3.61 MB
Organization / Authordonnemartin
Latest Release0.4.2
Page Updated
Do you use saws? Leave a review!
View open issues (23)
View saws activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating saws for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)


Build Status Documentation Status Dependency Status

PyPI version PyPI License



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



Installation and Tests


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:


Sample Usage:

aws s3api get-bucket-acl --bucket

Syntax for s3:


Sample Usage:

aws s3 ls s3://

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

EC2 Instance Ids

Option for ec2:


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:


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.


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.


aws <command> <subcommand> docs

Toolbar Options

SAWS supports a number of toolbar options:

Windows Support

SAWS has been tested on Windows 7 and Windows 10.

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


Although you can use the standard Windows command prompt, you'll probably have a better experience with either cmder or conemu.


Pip Installation

PyPI version PyPI

SAWS is hosted on PyPI. The following command will install SAWS along with dependencies such as the AWS CLI:

$ pip install saws

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

$ pip install git+

If you are not installing in a virtualenv, run with sudo:

$ sudo pip install saws

Once installed, start SAWS:

$ saws

Virtual Environment and Docker Installation

It is recommended that you install Python packages in a virtualenv to avoid potential issues with dependencies or permissions.

To view SAWS virtualenv and Docker installation instructions, click here.

Mac OS X 10.11 El Capitan Users

There is a known issue with Apple and its included python package dependencies (more info at 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

AWS Credentials and Named Profiles

Configure your credentials with the AWS CLI:

$ aws configure

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

$ export AWS_DEFAULT_PROFILE=user1
$ saws

Or as a one-liner:


Windows users can run the following commands:

> saws

Command line options for starting SAWS with a specific profile are under development. For more details on how to install and configure the AWS CLI, refer to the following documentation.

Supported Python Versions

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

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

Pypy3 is not supported due to lack of support from boto.

Supported Platforms

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

Developer Installation

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

$ git clone
$ pip install -e .
$ pip install -r requirements-dev.txt
$ saws

Continuous Integration

Build Status

Continuous integration details are available on Travis CI.

Dependencies Management

Dependency Status

Dependencies management details are available on Gemnasium.

Unit Tests and Code Coverage

Run unit tests in your active Python environment:

$ python tests/

Run unit tests with tox on multiple Python environments:

$ tox


Documentation Status

Source code documentation is available on

Run the following to build the docs:

$ scripts/


Contributions are welcome!

Review the Contributing Guidelines for details on how to:

  • Submit issues
  • Submit pull requests


Contact Info

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


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 Martin

Licensed 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

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
limitations under the License.
saws open issues Ask a question     (View All Issues)
  • almost 4 years Use XDG config location
  • almost 4 years Support for setting env vars witin saws
  • about 4 years Support for automatically updating credentials from Third-Party SAML Solution Providers
  • about 4 years json highlighting breaks variable capturing.
  • about 4 years Homebrew installation
  • over 4 years Autocomplete ecs task definitions
  • over 4 years SAWS Caching credentials? Leading to conflict.
  • over 4 years auto-complete for AWS resource not being populated
  • over 4 years UnicodeDecodeError: 'ascii' codec can't decode byte
  • over 4 years Command History Improvement
  • over 4 years Publish docker image on DockerHub
  • over 4 years Add option to count results
  • over 4 years Add option to choose fields to be displayed
  • over 4 years Support MFA
  • over 4 years Refactor resource and command options completions code to simplify adding additional resources/options.
  • over 4 years Ability to specify endpoint url in config
  • over 4 years Scan for resources in the background
  • over 4 years Add option to customise prompt
  • over 4 years Improve output highlighting
  • over 4 years Support for --region and --profile
saws open pull requests (View All Pulls)
  • Upgrade to prompt_toolkit 0.59.
  • Upgrade to prompt-toolkit 1.0.0
  • Use alpine and build docker image from source
  • If using saws from bash, then use the same shell when invoking commands.
  • [WIP] Upgrade to prompt_toolkit 2.0
saws list of languages used
saws latest release notes


0.4.2 (2017-04-08)

Bug Fixes

  • #90 - Fix Sphinx document generation issues.


  • Update list of commands.
  • #92 - Update feed_key to feed and process_keys forprompt-toolkit` v1.0.1+.


0.4.1 (2015-05-31)

Bug Fixes

  • #83 - Update to prompt-toolkit 1.0.0, which includes a number of performance improvements (especially noticeable on Windows) and bug fixes.


  • #75, #76 - Fix groff install and follow Dockerfile best practices.
  • #85 - Update packaging dependencies based on semantic versioning.
  • #86 - Fix linter issues regarding imports.
  • Update list of commands.
    • Add install from SOURCE.
    • Add note about OS X 10.11 pip issue (now also in README).
    • Update intro.
  • Update link to style guide in CONTRIBUTING.


0.4.0 (2015-12-08)


  • Implemented #67: Add Fish-style auto suggestions.

Bug Fixes

  • Fixed #71: Disable color output for shell commands.
  • Fixed #72: Exiting with F10 does not clear the menu bar.


  • Updated list of commands.
  • Updated repo README.
    • Added auto suggestions.
  • Fixed #66: Removed docs/build from source repo.
Other projects in Python