diff --git a/README.md b/README.md
index 601ee39f0..9af38d74e 100644
--- a/README.md
+++ b/README.md
@@ -76,9 +76,9 @@ The specs contained in this repository are:
 - [Files Impl and API](/files) - Virtual File System interface, unix like, on top of the MerkleDAG
 
 **Public APIs:**
-- [Core API](/public-api/core) - IPFS programmatic interface
-- [HTTP API](https://github.com/ipfs/http-api-spec) - IPFS HTTP API specification
 - [CLI](/public-api/cli) - Command Line Interface
+- [HTTP API](https://github.com/ipfs/http-api-spec) - IPFS HTTP API specification
+- [Core API](/public-api/core) - IPFS programatic interface
 
 **Records and Record Systems:**
 - [IPRS](/iprs-interplanetary-record-system) - InterPlanetary Record System
diff --git a/public-api/cli/README.md b/public-api/cli/README.md
index 14e7c4f51..359995553 100644
--- a/public-api/cli/README.md
+++ b/public-api/cli/README.md
@@ -3,100 +3,156 @@ CLI - Command Line Interface
 
 ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square)
 
-# Commands
-
-- ipfs
-- ipfs add
-- ipfs bitswap
-- ipfs bitswap stat
-- ipfs bitswap unwant
-- ipfs bitswap wantlist
-- ipfs block
-- ipfs block get
-- ipfs block put
-- ipfs block stat
-- ipfs bootstrap
-- ipfs bootstrap add
-- ipfs bootstrap list
-- ipfs bootstrap rm
-- ipfs cat
-- ipfs commands
-- ipfs config
-- ipfs config edit
-- ipfs config replace
-- ipfs config show
-- ipfs daemon
-- ipfs dht
-- ipfs dht findpeer
-- ipfs dht findprovs
-- ipfs dht get
-- ipfs dht put
-- ipfs dht query
-- ipfs diag
-- ipfs diag net
-- ipfs diag sys
-- ipfs dns
-- ipfs files
-- ipfs files ls
-- ipfs files
-- ipfs files cp
-- ipfs files ls
-- ipfs files mkdir
-- ipfs files mv
-- ipfs files read
-- ipfs files rm
-- ipfs files stat
-- ipfs files write
-- ipfs get
-- ipfs id
-- ipfs init
-- ipfs log
-- ipfs log level
-- ipfs log tail
-- ipfs ls
-- ipfs mount
-- ipfs name
-- ipfs name publish
-- ipfs name resolve
-- ipfs object
-- ipfs object data
-- ipfs object get
-- ipfs object links
-- ipfs object new
-- ipfs object patch
-- ipfs object patch add-link
-- ipfs object patch append-data
-- ipfs object patch rm-link
-- ipfs object patch set-data
-- ipfs object put
-- ipfs object stat
-- ipfs pin
-- ipfs pin add
-- ipfs pin ls
-- ipfs pin rm
-- ipfs ping
-- ipfs refs
-- ipfs refs local
-- ipfs repo
-- ipfs repo gc
-- ipfs resolve
-- ipfs stats
-- ipfs stats bw
-- ipfs swarm
-- ipfs swarm addrs
-- ipfs swarm addrs local
-- ipfs swarm connect
-- ipfs swarm disconnect
-- ipfs swarm filters
-- ipfs swarm filters add
-- ipfs swarm filters rm
-- ipfs swarm peers
-- ipfs tar
-- ipfs tar add
-- ipfs tar cat
-- ipfs tour
-- ipfs tour list
-- ipfs tour next
-- ipfs tour restart
-- ipfs update
-- ipfs version
+## Commands
+
+- `> ipfs commands`
+
+## Daemon
+
+- `> ipfs daemon`
+- `> ipfs id`
+- `> ipfs init`
+- `> ipfs log`
+- `> ipfs log level`
+- `> ipfs log tail`
+- `> ipfs diag`
+- `> ipfs diag net`
+- `> ipfs diag sys`
+- `> ipfs stats`
+- `> ipfs stats bw`
+- `> ipfs update`
+- `> ipfs version`
+
+## DAG
+
+- `> ipfs dag get`
+- `> ipfs dag put`
+
+#### `ipfs dag get <[cid, cid+path]>`
+
+The `dag get` call will be able to fetch nodes and resolve paths, the options for this command are:
+
+**Options:**
+- `--local-resolve` - It will try to resolve everything it can within the scope of the first object, returning the last value it could + the remainerPath
+
+#### `ipfs dag put <node>`
+
+The `dag put` call will store a single node at each time and return its respective CID
+
+**Options:**
+- `--format` - The multicodec of the format (dag-pb, dag-cbor, etc)
+- `--hash-alg` - The hash algorithm to be used
+- `--input-enc` - The input encoding of how the object is being passed. This is just a requirement to make sense of a blob of characters from a CLI context.
+
+## Files
+
+> discussion:
+> - https://github.com/ipfs/specs/issues/98
+> - https://github.com/ipfs/specs/issues/88
+
+- `> ipfs files add`
+- `> ipfs files cat`
+- `> ipfs files get`
+- `> ipfs files ls`
+- `> ipfs files cp`
+- `> ipfs files ls`
+- `> ipfs files mkdir`
+- `> ipfs files mv`
+- `> ipfs files read`
+- `> ipfs files rm`
+- `> ipfs files stat`
+- `> ipfs files write`
+- `> ipfs tar`
+- `> ipfs tar add`
+- `> ipfs tar cat`
+
+## Bitswap
+
+- `> ipfs bitswap`
+- `> ipfs bitswap stat`
+- `> ipfs bitswap unwant`
+- `> ipfs bitswap wantlist`
+
+## Block
+
+- `> ipfs block`
+- `> ipfs block get`
+- `> ipfs block put`
+- `> ipfs block stat`
+
+## Bootstrap
+
+- `> ipfs bootstrap`
+- `> ipfs bootstrap add`
+- `> ipfs bootstrap list`
+- `> ipfs bootstrap rm`
+
+## Config
+
+- `> ipfs config`
+- `> ipfs config edit`
+- `> ipfs config replace`
+- `> ipfs config show`
+
+## Name
+
+- `> ipfs dns`
+- `> ipfs name publish`
+- `> ipfs name resolve`
+- `> ipfs resolve`
+
+## DHT
+
+- `> ipfs dht`
+- `> ipfs dht findpeer`
+- `> ipfs dht findprovs`
+- `> ipfs dht get`
+- `> ipfs dht put`
+- `> ipfs dht query`
+
+## Object
+
+- `> ipfs object data`
+- `> ipfs object get`
+- `> ipfs object links`
+- `> ipfs object new`
+- `> ipfs object patch`
+- `> ipfs object patch add-link`
+- `> ipfs object patch append-data`
+- `> ipfs object patch rm-link`
+- `> ipfs object patch set-data`
+- `> ipfs object put`
+- `> ipfs object stat`
+
+## Pinning
+
+- `> ipfs pin add`
+- `> ipfs pin ls`
+- `> ipfs pin rm`
+
+## Network
+
+- `> ipfs ping`
+- `> ipfs swarm`
+- `> ipfs swarm addrs`
+- `> ipfs swarm addrs local`
+- `> ipfs swarm connect`
+- `> ipfs swarm disconnect`
+- `> ipfs swarm filters`
+- `> ipfs swarm filters add`
+- `> ipfs swarm filters rm`
+- `> ipfs swarm peers`
+
+## Repo
+
+- `> ipfs refs`
+- `> ipfs refs local`
+- `> ipfs repo`
+- `> ipfs repo gc`
+
+## Misc
+
+- `> ipfs tour`
+- `> ipfs tour list`
+- `> ipfs tour next`
+- `> ipfs tour restart`
diff --git a/public-api/core/README.md b/public-api/core/README.md
index 22b90dab6..3ff6af247 100644
--- a/public-api/core/README.md
+++ b/public-api/core/README.md
@@ -3,9 +3,7 @@ Core API
 
 > The `core` API is the programmatic interface for IPFS, it defines the method signatures.
 
-# Status
-
-![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square)
+# Status ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square)
 
 ## Required for compliant IPFS implementation
 
@@ -114,3 +112,5 @@ Core API
 - records (iprs)
   - put
   - get
+
+# [Interface definition and test suite](https://github.com/ipfs/interface-ipfs-core)