diff --git a/README.md b/README.md
index bc9bfe3..58e7e2e 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,18 @@ A Rust port of [`cacache` for Node.js](https://npm.im/cacache).
 
 A high-performance, concurrent, content-addressable disk cache.
 
+## Example
+
+```rust
+use cacache;
+use tempfile;
+let tmp = tempfile::tempdir().unwrap();
+let dir = tmp.path().to_owned();
+cacache::put::data(&dir, "key", b"my-data").unwrap();
+let data = cacache::get::read(&dir, "key").unwrap();
+assert_eq!(data, b"my-data");
+```
+
 ## Install
 
 Using [`cargo-edit`](https://crates.io/crates/cargo-edit)
diff --git a/src/lib.rs b/src/lib.rs
index 4c07538..6ef43da 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,7 +1,31 @@
 //! cacache is a Rust library for managing local key and content address
 //! caches. It's really fast, really good at concurrency, and it will never
 //! give you corrupted data, even if cache files get corrupted or manipulated.
-
+//!
+//! ## Examples
+//! ```
+//! use cacache;
+//! # use tempfile;
+//! # let tmp = tempfile::tempdir().unwrap();
+//! let dir = tmp.path().to_owned();
+//! cacache::put::data(&dir, "key", b"my-data").unwrap();
+//! let data = cacache::get::read(&dir, "key").unwrap();
+//! assert_eq!(data, b"my-data");
+//! ```
+//!
+//! You can also use the equivalent async APIs using async/await!
+//! ```
+//! # use tempfile;
+//! use cacache;
+//! # use async_std::task;
+//! # let tmp = tempfile::tempdir().unwrap();
+//! let dir = tmp.path().to_owned();
+//! # task::block_on(async {
+//! cacache::async_put::data(&dir, "key", b"my-async-data").await.unwrap();
+//! let data = cacache::async_get::read(&dir, "key").await.unwrap();
+//! assert_eq!(data, b"my-async-data");
+//! # })
+//! ```
 #![warn(missing_docs, missing_doc_code_examples)]
 
 pub use serde_json::Value;