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:
- 50+ top-level commands
- ~1400 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!
- Syntax and output highlighting
- Customizable shortcuts
- Contextual help
SAWS is available for Mac, *nix, and
Windows.
Index¶
Features¶
Installation and Tests¶
Syntax and Output Highlighting¶
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.
Configuring Resource Completion¶
You can control which resources are loaded on startup and are available
for interactive completion by updating your ~/.sawsrc file:
# AWS resources to refresh
refresh_instance_ids = True
refresh_instance_tags = True
refresh_bucket_names = True
Once initially loaded, resources are cached locally to allow for faster
loading. To refresh the cache, use the F5 key.
Customizable Shortcuts¶
The ~/.sawsrc 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 ~/.sawsrc 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)
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:
F2toggles output syntax highlightingF3toggles fuzzy completion of AWS resources and shortcutsF4toggles completion of shortcutsF5refreshes resources for auto-completionF9displays the contextual web docsF10orcontrol dexitsSAWS
Windows Support¶
SAWS is developed under Mac OS X Yosemite and Ubuntu 14.04 LTS and
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
Once installed, run the following command to start SAWS:
$ saws
Configuring AWS Credentials¶
Configure your credentials with the AWS CLI:
$ aws configure
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
Pypy3 is not supported due to lack of support from boto.
Supported Platforms¶
- Mac OS X
- *nix (Tested on Ubuntu 14.04 LTS)
- Windows 7
- Windows 10
Developer Installation¶
$ git clone https://github.com/donnemartin/saws.git
$ pip install -e .
$ pip install -r requirements-dev.txt
Unit Tests and Code Coverage¶
Code coverage details are available on Codecov.
Run unit tests in your active Python environment:
$ python tests/run_tests.py
Run unit tests with tox on multiple Python environments:
$ tox
Documentation¶
Documentation is available on Readthedocs.org.
Run the following to build the docs:
$ cd docs
$ make html
Contributing¶
Contributions are welcome!
Review the Contributing Guidelines for details on how to:
- Submit issues
- Submit pull requests
Credits¶
- AWS CLI by
AWS for powering
SAWSunder the hood - Python Prompt
Toolkit
by jonathanslenders for
simplifying the creation of
SAWS - Wharfee by
j-bennet for inspiring the creation
of
SAWSand for some handy utility functions
Contact Info¶
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
License¶
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.