diff --git a/Makefile b/Makefile
index 8eec896..95bbfd3 100644
--- a/Makefile
+++ b/Makefile
@@ -13,3 +13,9 @@ integration: build
 
 clean:
 	rm -f shout
+
+install: build
+	sudo cp ./shout /usr/local/bin
+
+uninstall:
+	sudo rm /usr/local/bin/shout
diff --git a/README.md b/README.md
index 9f1c2a0..c9f4d0c 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,72 @@
 # shout
+
+`shout` is kinda like really basic integration testing for your cli.
+
+Write `.shout` files that look like shell sessions and run `shout` to test 'em.
+
+## Install
+
+```
+git clone https://git.nose.space/defunkt/go-shout
+cd go-shout
+make install
+```
+
+## Features
+
+Everything you could ever ask for:
+
+```
+$ echo hello
+hello
+
+$ brew --version
+Homebrew 5...
+
+$ ls missing
+ls: missing: No such file or directory
+[1]
+```
+
+`...` matches anything — a whole line inline, or any number of lines on its own.
+
+`[1]` after the expected output matches the exit code.
+
+## Usage
+
+```
+$ shout test
+...............
+15 passed in 23ms
+```
+
+`shout test` runs code in a temp directory. `-k`/`--keep` keeps it around.
+
+`--update` will modify `.shout` files to match reality, without running any tests.
+
+Each line in a `.shout` file is run sequentially, unless `--parallel` is passed.
+
+```
+Usage: shout test [options] [files...]
+
+Run .shout test files
+
+Arguments:
+  files            Files or directories to test
+
+Options:
+  -u, --update     Rewrite expected output in-place with actual output
+  -k, --keep       Keep temp directories after run
+  --clean-env      Start with empty environment
+  --path <path>    Prepend <path> to PATH (repeatable)
+  --timeout <dur>  Per-command timeout (default: "10s")
+  -v, --verbose    Print each command as it runs
+  --parallel       Run files in parallel
+  -h, --help       display help for command
+```
+
+Print an example `.shout` file:
+
+```
+$ shout example
+```