diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2978b4d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,66 @@
+A simple server to share objects on an s3 bucket and display them in a nice way.
+
+# Features
+
+- Share any object on an s3 bucket
+- Generate short urls for the share
+- Simple API to create shares
+
+# Building
+
+Run `make` and the binary together with the web frontend will be in the `build` directory.
+
+# Usage
+
+Run the `s3browser` binary with the `--help` flag to see the available options.
+The `public` directory needs to be in the same directory as the binary.
+
+S3Share requires two things:
+
+- a s3 bucket with read access
+- a sql database
+
+# Synopsis
+
+```
+s3share 0.1
+Usage: s3share --s3-endpoint ENDPOINT --s3-bucket BUCKET --s3-access-key ACCESS_KEY --s3-secret-key SECRET_KEY [--s3-disable-ssl] [--address ADDRESS] --api-username USERNAME --api-password PASSWORD --db DB
+
+Options:
+  --s3-endpoint ENDPOINT
+                         host[:port] [env: S3_ENDPOINT]
+  --s3-bucket BUCKET     bucket to use [env: S3_BUCKET]
+  --s3-access-key ACCESS_KEY [env: S3_ACCESS_KEY]
+  --s3-secret-key SECRET_KEY [env: S3_SECRET_KEY]
+  --s3-disable-ssl [default: false, env: S3_DISABLE_SSL]
+  --address ADDRESS      what address to listen on [default: :3000, env: ADDRESS]
+  --api-username USERNAME
+                         username for API [env: API_USERNAME]
+  --api-password PASSWORD
+                         password for API [env: API_PASSWORD]
+  --db DB                DSN in format: https://github.com/go-sql-driver/mysql#dsn-data-source-name [env: DB_CONNECTION]
+  --help, -h             display this help and exit
+  --version              display version and exit
+```
+
+# API
+
+Use the provided username and password with basic auth.
+
+Shares ids consist of six alphanumeric characters e.g. `jW8ADy`.
+
+- `GET /api/share`: Get a list of all shares
+- `GET /api/share/:id`: Get a share by id. Result:
+```json
+{"slug":"jW8ADy","key":"/myObj.txt"}
+```
+- `POST /api/share`: Create a new share. Data to send:
+```json
+{"key":"/myObj.txt"}
+```
+- `DELETE /api/share/:id`: Delete a share
+
+Other urls are:
+
+- `/:id` to get the default site to display the share.
+- `/s/:id` to get the shared file directly.