docs: Add usage info to hugr-cli's rustdocs

hugr-cli/src/lib.rs

@@ -1,4 +1,60 @@
-//! Standard command line tools, used by the hugr binary.
+//! Standard command line tools for the HUGR format.
+//!
+//! This library provides utilities for the HUGR CLI.
+//!
+//! ## CLI Usage
+//!
+//! Run `cargo install hugr-cli` to install the CLI tools. This will make the
+//! `hugr` executable available in your shell as long as you have [cargo's bin
+//! 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
+//! ```
+//!
+//! ### 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.
+//! ```
 
 use clap::{crate_version, Parser};
 use clap_verbosity_flag::log::Level;