SAWS — saws 0.1.0 documentation

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¶

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.

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)

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.

Executing Shell Commands¶

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

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

I highly recommend installing Python packages in a virtualenv to avoid any issues with dependencies or permissions.

Once installed, run the following command to start SAWS:

$ saws

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.

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 (Tested on OS X 10.10)
*nix (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:

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

Continuous Integration¶

Continuous integration details are available on Travis CI.

Dependencies Management¶

Dependencies management details are available on Gemnasium.

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¶

Source code documentation is available on Readthedocs.org.

Run the following to build the docs:

$ scripts/update_docs.sh

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 SAWS under the hood
Python Prompt Toolkit by jonathanslenders for simplifying the creation of SAWS
Wharfee by j-bennet for inspiring the creation of SAWS and 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.

SAWS¶

Motivation¶

AWS CLI¶

SAWS: A Supercharged AWS CLI¶

Index¶

Features¶

Installation and Tests¶

Misc¶

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¶

Configuring Resource Completion¶

Customizable Shortcuts¶

Fuzzy Resource and Shortcut Completion¶

Executing Shell Commands¶

Contextual Help¶

Contextual Command Line Help¶

Contextual Web Docs¶

Installation¶

Pip Installation¶

Configuring AWS Credentials¶

Supported Python Versions¶

Supported Platforms¶

Developer Installation¶

Continuous Integration¶

Dependencies Management¶

Unit Tests and Code Coverage¶

Documentation¶

Contributing¶

Credits¶

Contact Info¶

License¶

Table Of Contents

Related Topics

This Page