diff --git a/API.md b/API.md
index b8dcb857b..eda2ab08a 100644
--- a/API.md
+++ b/API.md
@@ -1,286 +1,223 @@
-# API
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [API](#api)
+  - [Callbacks and promises](#callbacks-and-promises)
+  - [Reference](#reference)
+    - [Core](#core)
+      - [`version([callback])`](#versioncallback)
+      - [`id([callback])`](#idcallback)
+      - [`block`](#block)
+        - [`block.put(buffer, [callback])`](#blockputbuffer-callback)
+        - [`block.get(hash, [callback])`](#blockgethash-callback)
+        - [`block.stat(hash, [callback])`](#blockstathash-callback)
+      - [`object`](#object)
+        - [`object.put(buffer, encoding, [callback])`](#objectputbuffer-encoding-callback)
+        - [`object.get(hash, [callback])`](#objectgethash-callback)
+        - [`object.data(hash, [callback])`](#objectdatahash-callback)
+        - [`object.stat(hash, [callback])`](#objectstathash-callback)
+        - [`object.links(hash, [callback])`](#objectlinkshash-callback)
+        - [`object.new(hash, [callback])`](#objectnewhash-callback)
+        - [`object.patch`](#objectpatch)
+          - [`object.patch.addLink(hash, name, ref, [callback])`](#objectpatchaddlinkhash-name-ref-callback)
+          - [`object.patch.rmLink(hash, name, [callback])`](#objectpatchrmlinkhash-name-callback)
+          - [`object.patch.setData(hash, data, [callback])`](#objectpatchsetdatahash-data-callback)
+          - [`object.patch.appendData(hash, data, ref, [callback])`](#objectpatchappenddatahash-data-ref-callback)
+      - [`refs(hash, options, [callback])`](#refshash-options-callback)
+        - [`refs.local(hash, [callback])`](#refslocalhash-callback)
+      - [`pin`](#pin)
+        - [`pin.add(hash, options, [callback])`](#pinaddhash-options-callback)
+        - [`pin.remove(hash, options, [callback])`](#pinremovehash-options-callback)
+        - [`pin.list(hash, options, [callback])`](#pinlisthash-options-callback)
+      - [`log`](#log)
+        - [`log.tail([callback])`](#logtailcallback)
+    - [Extensions](#extensions)
+      - [`add(arrayOrBufferOrStream, [callback])`](#addarrayorbufferorstream-callback)
+      - [`name`](#name)
+        - [`name.publish(hash, [callback])`](#namepublishhash-callback)
+        - [`name.resolve(hash, [callback])`](#nameresolvehash-callback)
+      - [`files`](#files)
+        - [`files.cp(src, target, [callback])`](#filescpsrc-target-callback)
+        - [`files.ls(folder, [callback])`](#fileslsfolder-callback)
+        - [`files.mkdir(folder, [options, callback])`](#filesmkdirfolder-options-callback)
+        - [`files.stat(fileOrFolder, [callback])`](#filesstatfileorfolder-callback)
+        - [`files.rm(fileOrFolder, [options, callback])`](#filesrmfileorfolder-options-callback)
+        - [`files.read(fileOrFolder, [callback])`](#filesreadfileorfolder-callback)
+        - [`files.write(file, bufferOrArray, [options, callback])`](#fileswritefile-bufferorarray-options-callback)
+        - [`files.mv(src, target, [callback])`](#filesmvsrc-target-callback)
+      - [`mount(ipfs, ipns, [callback])`](#mountipfs-ipns-callback)
+    - [Tooling](#tooling)
+      - [`commands([callback])`](#commandscallback)
+      - [`update`](#update)
+        - [`update.apply([callback])`](#updateapplycallback)
+        - [`update.check([callback])`](#updatecheckcallback)
+        - [`update.log([callback])`](#updatelogcallback)
+      - [`diag`](#diag)
+        - [`diag.net([callback])`](#diagnetcallback)
+        - [`diag.sys([callback])`](#diagsyscallback)
+        - [`diag.cmds([callback])`](#diagcmdscallback)
+    - [Network](#network)
+      - [`ping(id, [callback])`](#pingid-callback)
+      - [`dht`](#dht)
+        - [`dht.findprovs([callback])`](#dhtfindprovscallback)
+        - [`dht.get(key, [options, callback])`](#dhtgetkey-options-callback)
+        - [`dht.put(key, value, [options, callback])`](#dhtputkey-value-options-callback)
+      - [`swarm`](#swarm)
+        - [`swarm.peers([callback])`](#swarmpeerscallback)
+        - [`swarm.connect(address, [callback])`](#swarmconnectaddress-callback)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-## Usage
+# API
 
 We classify the API calls by 'core', 'extensions', 'tooling', and 'network', following the same API spec organization available at [ipfs/specs](https://github.com/ipfs/specs/tree/master/api).
 
-The tests folder also contains great examples that can be used to understand how this client library interacts with the HTTP-API. You can find the [tests here](tests/api).
-
-### Core
-
-##### version
-
-- [examples](https://github.com/ipfs/js-ipfs-api/blob/master/test/api/version.spec.js)
-
-##### node
+The tests folder also contains great examples that can be used to understand how this client library interacts with the HTTP-API. You can find the [tests here](test/api).
 
-> node start and stop are not implemented in the API
 
-- [examples](https://github.com/ipfs/js-ipfs-api/blob/master/test/api/id.spec.js)
+## Callbacks and promises
 
-##### block
+If you do not pass in a callback all api functions will return a `Promise`, for example
 
-- [examples](https://github.com/ipfs/js-ipfs-api/blob/master/test/api/block.spec.js)
-
-##### object
-
-*curl*
-```sh
-curl 'http://localhost:5001/api/v0/object/get?arg=QmYEqnfCZp7a39Gxrgyv3qRS4MoCTGjegKV6zroU3Rvr52&stream-channels=true' --compressed
-```
-
-*response*
 ```js
-{
-    Links: [{
-        Name: string,
-        Hash: string,
-        Size: number
-    }, ...],
-    Data: string
-}
-```
-*Data is base64 encoded.*
-
-- [examples](https://github.com/ipfs/js-ipfs-api/blob/master/test/api/object.spec.js)
-
-##### pin
-
-
--------------------------------------------------------
-
-### Extensions
-
-
--------------------------------------------------------
-
-### Tooling
-
-##### add
-
-Add a file (where file is any data) to ipfs returning the hash and name. The
-name value will only be set if you are actually sending a file. A single or
-array of files can be used.
-
-*usage*
-```javascript
-ipfs.add(files, function(err, res) {
-    if(err || !res) return console.error(err)
-
-    res.forEach(function(file) {
-        console.log(file.Hash)
-        console.log(file.Name)
-    })
-})
+ipfs.id()
+  .then(function (id) {
+    console.log('my id is: ', id)
+  })
 ```
 
-`files` can be a mixed array of filenames or buffers of data. A single value is
-also acceptable.
+This relies on a global `Promise` object. If you are in an environemnt where that is not
+yet available you need to bring your own polyfill.
 
-Example
-```js
-var files = ["../files/hello.txt", new Buffer("ipfs!")]
-var files = "../files/hello.txt"
-```
+## Reference
 
-*curl*
-```sh
-curl 'http://localhost:5001/api/v0/add?stream-channels=true' \
--H 'content-type: multipart/form-data; boundary=a831rwxi1a3gzaorw1w2z49dlsor' \
--H 'Connection: keep-alive' \
---data-binary $'--a831rwxi1a3gzaorw1w2z49dlsor\r\nContent-Type: application/octet-stream\r\nContent-Disposition: file; name="file"; filename="Hello.txt"\r\n\r\nhello--a831rwxi1a3gzaorw1w2z49dlsor--' --compressed
-```
+### Core
 
-*response*
-```js
-[{
-    Hash: string,
-    Name: string
-}, ...]
-```
-*The name value will only be set for actual files.*
+#### `version([callback])`
 
-##### cat
+- [tests](test/api/version.spec.js)
 
-Retrieve the contents of a single hash, or array of hashes.
+#### `id([callback])`
 
-**usage**
+- [tests](test/api/id.spec.js)
 
-```javascript
-ipfs.cat(hashs, function(err, res) {
-    if(err || !res) return console.error(err)
+#### `block`
 
-    if(res.readable) {
-        // Returned as a stream
-        res.pipe(process.stdout)
-    } else {
-        // Returned as a string
-        console.log(res)
-    }
-})
-```
+- [tests](test/api/block.spec.js)
 
-*curl*
+##### `block.put(buffer, [callback])`
+##### `block.get(hash, [callback])`
+##### `block.stat(hash, [callback])`
 
-```sh
-curl "http://localhost:5001/api/v0/cat?arg=<hash>&stream-channels=true"
-```
+#### `object`
 
-*response*
+- [tests](test/api/object.spec.js)
 
-The response is either a readable stream, or a string.
+##### `object.put(buffer, encoding, [callback])`
+##### `object.get(hash, [callback])`
+##### `object.data(hash, [callback])`
+##### `object.stat(hash, [callback])`
+##### `object.links(hash, [callback])`
+##### `object.new(hash, [callback])`
 
-##### ls
-Get the node structure of a hash. Included in it is a hash and array to links.
+##### `object.patch`
 
-*Usage*
-```javascript
-ipfs.ls(hashs, function(err, res) {
-    if(err || !res) return console.error(err)
+###### `object.patch.addLink(hash, name, ref, [callback])`
+###### `object.patch.rmLink(hash, name, [callback])`
+###### `object.patch.setData(hash, data, [callback])`
+###### `object.patch.appendData(hash, data, ref, [callback])`
 
-    res.Objects.forEach(function(node) {
-        console.log(node.Hash)
-        console.log("Links [%d]", node.Links.length)
-        node.Links.forEach(function(link, i) {
-            console.log("[%d]", i, link)
-        })
-    })
-})
-```
+#### `refs(hash, options, [callback])`
 
-*Curl*
-```sh
-curl "http://localhost:5001/api/v0/ls?arg=<hash>&stream-channels=true"
-```
+- [tests](test/api/refs.spec.js)
 
-*Response*
-```js
-{
-    Objects: [
-        {
-            Hash: string,
-            Links: [{
-                Name: string,
-                Hash: string,
-                Size: number
-            }, ...]
-        },
-        ....
-    ]
-}
-```
+##### `refs.local(hash, [callback])`
 
-##### update
 
--------------------------------------------------------
+#### `pin`
 
-### Network
+- [tests](test/api/pin.spec.js)
 
+##### `pin.add(hash, options, [callback])`
+##### `pin.remove(hash, options, [callback])`
+##### `pin.list(hash, options, [callback])`
 
----------
+#### `log`
 
-#### Files
+- [tests](test/api/log.spec.js)
 
-##### mkdir
+##### `log.tail([callback])`
 
-```JavaScript
-ipfs.files.mkdir(<folderName>, function (err) {})
-```
+### Extensions
 
-##### cp
+#### `add(arrayOrBufferOrStream, [callback])`
 
-```JavaScript
-ipfs.files.cp([<pathSrc>, <pathDst>], function (err) {})
-```
+- [tests](test/api/add.spec.js)
 
-##### ls
+#### `name`
 
-```JavaScript
-ipfs.files.ls(<path>, function (err, res) {})
-```
+- [tests](test/api/name.spec.js)
 
-##### stat
+##### `name.publish(hash, [callback])`
+##### `name.resolve(hash, [callback])`
 
-```JavaScript
-ipfs.files.stat(<path>, function (err, res) {})
-```
+#### `files`
 
-##### rm
+- [tests](test/api/files.spec.js)
 
-```JavaScript
-ipfs.files.rm(<path>, [<options>],  function (err) {})
-```
+##### `files.cp(src, target, [callback])`
+##### `files.ls(folder, [callback])`
+##### `files.mkdir(folder, [options, callback])`
+##### `files.stat(fileOrFolder, [callback])`
+##### `files.rm(fileOrFolder, [options, callback])`
+##### `files.read(fileOrFolder, [callback])`
+##### `files.write(file, bufferOrArray, [options, callback])`
+##### `files.mv(src, target, [callback])`
 
-For `rm -r` pass a options obj with `r: true`
+#### `mount(ipfs, ipns, [callback])`
 
-##### read
+- [tests](test/api/mount.spec.js)
 
-```JavaScript
-ipfs.files.read(<path>, function (err, res) {
-  if(res.readable) {
-    // Returned as a stream
-    res.pipe(process.stdout)
-  } else {
-    // Returned as a string
-    console.log(res)
-  }
-})
-```
+### Tooling
 
-##### write
+#### `commands([callback])`
 
-##### mv
+- [tests](test/api/commands.spec.js)
 
-```JavaScript
-ipfs.files.mv([<pathSrc>, <pathDst>], function (err) {})
-```
+#### `update`
 
-response: (it returns empty when successful)
+- [tests](test/api/update.spec.js)
 
-##### cp
+##### `update.apply([callback])`
+##### `update.check([callback])`
+##### `update.log([callback])`
 
-```JavaScript
-ipfs.files.cp([<pathSrc>, <pathDst>], function (err) {})
-```
+#### `diag`
 
-##### ls
+- [tests](test/api/diag.spec.js)
 
-```JavaScript
-ipfs.files.ls(<path>, function (err, res) {})
-```
-
-##### stat
+##### `diag.net([callback])`
+##### `diag.sys([callback])`
+##### `diag.cmds([callback])`
 
-```JavaScript
-ipfs.files.stat(<path>, function (err, res) {})
-```
+### Network
 
-##### rm
+#### `ping(id, [callback])`
 
-```JavaScript
-ipfs.files.rm(<path>, [<options>],  function (err) {})
-```
+- [tests](test/api/ping.spec.js)
 
-For `rm -r` pass a options obj with `r: true`
+#### `dht`
 
-##### read
+- [tests](test/api/dht.spec.js)
 
-```JavaScript
-ipfs.files.read(<path>, function (err, res) {
-  if(res.readable) {
-    // Returned as a stream
-    res.pipe(process.stdout)
-  } else {
-    // Returned as a string
-    console.log(res)
-  }
-})
-```
+##### `dht.findprovs([callback])`
+##### `dht.get(key, [options, callback])`
+##### `dht.put(key, value, [options, callback])`
 
-##### write
+#### `swarm`
 
-##### mv
-curl "http://localhost:5001/api/v0/files/mkdir?arg=%2Ffolder4"
+- [tests](test/api/swarm.spec.js)
 
-```JavaScript
-ipfs.files.mv([<pathSrc>, <pathDst>], function (err) {})
+##### `swarm.peers([callback])`
+##### `swarm.connect(address, [callback])`
diff --git a/README.md b/README.md
index 28a4f8f34..d2ce2dbf4 100644
--- a/README.md
+++ b/README.md
@@ -49,20 +49,6 @@ If you omit the host and port, the api will parse `window.host`, and use this in
 var ipfs = window.ipfsAPI()
 ```
 
-### Using Promises
-
-If you do not pass in a callback all api functions will return a `Promise`, for example
-
-```js
-ipfs.id()
-  .then(function (id) {
-    console.log('my id is: ', id)
-  })
-```
-
-This relies on a global `Promise` object. If you are in an environemnt where that is not
-yet available you need to bring your own polyfill.
-
 #### Gotchas
 
 When using the api from script tag for things that require buffers (`ipfs.add`, for example), you will have to use either the exposed `ipfs.Buffer`, that works just like a node buffer, or use this [browser buffer](https://github.com/feross/buffer).
@@ -77,4 +63,4 @@ $ ipfs config --json API.HTTPHeaders.Access-Control-Allow-Origin "[\"http://exam
 
 ## Usage
 
-See [API.md](API.md) and `tests/api` for details on available methods.
+See [API.md](API.md) and [`tests/api`](test/api) for details on available methods.
diff --git a/src/api/diag.js b/src/api/diag.js
index d4f6ac2c6..438817446 100644
--- a/src/api/diag.js
+++ b/src/api/diag.js
@@ -5,6 +5,7 @@ const command = require('../cmd-helpers').command
 module.exports = (send) => {
   return {
     net: command(send, 'diag/net'),
-    sys: command(send, 'diag/sys')
+    sys: command(send, 'diag/sys'),
+    cmds: command(send, 'diag/sys')
   }
 }
diff --git a/test/api/diag.spec.js b/test/api/diag.spec.js
index 63dc9ed24..c2939190c 100644
--- a/test/api/diag.spec.js
+++ b/test/api/diag.spec.js
@@ -19,6 +19,14 @@ describe('.diag', () => {
     })
   })
 
+  it('.diag.cmds', (done) => {
+    apiClients['a'].diag.cmds((err, res) => {
+      expect(err).to.not.exist
+      expect(res).to.exist
+      done()
+    })
+  })
+
   describe('promise', () => {
     it('.diag.net', () => {
       return apiClients['a'].diag.net()
@@ -35,5 +43,12 @@ describe('.diag', () => {
           expect(res).to.have.a.property('diskinfo')
         })
     })
+
+    it('.diag.cmds', () => {
+      return apiClients['a'].diag.cmds()
+        .then((res) => {
+          expect(res).to.exist
+        })
+    })
   })
 })
diff --git a/test/api/object.spec.js b/test/api/object.spec.js
index 9c60a279c..dff1926e5 100644
--- a/test/api/object.spec.js
+++ b/test/api/object.spec.js
@@ -70,7 +70,7 @@ describe('.object', () => {
     })
   })
 
-  describe('object.path', () => {
+  describe('object.patch', () => {
     before((done) => {
       apiClients['a'].object.put(testPatchObject, 'json', (err, res) => {
         expect(err).to.not.exist