diff --git a/hugr-cli/README.md b/hugr-cli/README.md
index dba9900e27..12024c98f3 100644
--- a/hugr-cli/README.md
+++ b/hugr-cli/README.md
@@ -24,20 +24,28 @@ cargo install hugr-cli
 This will install the `hugr` binary. Running `hugr --help` shows:
 
 ```
-Validate a HUGR.
+HUGR CLI tools.
 
-Usage: hugr [OPTIONS] <INPUT>
+Usage: hugr [OPTIONS] <COMMAND>
 
-Arguments:
-  <INPUT>
+Commands:
+  validate        Validate a HUGR package
+  gen-extensions  Write standard extensions out in serialized form
+  mermaid         Write HUGR as mermaid diagrams
+  convert         Convert between different HUGR envelope formats
+  help            Print this message or the help of the given subcommand(s)
 
 Options:
-  -m, --mermaid      Visualise with mermaid.
-  -n, --no-validate  Skip validation.
-  -v, --verbose...   Increase logging verbosity
-  -q, --quiet...     Decrease logging verbosity
-  -h, --help         Print help
-  -V, --version      Print version
+  -v, --verbose...  Increase logging verbosity
+  -q, --quiet...    Decrease logging verbosity
+  -h, --help        Print help
+  -V, --version     Print version
+```
+
+Refer to the help for each subcommand for more information, e.g.
+
+```
+hugr validate --help
 ```
 
 
diff --git a/hugr-cli/src/lib.rs b/hugr-cli/src/lib.rs
index 9e5e74ece8..1c68942e33 100644
--- a/hugr-cli/src/lib.rs
+++ b/hugr-cli/src/lib.rs
@@ -9,51 +9,14 @@
 //! directory](https://doc.rust-lang.org/book/ch14-04-installing-binaries.html)
 //! in your path.
 //!
-//! The CLI provides two subcommands:
-//!
-//! - `validate` for validating HUGR files.
-//! - `mermaid` for visualizing HUGR files as mermaid diagrams.
-//!
-//! ### Validate
-//!
-//! Validate and visualize a HUGR file
-//!
-//! Usage: `hugr validate [OPTIONS] [INPUT]`
-//!
-//! ```text
-//! Options:
-//!   -v, --verbose...  Increase logging verbosity
-//!   -q, --quiet...    Decrease logging verbosity
-//!   -h, --help        Print help (see more with '--help')
-//!   -V, --version     Print version
-//!
-//! Input:
-//!       --no-std                   Don't use standard extensions when validating hugrs. Prelude is still used.
-//!   -e, --extensions <EXTENSIONS>  Paths to serialised extensions to validate against.
-//!       --hugr-json                Read the input as a HUGR JSON file instead of an envelope
-//!   [INPUT]                    Input file. Defaults to `-` for stdin
+//! The top level help can be accessed with:
+//! ```sh
+//! hugr --help
 //! ```
 //!
-//! ### Mermaid
-//!
-//! Write HUGR as mermaid diagrams
-//!
-//! Usage: `hugr mermaid [OPTIONS] [INPUT]`
-//!
-//! ```text
-//! Options:
-//!       --validate         Validate before rendering, includes extension inference.
-//!   -o, --output <OUTPUT>  Output file '-' for stdout [default: -]
-//!   -v, --verbose...       Increase logging verbosity
-//!   -q, --quiet...         Decrease logging verbosity
-//!   -h, --help             Print help (see more with '--help')
-//!   -V, --version          Print version
-//!
-//! Input:
-//!       --no-std                   Don't use standard extensions when validating hugrs. Prelude is still used.
-//!   -e, --extensions <EXTENSIONS>  Paths to serialised extensions to validate against.
-//!       --hugr-json                Read the input as a HUGR JSON file instead of an envelope
-//!   [INPUT]                    Input file. Defaults to `-` for stdin.
+//! Refer to the help for each subcommand for more information, e.g.
+//! ```sh
+//! hugr validate --help
 //! ```
 
 use clap::{Parser, crate_version};
@@ -87,7 +50,7 @@ pub struct CliArgs {
 #[derive(Debug, clap::Subcommand)]
 #[non_exhaustive]
 pub enum CliCommand {
-    /// Validate and visualize a HUGR file.
+    /// Validate a HUGR package.
     Validate(validate::ValArgs),
     /// Write standard extensions out in serialized form.
     GenExtensions(extensions::ExtArgs),