Skip to content

Commit 02395d8

Browse files
jameslsjamesls
committed
Add initial take at the README
1 parent 6cadb6c commit 02395d8

File tree

1 file changed

+253
-1
lines changed

1 file changed

+253
-1
lines changed

‎README.rst

Lines changed: 253 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,254 @@
1-
The AWS Shell
1+
AWS Shell - the interactive productivity booster for the AWS CLI
2+
================================================================
3+
4+
.. image:: https://aws-developer-blog-media.s3-us-west-2.amazonaws.com/cli/Super-Charge-Your-AWS-Command-Line-Experience-with-aws-shell/aws-shell-final.gif
5+
6+
7+
Installation
8+
============
9+
10+
You can install the AWS Shell using `pip`_::
11+
12+
$ pip install aws-shell
13+
14+
If you are not installing into a virtualenv you can run::
15+
16+
$ sudo pip install aws-shell
17+
18+
If you want to upgrade to the latest version of the AWS Shell,
19+
you can run::
20+
21+
$ pip install --upgrade aws-shell
22+
23+
You can also use this upgrade command whenever a new version of the AWS CLI is
24+
released that includes new services and API updates. You will then be
25+
able to use these new services and API updates in the AWS Shell.
26+
27+
Once you've installed the AWS Shell, you can now run::
28+
29+
$ aws-shell
30+
31+
To exit the shell, press ``Ctrl-D``.
32+
33+
Supported Python Versions
34+
-------------------------
35+
36+
The AWS Shell works on the same python versions supported by the AWS CLI:
37+
38+
* 2.6.5 and greater
39+
* 2.7.x and greater
40+
* 3.3.x and greater
41+
* 3.4.x and greater
42+
43+
44+
Configuration
245
=============
46+
47+
The AWS Shell uses the same configuration settings as the AWS CLI.
48+
If you've never used the AWS CLI before, the easiest way to get
49+
started is to run the ``configure`` command::
50+
51+
$ aws-shell
52+
aws> configure
53+
AWS Access Key ID [None]: your-access-key-id
54+
AWS Secret Access Key [None]: your-secret-access-key
55+
Default region name [None]: region-to-use (e.g us-west-2, us-west-1, etc).
56+
Default output format [None]:
57+
aws>
58+
59+
For more information about configure settings, see the
60+
`AWS CLI Getting Started Guide`_.
61+
62+
Basic Usage
63+
===========
64+
65+
The AWS Shell accepts the same commands as the AWS CLI, except you don't
66+
need to provide the ``aws`` prefix. For example, here are a few commands
67+
you can try::
68+
69+
70+
$ aws-shell
71+
aws> ec2 describe-regions
72+
{
73+
"Regions": [
74+
{
75+
"Endpoint": "ec2.eu-west-1.amazonaws.com",
76+
"RegionName": "eu-west-1"
77+
},
78+
...
79+
aws> s3 ls
80+
2015-12-07 15:03:34 bucket1
81+
2015-12-07 15:03:34 bucket2
82+
aws> dynamodb list-tables --output text
83+
TABLENAMES First
84+
TABLENAMES Second
85+
TABLENAMES Third
86+
87+
88+
Features
89+
========
90+
91+
Auto Completion of Commands and Options
92+
---------------------------------------
93+
94+
The AWS Shell provides auto completion of commands and
95+
options as you type.
96+
97+
98+
.. image:: https://cloud.githubusercontent.com/assets/368057/11824078/784a613e-a32c-11e5-8ac5-f1d1873cc643.png
99+
100+
101+
Shorthand Auto Completion
102+
-------------------------
103+
104+
The AWS Shell can also fill in an example of the
105+
shorthand syntax used for various AWS CLI options:
106+
107+
.. image:: https://cloud.githubusercontent.com/assets/368057/11823453/e95d85da-a328-11e5-8b8d-67566eccf9e3.png
108+
109+
110+
Server Side Auto Completion
111+
---------------------------
112+
113+
The AWS Shell also leverages `boto3`_, the AWS SDK for Python, to auto complete
114+
server side resources such as Amazon EC2 instance Ids, Amazon Dynamodb table
115+
names, AWS IAM user names, Amazon S3 bucket names, etc.
116+
117+
This feature is under active development. The list of supported resources
118+
continues to grow.
119+
120+
.. image:: https://cloud.githubusercontent.com/assets/368057/11824022/3648b4fc-a32c-11e5-8e18-92f028eb1cee.png
121+
122+
123+
Fuzzy Searching
124+
---------------
125+
126+
Every auto completion value supports fuzzy searching. This enables you to
127+
specify the commands, options, and values you want to run with even less
128+
typing. You can try typing:
129+
130+
* The first letter of each sub word: ``ec2 describe-reserved-instances-offerings``
131+
-> ``ec2 drio``
132+
* A little bit of each word: ``ec2 describe-instances`` -> ``ec2 descinst``
133+
* Any part of the command: ``dynamodb table`` -> Offers all commands that
134+
contain the subsequence ``table``.
135+
136+
137+
.. image:: https://cloud.githubusercontent.com/assets/368057/11823996/18e69d16-a32c-11e5-80a2-defbaa6a8a80.png
138+
139+
Inline Documentation
140+
--------------------
141+
142+
The AWS Shell will automatically pull up documentation as you type commands.
143+
It will show inline documentation for CLI options. There is also a separate
144+
documentation panel that will show documentation for the current command or
145+
option you are typing.
146+
147+
.. image:: https://cloud.githubusercontent.com/assets/368057/11823320/36ae9b04-a328-11e5-9661-81abfc0afe5a.png
148+
149+
150+
Fish-Style Auto Suggestions
151+
---------------------------
152+
153+
The AWS Shell supports Fish-style auto-suggestions. Use the right arrow key to
154+
complete a suggestion.
155+
156+
.. image:: https://cloud.githubusercontent.com/assets/368057/11822961/4bceff94-a326-11e5-87fa-c664e1e82be4.png
157+
158+
Command History
159+
---------------
160+
161+
The AWS Shell records the commands you run and writes them to
162+
``~/.aws/shell/history``. You can use the up and down arrow keys to scroll
163+
through your history.
164+
165+
.. image:: https://cloud.githubusercontent.com/assets/368057/11823211/b5851e9a-a327-11e5-877f-687dc1f90e27.png
166+
167+
Toolbar Options
168+
---------------
169+
170+
The AWS Shell has a bottom toolbar that provides several options:
171+
172+
* ``F2`` toggles between fuzzy and substring matching
173+
* ``F3`` toggles between VI and Emacs key bindings
174+
* ``F4`` toggles between single and multi column auto completions
175+
* ``F5`` shows and hides the help documentation pane
176+
* ``F10`` or ``Ctrl-D`` exits the AWS Shell
177+
178+
As you toggle options in the toolbar, your preferences are persisted
179+
to the ``~/.aws/shell/awsshellrc`` file so that the next time you run
180+
the AWS Shell, your preferences will be restored.
181+
182+
.. image:: https://cloud.githubusercontent.com/assets/368057/11823907/8c3f1e60-a32b-11e5-9f99-fe504ea0a5dc.png
183+
184+
Dot Commands
185+
------------
186+
187+
The AWS Shell provides additional commands specific to the AWS Shell.
188+
The commands are available by adding the ``.`` prefix before a command.
189+
190+
Creating Shell Scripts with .edit
191+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
192+
193+
There are times when you may want to take a sequence of commands
194+
you've run in the AWS Shell and combine them into a shell script.
195+
In addition to the command history that's persisted to the
196+
history file, the AWS Shell also keeps track of all the commands
197+
you've run since you first started your AWS Shell session.
198+
199+
You can run the ``.edit`` command to open all these commands in
200+
an editor. The AWS Shell will use the ``EDITOR`` environment
201+
variable before defaulting to ``notepad`` on Windows and
202+
``vim`` on other platforms.
203+
204+
::
205+
206+
aws> ec2 describe-instances
207+
aws> dynamodb list-tables
208+
aws> .edit
209+
210+
211+
Executing Shell Commands
212+
------------------------
213+
214+
The AWS Shell integrates with other commands in several ways.
215+
First, you can pipe AWS CLI commands to other processes as well
216+
as redirect output to a file::
217+
218+
aws> dynamodb list-tables --output text | head -n 1
219+
TABLENAMES First
220+
aws> dynamodb list-tables --output text > /tmp/foo.txt
221+
222+
Second, if you want to run a shell command rather than an AWS CLI
223+
command, you can add the ``!`` prefix to your command::
224+
225+
aws> !ls /tmp/
226+
foo.txt bar.txt
227+
228+
Developer Preview Status
229+
========================
230+
231+
The AWS Shell is currently in developer preview.
232+
We welcome feedback, feature requests, and bug reports.
233+
There may be backwards incompatible changes made in order
234+
to respond to customer feedback as we continue to iterate
235+
on the AWS Shell.
236+
237+
238+
More Information
239+
================
240+
241+
Below are miscellaneous links for more information:
242+
243+
* `AWS CLI Reference Docs`_
244+
* `AWS CLI User Guide`_
245+
* `AWS CLI Blog`_
246+
* `AWS CLI Github Repo`_
247+
248+
.. _pip: http://www.pip-installer.org/en/latest/
249+
.. _AWS CLI Getting Started Guide: http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html
250+
.. _boto3: https://github.com/boto/boto3
251+
.. _AWS CLI Reference Docs: http://docs.aws.amazon.com/cli/latest/reference/
252+
.. _AWS CLI User Guide: http://docs.aws.amazon.com/cli/latest/userguide/
253+
.. _AWS CLI Blog: https://blogs.aws.amazon.com/cli/
254+
.. _AWS CLI Github Repo: https://github.com/aws/aws-cli

0 commit comments

Comments
 (0)