diff --git a/README.txt b/README.txt
index 49cf05c..fb57ebb 100644
--- a/README.txt
+++ b/README.txt
@@ -3,9 +3,27 @@
 | |\/| | | | | | __| | '_ \ / _` | | | | |
 | |  | | |_| | | |_| | |_) | (_| | | |_|_|
 |_|  |_|\__,_|_|\__|_|_.__/ \__,_|_|_(_|_)
-
 Run commands across a set of hosts interactively!
-=================================================
+
+
+## Core Concepts
+
+At its core, multiball allows you to run commands on multiple target hosts via ssh. The actual commands are run
+non-interactively, and when complete show their output.
+
+Multiball has a list of 'default' hosts that it loads from a specified configuration file.
+
+Multiball has a list of 'targeted' hosts that it will run the commands on. This list is arbitrary, and is set to the
+default host list at startup.
+
+Multiball includes a set of commands to manipulate the target list.
+
+Multiball has a safety system: By default multiball is "safe", preventing any commands from being run on the target
+list, while still allowing manipulation of the host list and other commands that would not run on the remote hosts. Once
+it is unsafetied (using the `/safety off` command), any command that isn't a multiball command will be run on the remote
+hosts in the target list.
+
+## Quickstart
 
 Basic configuration file is in `multiball.cfg.example` in the distribution. Customize to your liking. 
 
@@ -13,8 +31,7 @@ Host list is loaded from your ssh configuration by default (assuming you have a
 
 Planned features, see __main__.py's comments.
 
-Installation
--------------------------------------------------
+### Installation
 
 Install dependencies:
 
@@ -33,3 +50,31 @@ Install, including dependencies:
 cd multiball
 make
 ```
+
+### Usage
+
+The `multiball` command starts an interactive shell. It looks in the current working directory for its configuration
+file (`multiball.cfg`). Typically, a different configuration for each project, client, etc would be created. For
+example at Autonomic, we have a multiball.cfg in our infrastructure repository, in `infrastructure-data`, so to work
+on Autonomic hosts, run multiball from that directory.
+
+Commands:
+
+* /help, help, ? - This help
+* /targethosts, /targethosts, /targets, /hosts - Show the current list of target hosts.
+* /clear - Clear target host list.
+* /host, /add, /target - Set the target host list. /host clears the list first. Supports wildcards.
+* /remove, /removehost, /removetarget - Remove hosts from target host list. Supports wildcards.
+* /all - Reset the target host list to all known hosts.
+* /allhosts, /alltargets - Show list of all known hosts.
+* /exit, exit - Exit.
+* /environment, /env, /set - Set (or print) environment to send to remote host before running commands.
+* /clearenv - Clear environment (entire or single variable)
+* /safety, safety - Turn on safety or turn off with `off`.
+* /safe - Run this command as if it were safe even if safety is on.
+* /confirm - [scripting] Prompt for confirmation
+* /echo - [scripting] print string
+* /arguments - [scripting] Abort if no arguments are specified.
+* /unsafe - [scripting] Abort command if safety is on.
+* /save - Save last run log to file.
+