diff --git a/README.md b/README.md
new file mode 100644
index 00000000..2fca26a9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,57 @@
+# helmfile
+
+Deploy Kubernetes Helm Charts
+
+## about
+
+Helmfile is a declarative spec for deploying helm charts. It lets you...
+
+* Keep a directory of chart value files and maintain changes in version control.
+* Apply CI/CD to configuration changes.
+* Periodically sync to avoid skew in environments.
+
+To avoid upgrades for each iteration of `helm`, the `helmfile` executable delegates to `helm` - as a result, `helm` must be installed.
+
+The default helmfile is `charts.yaml`:
+
+```
+repositories:
+  - name: roboll
+    url: http://roboll.io/charts
+
+charts:
+  - name: vault                          # helm deployment name
+    namespace: vault                     # target namespace
+    chart: roboll/vault-secret-manager   # chart reference
+    values: [ vault.yaml ]               # value files (--values)
+    set:                                 # values (--set)
+      - name: address
+        value: https://vault.example.com
+
+```
+
+## usage
+
+```
+NAME:
+   helmfile
+
+USAGE:
+   helmfile [global options] command [command options] [arguments...]
+
+VERSION:
+   0.0.0
+
+COMMANDS:
+     repos    sync repositories from state file (helm repo add && help repo update)
+     charts   sync charts from state file (helm repo upgrade --install)
+     sync     sync all resources from state file (repos && charts)
+     delete   delete charts from state file (helm delete)
+     help, h  Shows a list of commands or help for one command
+
+GLOBAL OPTIONS:
+   --file FILE, -f FILE  load config from FILE (default: "charts.yaml")
+   --quiet, -q           silence output
+   --help, -h            show help
+   --version, -v         print the version
+```
diff --git a/main.go b/main.go
index c9a4a1f9..51e6eea9 100644
--- a/main.go
+++ b/main.go
@@ -36,7 +36,7 @@ func main() {
 	app.Commands = []cli.Command{
 		{
 			Name:  "repos",
-			Usage: "sync repositories from state file",
+			Usage: "sync repositories from state file (helm repo add && helm repo update)",
 			Flags: []cli.Flag{
 				cli.StringFlag{
 					Name:  "args",
@@ -66,7 +66,7 @@ func main() {
 		},
 		{
 			Name:  "charts",
-			Usage: "sync charts from state file",
+			Usage: "sync charts from state file (helm repo upgrade --install)",
 			Flags: []cli.Flag{
 				cli.StringFlag{
 					Name:  "args",
@@ -96,7 +96,7 @@ func main() {
 		},
 		{
 			Name:  "sync",
-			Usage: "sync all resources from state file",
+			Usage: "sync all resources from state file (repos && charts)",
 			Action: func(c *cli.Context) error {
 				state, helm, err := before(c)
 				if err != nil {
@@ -121,7 +121,7 @@ func main() {
 		},
 		{
 			Name:  "delete",
-			Usage: "delete charts from state file",
+			Usage: "delete charts from state file (helm delete)",
 			Action: func(c *cli.Context) error {
 				state, helm, err := before(c)
 				if err != nil {