diff --git a/README.md b/README.md
index c331d1de90..5d681c8c37 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,46 @@ A library to **sub**mit e**xt**rinsics to a [substrate](https://github.com/parit
 
 ## Usage
 
-See [examples](./examples).
+### Downloading metadata from a Substrate node
+
+Use the [`subxt-cli`](./cli) tool to download the metadata for your target runtime from a node.
+
+1. Install:
+```bash
+cargo install subxt-cli
+```
+2. Save the encoded metadata to a file:
+```bash
+subxt metadata -f bytes > metadata.scale
+```
+
+This defaults to querying the metadata of a locally running node on the default `http://localhost:9933/`. If querying
+a different node then the `metadata` command accepts a `--url` argument.
+
+### Generating the runtime API from the downloaded metadata
+
+Declare a module and decorate it with the `subxt` attribute which points at the downloaded metadata for the 
+target runtime:
+
+```rust
+#[subxt::subxt(runtime_metadata_path = "metadata.scale")]
+pub mod node_runtime { }
+```
+
+**Important:** `runtime_metadata_path` resolves to a path relative to the directory where your crate's `Cargo.toml` 
+resides ([`CARGO_MANIFEST_DIR`](https://doc.rust-lang.org/cargo/reference/environment-variables.html)), *not* relative to the source file.
+
+### Initializing the API client
+
+API is still a work in progress. See [examples](./examples) for the current usage.
+
+### Querying Storage
+
+API is still a work in progress. See [tests](./tests/integration/frame) for the current usage.
+
+### Submitting Extrinsics
+
+API is still a work in progress. See [examples](./examples/polkadot_balance_transfer.rs) for the current usage.
 
 ## Integration Testing
 
@@ -25,11 +64,6 @@ cargo install --git https://github.com/paritytech/substrate node-cli --tag=polka
 
 [substrate-api-client](https://github.com/scs/substrate-api-client) provides similar functionality.
 
-## Subxt Client
-By default the client builder will connect to a full node via rpc. The `subxt-client` helps
-embedding a light client directly. It can also be used to embed a full node. This is especially
-useful for testing and ci.
-
 #### License
 
 <sup>