diff --git a/README.md b/README.md
index 6ed3a73..b7bc5d1 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,93 @@ Node package compare and change runner.
 [![npm](https://img.shields.io/npm/v/pkgcomp.svg)](https://www.npmjs.com/package/pkgcomp)
 [![Project Status](https://img.shields.io/badge/status-experimental-orange.svg)](https://nodejs.org/api/documentation.html#documentation_stability_index)
 
+## Usage
+
+Simply install the package and run it from the command line in your project. You can install it globally and run it that way, but installing locally is generally better.
+
+```
+yarn add -D pkgcomp
+npx pkgcomp
+```
+
+If the `dependencies` or `devDependencies` in `package.json` change, or if one of the files in your `checkFiles` config's md5 hash changes, your command will run. If the command exits with a non-zero exit code, `pkgcomp` will exit with the same exit code.
+
+Out of the box the script will do nothing, you have to provide a command to run, via the `cmd` config. See [Configuration](#configuration) below.
+
+You can also set the command, and control how the script works, via the available [command line arguments](#cli-arguments)
+
+### In node
+
+Alternatively, you can use the module in node by passing in a config object, some identifier to key changes on (`name` from package.json is what the CLI uses), and an options object to enable verbose mode or force the command to be run.
+
+```js
+const pkgcomp = require('pkgcomp');
+const config = { cmd: 'yarn install' }; // see Configuration below
+const options = { verbose: false, force: false }; // see CLI Arguments below
+
+// module returns a Promise
+pkgcomp(config, 'my-package', options)
+  .then((payload) => {
+    console.log({ payload }); // checkFiles hashes, dependencies, and devDependencies
+  })
+  .catch(err => {
+    // err has `exitCode` and `cmd` properties
+    console.error(err);
+    process.exit(err.exitCode);
+  })
+```
+
+## Configuration
+
+Configuration is provided as JSON, and can be defined in any of the following (listed by precidence):
+
+- `.config/pkgcomp.json`
+- `.pkgcomp.json`
+- `pkgcomp.json`
+- In a `pkgcomp` key in your `package.json`
+
+### Config options
+
+Name | Default | Description
+---- | ------- | -----------
+`checkFiles` | `['package-lock.json', 'yarn.lock']` | Additional files to checksum and compare, files that are not included will be skipped
+`rootDir` | `process.cwd()` | The root path to your project
+`dataDir` | `<Home>/.local/share` | Directory where this module's data should be written to
+`cmd` | `false` | Command to run when changes are found; *false or an empty string means do nothing*
+
+### Example configs
+
+As a standalone file:
+
+```json
+{
+  "checkFiles": ["yarn.lock"],
+  "cmd": "yarn install"
+}
+```
+
+As a property in `package.json`:
+
+```json
+{
+  "name": "your-package",
+  "version": "0.0.0",
+  ...
+  "pkgcomp": {
+    "checkFiles": ["yarn.lock"],
+    "cmd": "yarn install"
+  }
+}
+```
+
+## CLI Arguments
+
+Argument | Default | Description
+-------- | ------- | -----------
+`--verbose` | `false` | Shows more verbose output, like if the command is being skipped or a file in `checkFiles` does not exist
+`--force` | `false` | Runs your command regardless of whether or not there were changes in the package
+`--cmd` | | Specify the command to run when changes are found (ex. `--cmd="yarn install"`)
+
 #### License
 
 MIT © [w33ble](https://github.com/w33ble)
\ No newline at end of file