docs: improve --help output for agent usability

Addresses all items from #491, plus one additional gap
found during a full help audit:

- canister settings update: fill in empty descriptions for
  --compute-allocation, --log-visibility, --add/remove/set-log-viewer,
  --add/remove-environment-variable; clarify that --log-visibility only
  accepts 'controllers'/'public', not 'allowed-viewers'
- canister settings show: fix description from "status" to "settings";
  fix "enviroment" typo; note no default-to-all behaviour
- canister status: document that omitting [CANISTER] queries all
  canisters in the environment; fix "enviroment" typo; add examples
- network start: document default port 8000, gateway.port config, and
  --project-root-override tip for port conflicts
- new: replace misleading template_values_file reference in --silent
  with accurate non-interactive/CI guidance; improve --define description
  to mention template-specific variable names and relationship to --silent
- canister list: document plain-text and JSON output formats
- environment list: fix "enviroments" typo; add context about icp project show
- cycles transfer: fix //// comment to /// so --from-subaccount gets a description
- cycles mint: document that exactly one of --icp or --cycles is required
- docs/reference/cli.md: regenerated

Author: marc0olo

crates/icp-cli/src/commands/canister/list.rs

@@ -6,7 +6,10 @@ use serde::Serialize;
 
 use crate::options::EnvironmentOpt;
 
-/// List the canisters in an environment
+/// List the canisters in an environment.
+///
+/// Prints canister names, one per line. Use --json for machine-readable output
+/// (returns {"canisters": ["name1", "name2", ...]})
 #[derive(Debug, Args)]
 pub(crate) struct ListArgs {
     #[command(flatten)]

crates/icp-cli/src/commands/canister/settings/show.rs

@@ -6,15 +6,16 @@ use crate::commands::{
     canister::status::{self, StatusArgs, StatusArgsOptions},
 };
 
-/// Show the status of a canister.
+/// Show the status of a canister, including its settings.
 ///
+/// A canister must always be specified (no default-to-all behaviour).
 /// By default this queries the status endpoint of the management canister.
 /// If the caller is not a controller, falls back on fetching public
 /// information from the state tree.
 #[derive(Debug, Args)]
 pub(crate) struct ShowArgs {
-    /// canister name or principal to target.
-    /// When using a name, an enviroment must be specified.
+    /// Canister name or principal to target.
+    /// When using a name, an environment must be specified.
     pub(crate) canister: args::Canister,
 
     #[command(flatten)]

crates/icp-cli/src/commands/canister/settings/update.rs

@@ -44,6 +44,9 @@ impl ControllerOpt {
 
 #[derive(Clone, Debug, Default, Args)]
 pub(crate) struct LogVisibilityOpt {
+    /// Set log visibility to a fixed policy [possible values: controllers, public].
+    /// Conflicts with --add-log-viewer, --remove-log-viewer, and --set-log-viewer.
+    /// Use --add-log-viewer / --set-log-viewer to grant access to specific principals instead.
     #[arg(
         long,
         value_parser = log_visibility_parser,
@@ -53,12 +56,15 @@ pub(crate) struct LogVisibilityOpt {
     )]
     log_visibility: Option<LogVisibility>,
 
+    /// Add a principal to the allowed log viewers list
     #[arg(long, action = ArgAction::Append, conflicts_with("set_log_viewer"))]
     add_log_viewer: Option<Vec<Principal>>,
 
+    /// Remove a principal from the allowed log viewers list
     #[arg(long, action = ArgAction::Append, conflicts_with("set_log_viewer"))]
     remove_log_viewer: Option<Vec<Principal>>,
 
+    /// Replace the allowed log viewers list with the specified principals
     #[arg(long, action = ArgAction::Append)]
     set_log_viewer: Option<Vec<Principal>>,
 }
@@ -71,9 +77,11 @@ impl LogVisibilityOpt {
 
 #[derive(Clone, Debug, Default, Args)]
 pub(crate) struct EnvironmentVariableOpt {
+    /// Add a canister environment variable in KEY=VALUE format
     #[arg(long, value_parser = environment_variable_parser, action = ArgAction::Append)]
     add_environment_variable: Option<Vec<EnvironmentVariable>>,
 
+    /// Remove a canister environment variable by key name
     #[arg(long, action = ArgAction::Append)]
     remove_environment_variable: Option<Vec<String>>,
 }
@@ -97,6 +105,7 @@ pub(crate) struct UpdateArgs {
     #[command(flatten)]
     controllers: Option<ControllerOpt>,
 
+    /// Compute allocation percentage (0-100). Represents a guaranteed share of a subnet's compute capacity.
     #[arg(long, value_parser = compute_allocation_parser)]
     compute_allocation: Option<u8>,
 

crates/icp-cli/src/commands/canister/status.rs

@@ -29,9 +29,25 @@ const E_NOT_A_CONTROLLER: &str = "IC0512";
 /// If the caller is not a controller, falls back on fetching public
 /// information from the state tree.
 #[derive(Debug, Args)]
+#[command(after_long_help = "\
+Examples:
+
+    # Status of all canisters in the local environment
+    icp canister status
+
+    # Status of one canister by name
+    icp canister status backend -e local
+
+    # Print only canister IDs (useful for scripting)
+    icp canister status -i
+
+    # JSON output for all canisters
+    icp canister status --json
+")]
 pub(crate) struct StatusArgs {
     /// An optional canister name or principal to target.
-    /// When using a name, an enviroment must be specified.
+    /// When using a name, an environment must be specified.
+    /// If omitted, shows status for all canisters in the environment.
     pub(crate) canister: Option<args::Canister>,
 
     #[command(flatten)]

crates/icp-cli/src/commands/cycles/mint.rs

@@ -11,7 +11,9 @@ use crate::commands::args::TokenCommandArgs;
 use crate::commands::parsers::parse_subaccount;
 use crate::operations::token::mint::mint_cycles;
 
-/// Convert icp to cycles
+/// Convert ICP to cycles.
+///
+/// Exactly one of --icp or --cycles must be provided.
 #[derive(Debug, Args)]
 pub(crate) struct MintArgs {
     /// Amount of ICP to mint to cycles.

crates/icp-cli/src/commands/cycles/transfer.rs

@@ -26,7 +26,7 @@ pub(crate) struct TransferArgs {
     #[arg(long, value_parser = parse_subaccount)]
     pub(crate) to_subaccount: Option<[u8; 32]>,
 
-    //// The subaccount to transfer from
+    /// The subaccount to transfer cycles from
     #[arg(long, value_parser = parse_subaccount)]
     pub(crate) from_subaccount: Option<[u8; 32]>,
 

crates/icp-cli/src/commands/environment/list.rs

@@ -1,7 +1,10 @@
 use clap::Args;
 use icp::context::Context;
 
-/// Display a list of enviroments
+/// List the environments defined in this project, one per line.
+///
+/// Use `icp project show` to see the fully expanded configuration including
+/// implicit environments (local, ic) and their network and canister assignments.
 #[derive(Args, Debug)]
 pub(crate) struct ListArgs;
 

crates/icp-cli/src/commands/network/start.rs

@@ -20,7 +20,13 @@ use tracing::{debug, info, warn};
 use super::args::NetworkOrEnvironmentArgs;
 use icp::context::Context;
 
-/// Run a given network
+/// Run a given network.
+///
+/// The gateway binds to port 8000 by default. To use a different port, set
+/// `gateway.port` in `icp.yaml`. If port 8000 is already in use by another
+/// icp-cli project, stop that network first:
+///
+///     icp network stop --project-root-override <path>
 #[derive(Args, Debug)]
 #[command(after_long_help = "\
 Examples:

crates/icp-cli/src/commands/new.rs

@@ -58,8 +58,10 @@ pub struct IcpGenerateArgs {
     #[arg(long, action)]
     pub continue_on_error: bool,
 
-    /// If silent mode is set all variables will be extracted from the template_values_file. If a
-    /// value is missing the project generation will fail
+    /// Non-interactive mode: suppresses all prompts. Unset variables fall back to their
+    /// template-defined defaults; generation fails if a required variable has no default.
+    /// Combine with --define to supply values for variables that have no default in the template.
+    /// Use for CI or automated/agent contexts.
     #[arg(long, short, requires("name"), action)]
     pub silent: bool,
 
@@ -77,7 +79,9 @@ pub struct IcpGenerateArgs {
     #[arg(long = "gitconfig", value_parser, value_name="GITCONFIG_FILE", help_heading = heading::GIT_PARAMETERS)]
     pub gitconfig: Option<PathBuf>,
 
-    /// Define a value for use during template expansion. E.g `--define foo=bar`
+    /// Set a template variable in KEY=VALUE format (e.g. --define project_name=my-app).
+    /// Variable names are template-specific. Suppresses the interactive prompt for that variable.
+    /// Required in --silent mode for any template variable that has no default value.
     #[arg(long, short, number_of_values = 1, value_parser, help_heading = heading::OUTPUT_PARAMETERS)]
     pub define: Vec<String>,
 

docs/reference/cli.md

@@ -314,7 +314,9 @@ Install a built WASM to a canister on a network
 
 ## `icp canister list`
 
-List the canisters in an environment
+List the canisters in an environment.
+
+Prints canister names, one per line. Use --json for machine-readable output (returns {"canisters": ["name1", "name2", ...]})
 
 **Usage:** `icp canister list [OPTIONS]`
 
@@ -406,23 +408,23 @@ Commands to manage canister settings
 
 ###### **Subcommands:**
 
-* `show` — Show the status of a canister
+* `show` — Show the status of a canister, including its settings
 * `update` — Change a canister's settings to specified values
 * `sync` — Synchronize a canister's settings with those defined in the project
 
 
 
 ## `icp canister settings show`
 
-Show the status of a canister.
+Show the status of a canister, including its settings.
 
-By default this queries the status endpoint of the management canister. If the caller is not a controller, falls back on fetching public information from the state tree.
+A canister must always be specified (no default-to-all behaviour). By default this queries the status endpoint of the management canister. If the caller is not a controller, falls back on fetching public information from the state tree.
 
 **Usage:** `icp canister settings show [OPTIONS] <CANISTER>`
 
 ###### **Arguments:**
 
-* `<CANISTER>` — canister name or principal to target. When using a name, an enviroment must be specified
+* `<CANISTER>` — Canister name or principal to target. When using a name, an environment must be specified
 
 ###### **Options:**
 
@@ -461,19 +463,19 @@ Change a canister's settings to specified values
 * `--set-controller <SET_CONTROLLER>` — Replace the canister's controller list with the specified principals.
 
    Warning: This removes all existing controllers not in the new list. If you don't include yourself, you will lose control of the canister.
-* `--compute-allocation <COMPUTE_ALLOCATION>`
+* `--compute-allocation <COMPUTE_ALLOCATION>` — Compute allocation percentage (0-100). Represents a guaranteed share of a subnet's compute capacity
 * `--memory-allocation <MEMORY_ALLOCATION>` — Memory allocation in bytes. Supports suffixes: kb, kib, mb, mib, gb, gib (e.g. "4gib" or "2.5kb")
 * `--freezing-threshold <FREEZING_THRESHOLD>` — Freezing threshold. Controls how long a canister can be inactive before being frozen. Supports duration suffixes: s (seconds), m (minutes), h (hours), d (days), w (weeks). A bare number is treated as seconds
 * `--reserved-cycles-limit <RESERVED_CYCLES_LIMIT>` — Upper limit on cycles reserved for future resource payments. Memory allocations that would push the reserved balance above this limit will fail. Supports suffixes: k (thousand), m (million), b (billion), t (trillion)
 * `--wasm-memory-limit <WASM_MEMORY_LIMIT>` — Wasm memory limit in bytes. Supports suffixes: kb, kib, mb, mib, gb, gib (e.g. "4gib" or "2.5kb")
 * `--wasm-memory-threshold <WASM_MEMORY_THRESHOLD>` — Wasm memory threshold in bytes. Supports suffixes: kb, kib, mb, mib, gb, gib (e.g. "4gib" or "2.5kb")
 * `--log-memory-limit <LOG_MEMORY_LIMIT>` — Log memory limit in bytes (max 2 MiB). Oldest logs are purged when usage exceeds this value. Supports suffixes: kb, kib, mb, mib (e.g. "2mib" or "256kib"). Canister default is 4096 bytes
-* `--log-visibility <LOG_VISIBILITY>`
-* `--add-log-viewer <ADD_LOG_VIEWER>`
-* `--remove-log-viewer <REMOVE_LOG_VIEWER>`
-* `--set-log-viewer <SET_LOG_VIEWER>`
-* `--add-environment-variable <ADD_ENVIRONMENT_VARIABLE>`
-* `--remove-environment-variable <REMOVE_ENVIRONMENT_VARIABLE>`
+* `--log-visibility <LOG_VISIBILITY>` — Set log visibility to a fixed policy [possible values: controllers, public]. Conflicts with --add-log-viewer, --remove-log-viewer, and --set-log-viewer. Use --add-log-viewer / --set-log-viewer to grant access to specific principals instead
+* `--add-log-viewer <ADD_LOG_VIEWER>` — Add a principal to the allowed log viewers list
+* `--remove-log-viewer <REMOVE_LOG_VIEWER>` — Remove a principal from the allowed log viewers list
+* `--set-log-viewer <SET_LOG_VIEWER>` — Replace the allowed log viewers list with the specified principals
+* `--add-environment-variable <ADD_ENVIRONMENT_VARIABLE>` — Add a canister environment variable in KEY=VALUE format
+* `--remove-environment-variable <REMOVE_ENVIRONMENT_VARIABLE>` — Remove a canister environment variable by key name
 * `--proxy <PROXY>` — Principal of a proxy canister to route the management canister calls through
 
 
@@ -678,9 +680,24 @@ By default this queries the status endpoint of the management canister. If the c
 
 **Usage:** `icp canister status [OPTIONS] [CANISTER]`
 
+Examples:
+
+    # Status of all canisters in the local environment
+    icp canister status
+
+    # Status of one canister by name
+    icp canister status backend -e local
+
+    # Print only canister IDs (useful for scripting)
+    icp canister status -i
+
+    # JSON output for all canisters
+    icp canister status --json
+
+
 ###### **Arguments:**
 
-* `<CANISTER>` — An optional canister name or principal to target. When using a name, an enviroment must be specified
+* `<CANISTER>` — An optional canister name or principal to target. When using a name, an environment must be specified. If omitted, shows status for all canisters in the environment
 
 ###### **Options:**
 
@@ -744,7 +761,7 @@ Mint and manage cycles
 ###### **Subcommands:**
 
 * `balance` — Display the cycles balance
-* `mint` — Convert icp to cycles
+* `mint` — Convert ICP to cycles
 * `transfer` — Transfer cycles to another principal
 
 
@@ -769,7 +786,9 @@ Display the cycles balance
 
 ## `icp cycles mint`
 
-Convert icp to cycles
+Convert ICP to cycles.
+
+Exactly one of --icp or --cycles must be provided.
 
 **Usage:** `icp cycles mint [OPTIONS]`
 
@@ -801,7 +820,7 @@ Transfer cycles to another principal
 ###### **Options:**
 
 * `--to-subaccount <TO_SUBACCOUNT>` — The subaccount to transfer to (only if the receiver is a principal)
-* `--from-subaccount <FROM_SUBACCOUNT>`
+* `--from-subaccount <FROM_SUBACCOUNT>` — The subaccount to transfer cycles from
 * `-n`, `--network <NETWORK>` — Name or URL of the network to target, conflicts with environment argument
 * `-k`, `--root-key <ROOT_KEY>` — The root key to use if connecting to a network by URL. Required when using `--network <URL>`
 * `-e`, `--environment <ENVIRONMENT>` — Override the environment to connect to. By default, the local environment is used
@@ -877,13 +896,15 @@ Show information about the current project environments
 
 ###### **Subcommands:**
 
-* `list` — Display a list of enviroments
+* `list` — List the environments defined in this project, one per line
 
 
 
 ## `icp environment list`
 
-Display a list of enviroments
+List the environments defined in this project, one per line.
+
+Use `icp project show` to see the fully expanded configuration including implicit environments (local, ic) and their network and canister assignments.
 
 **Usage:** `icp environment list`
 
@@ -1172,7 +1193,11 @@ Examples:
 
 ## `icp network start`
 
-Run a given network
+Run a given network.
+
+The gateway binds to port 8000 by default. To use a different port, set `gateway.port` in `icp.yaml`. If port 8000 is already in use by another icp-cli project, stop that network first:
+
+icp network stop --project-root-override <path>
 
 **Usage:** `icp network start [OPTIONS] [NAME]`
 
@@ -1328,11 +1353,11 @@ Under the hood templates are generated with `cargo-generate`. See the cargo-gene
 * `-f`, `--force` — Don't convert the project name to kebab-case before creating the directory. Note that `icp-cli` won't overwrite an existing directory, even if `--force` is given
 * `-q`, `--quiet` — Opposite of verbose, suppresses errors & warning in output Conflicts with --debug, and requires the use of --continue-on-error
 * `--continue-on-error` — Continue if errors in templates are encountered
-* `-s`, `--silent` — If silent mode is set all variables will be extracted from the template_values_file. If a value is missing the project generation will fail
+* `-s`, `--silent` — Non-interactive mode: suppresses all prompts. Unset variables fall back to their template-defined defaults; generation fails if a required variable has no default. Combine with --define to supply values for variables that have no default in the template. Use for CI or automated/agent contexts
 * `--vcs <VCS>` — Specify the VCS used to initialize the generated template
 * `-i`, `--identity <IDENTITY>` — Use a different ssh identity
 * `--gitconfig <GITCONFIG_FILE>` — Use a different gitconfig file, if omitted the usual $HOME/.gitconfig will be used
-* `-d`, `--define <DEFINE>` — Define a value for use during template expansion. E.g `--define foo=bar`
+* `-d`, `--define <DEFINE>` — Set a template variable in KEY=VALUE format (e.g. --define project_name=my-app). Variable names are template-specific. Suppresses the interactive prompt for that variable. Required in --silent mode for any template variable that has no default value
 * `--init` — Generate the template directly into the current dir. No subfolder will be created and no vcs is initialized
 * `--destination <PATH>` — Generate the template directly at the given path
 * `--force-git-init` — Will enforce a fresh git init on the generated project