5.3k GitHub stars and counting — donnemartin/saws is a Python project TopGit is tracking across repositories on the platform. A supercharged AWS command line interface (CLI).
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
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 either cmder or conemu.
Installation
Pip Installation
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:
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 SAWSvirtualenv 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 https://github.com/pypa/pip/issues/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
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:
$ AWS_DEFAULT_PROFILE=user1 saws
Windows users can run the following commands:
> set AWS_DEFAULT_PROFILE=user1
> 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:
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
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed 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 and
limitations under the License.
No homepage URL was recorded for donnemartin/saws in TopGit's last sync. The README tab above frequently contains screenshots and demo links, or check the repository description on GitHub.
Is donnemartin/saws open source?
TopGit's metadata for donnemartin/saws does not record a license. Most public repositories on GitHub ARE open source, but the exact terms vary — verify by opening the LICENSE file directly.
What else is in the Developer Tools space?
donnemartin/saws is tracked by TopGit under the Developer Tools category, alongside 17 GitHub-tagged topics. Trending and Topics pages list peer repositories of comparable stars and language.
What is donnemartin/saws?
donnemartin/saws (donnemartin/saws) is a Python project on GitHub. From the project's own README: A supercharged AWS command line interface (CLI).
Where do I read more about donnemartin/saws?
This TopGit page is a snapshot — the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/donnemartin/saws is the definitive source.
Why is donnemartin/saws categorized under Developer Tools?
TopGit places donnemartin/saws in the Developer Tools category based on its GitHub topics and description (tagged: "aws", "aws-cli", "cli"). Categories are assigned from real repository metadata, not editorial guesswork.
Read full README in the tab above.
Curious whether saws is right for you?
Let ChatGPT, Claude, or Perplexity look into it — click below and see what AI actually says about saws.
/saws
