diff --git a/crates/icp-cli/src/commands/canister/list.rs b/crates/icp-cli/src/commands/canister/list.rs index f56b3f20..e2af589e 100644 --- a/crates/icp-cli/src/commands/canister/list.rs +++ b/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)] diff --git a/crates/icp-cli/src/commands/canister/settings/show.rs b/crates/icp-cli/src/commands/canister/settings/show.rs index beada3c2..6aea9e5e 100644 --- a/crates/icp-cli/src/commands/canister/settings/show.rs +++ b/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)] diff --git a/crates/icp-cli/src/commands/canister/settings/update.rs b/crates/icp-cli/src/commands/canister/settings/update.rs index 46c8a5f5..83559cb6 100644 --- a/crates/icp-cli/src/commands/canister/settings/update.rs +++ b/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, + /// Add a principal to the allowed log viewers list #[arg(long, action = ArgAction::Append, conflicts_with("set_log_viewer"))] add_log_viewer: Option>, + /// Remove a principal from the allowed log viewers list #[arg(long, action = ArgAction::Append, conflicts_with("set_log_viewer"))] remove_log_viewer: Option>, + /// Replace the allowed log viewers list with the specified principals #[arg(long, action = ArgAction::Append)] set_log_viewer: Option>, } @@ -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>, + /// Remove a canister environment variable by key name #[arg(long, action = ArgAction::Append)] remove_environment_variable: Option>, } @@ -97,6 +105,7 @@ pub(crate) struct UpdateArgs { #[command(flatten)] controllers: Option, + /// 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, diff --git a/crates/icp-cli/src/commands/canister/status.rs b/crates/icp-cli/src/commands/canister/status.rs index 18412e1c..dd35f1ef 100644 --- a/crates/icp-cli/src/commands/canister/status.rs +++ b/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, #[command(flatten)] diff --git a/crates/icp-cli/src/commands/cycles/mint.rs b/crates/icp-cli/src/commands/cycles/mint.rs index 901598d0..4af29ddb 100644 --- a/crates/icp-cli/src/commands/cycles/mint.rs +++ b/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. diff --git a/crates/icp-cli/src/commands/cycles/transfer.rs b/crates/icp-cli/src/commands/cycles/transfer.rs index 00ae0a8c..4e31bc6f 100644 --- a/crates/icp-cli/src/commands/cycles/transfer.rs +++ b/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]>, diff --git a/crates/icp-cli/src/commands/environment/list.rs b/crates/icp-cli/src/commands/environment/list.rs index 13dfcf47..816aebdf 100644 --- a/crates/icp-cli/src/commands/environment/list.rs +++ b/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; diff --git a/crates/icp-cli/src/commands/network/start.rs b/crates/icp-cli/src/commands/network/start.rs index 55c8e6d0..0ce12260 100644 --- a/crates/icp-cli/src/commands/network/start.rs +++ b/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 #[derive(Args, Debug)] #[command(after_long_help = "\ Examples: diff --git a/crates/icp-cli/src/commands/new.rs b/crates/icp-cli/src/commands/new.rs index 0f8a5de6..3b7fe553 100644 --- a/crates/icp-cli/src/commands/new.rs +++ b/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, - /// 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, diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 22562467..09a0401a 100644 --- a/docs/reference/cli.md +++ b/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,7 +408,7 @@ 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 @@ -414,15 +416,15 @@ Commands to manage canister settings ## `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] ` ###### **Arguments:** -* `` — 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 ###### **Options:** @@ -461,19 +463,19 @@ Change a canister's settings to specified values * `--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 percentage (0-100). Represents a guaranteed share of a subnet's compute capacity * `--memory-allocation ` — Memory allocation in bytes. Supports suffixes: kb, kib, mb, mib, gb, gib (e.g. "4gib" or "2.5kb") * `--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 ` — 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 in bytes. Supports suffixes: kb, kib, mb, mib, gb, gib (e.g. "4gib" or "2.5kb") * `--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 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 ` -* `--add-log-viewer ` -* `--remove-log-viewer ` -* `--set-log-viewer ` -* `--add-environment-variable ` -* `--remove-environment-variable ` +* `--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 a principal to the allowed log viewers list +* `--remove-log-viewer ` — Remove a principal from the allowed log viewers list +* `--set-log-viewer ` — Replace the allowed log viewers list with the specified principals +* `--add-environment-variable ` — Add a canister environment variable in KEY=VALUE format +* `--remove-environment-variable ` — Remove a canister environment variable by key name * `--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:** -* `` — An optional canister name or principal to target. When using a name, an enviroment must be specified +* `` — 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 ` — The subaccount to transfer to (only if the receiver is a principal) -* `--from-subaccount ` +* `--from-subaccount ` — The subaccount to transfer cycles from * `-n`, `--network ` — Name or URL of the network to target, conflicts with environment argument * `-k`, `--root-key ` — The root key to use if connecting to a network by URL. Required when using `--network ` * `-e`, `--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 **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 ` — Specify the VCS used to initialize the generated template * `-i`, `--identity ` — Use a different ssh identity * `--gitconfig ` — Use a different gitconfig file, if omitted the usual $HOME/.gitconfig will be used -* `-d`, `--define ` — Define a value for use during template expansion. E.g `--define foo=bar` +* `-d`, `--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 ` — Generate the template directly at the given path * `--force-git-init` — Will enforce a fresh git init on the generated project