diff --git a/CHANGELOG.md b/CHANGELOG.md index fced4c67..03346dd2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,7 @@ * feat: `icp canister logs` to display the current canister logs * use `--follow` to continuously poll for new logs. `--interval ` to poll every `n` seconds * feat: Support `k`, `m`, `b`, `t` suffixes in `.yaml` files when specifying cycles amounts +* feat: Add an optional root-key argument to canister commands # v0.1.0 diff --git a/crates/icp-cli/src/commands/args.rs b/crates/icp-cli/src/commands/args.rs index a955403c..9f771046 100644 --- a/crates/icp-cli/src/commands/args.rs +++ b/crates/icp-cli/src/commands/args.rs @@ -13,7 +13,7 @@ use crate::options::{EnvironmentOpt, IdentityOpt, NetworkOpt}; #[derive(Args, Debug)] pub(crate) struct CanisterCommandArgs { // Note: Could have flattened CanisterEnvironmentArg to avoid adding child field - /// Name or principal of canister to target + /// Name or principal of canister to target. /// When using a name an environment must be specified. pub(crate) canister: Canister, diff --git a/crates/icp-cli/src/options.rs b/crates/icp-cli/src/options.rs index 1754e1ac..54722beb 100644 --- a/crates/icp-cli/src/options.rs +++ b/crates/icp-cli/src/options.rs @@ -1,4 +1,5 @@ -use clap::{ArgGroup, Args}; +use clap::error::ErrorKind; +use clap::{ArgGroup, ArgMatches, Args, FromArgMatches}; use icp::context::{EnvironmentSelection, NetworkSelection}; use icp::identity::IdentitySelection; use icp::prelude::LOCAL; @@ -63,22 +64,114 @@ impl From for EnvironmentSelection { } } +#[derive(Clone, Debug)] +pub(crate) struct RootKey(pub Vec); + +fn parse_root_key(input: &str) -> Result { + let v = hex::decode(input).map_err(|e| format!("Invalid root key hex string: {e}"))?; + if v.len() != 133 { + Err(format!( + "Invalid root key. Expected 133 bytes but got {}", + v.len() + )) + } else { + Ok(RootKey(v)) + } +} + +#[derive(Clone, Debug)] +enum NetworkTarget { + Url(Url), + Named(String), +} + +fn parse_network_target(input: &str) -> Result { + match Url::parse(input) { + Ok(url) => Ok(NetworkTarget::Url(url)), + Err(_) => Ok(NetworkTarget::Named(input.to_string())), + } +} + #[derive(Args, Clone, Debug, Default)] #[clap(group(ArgGroup::new("network-select").multiple(false)))] -pub(crate) struct NetworkOpt { - /// Name of the network to target, conflicts with environment argument - #[arg(long, short = 'n', env = "ICP_NETWORK", group = "network-select", help_heading = heading::NETWORK_PARAMETERS)] - network: Option, +pub(crate) struct NetworkOptInner { + /// Name or URL of the network to target, conflicts with environment argument + #[arg(long, short = 'n', env = "ICP_NETWORK", group = "network-select", help_heading = heading::NETWORK_PARAMETERS, value_parser = parse_network_target)] + network: Option, + + /// The root key to use if connecting to a network by URL. + /// Required when using `--network `. + #[arg(long, short = 'k', requires = "network", help_heading = heading::NETWORK_PARAMETERS, value_parser = parse_root_key)] + root_key: Option, +} + +// This is wrapper around NetworkOptInner that will do some additional +// validation to only allow --root-key when the network is a url. +#[derive(Clone, Debug, Default)] +pub(crate) enum NetworkOpt { + Url(Url, RootKey), + + Name(String), + + #[default] + None, +} + +impl FromArgMatches for NetworkOpt { + fn from_arg_matches(matches: &ArgMatches) -> Result { + let inner = NetworkOptInner::from_arg_matches(matches)?; + + match (inner.network, inner.root_key) { + // Case: We have a URL, so we REQUIRE the root key + (Some(NetworkTarget::Url(url)), Some(key)) => Ok(NetworkOpt::Url(url, key)), + + // ERROR Case: URL provided but missing root key + (Some(NetworkTarget::Url(_)), None) => Err(clap::Error::raw( + ErrorKind::MissingRequiredArgument, + "`--root-key` is required when `--network` is a URL.\n", + )), + + // Case: Named network (root key should be empty) + (Some(NetworkTarget::Named(name)), None) => Ok(NetworkOpt::Name(name)), + + // ERROR case: Name provided with a root key + (Some(NetworkTarget::Named(_)), Some(_)) => Err(clap::Error::raw( + ErrorKind::ArgumentConflict, + "`--root-key` is only valid when `--network` is a URL.\n", + )), + + // Case: No network specified + (None, None) => Ok(NetworkOpt::None), + + // Case: Should be impossible, --root-key is passed without a network argument + (None, Some(_)) => { + panic!("Invalid cli arg combination: --root-key without a --network ") + } + } + } + + fn update_from_arg_matches(&mut self, matches: &ArgMatches) -> Result<(), clap::Error> { + // For simple wrappers, we can just replace the current state + *self = Self::from_arg_matches(matches)?; + Ok(()) + } +} + +impl Args for NetworkOpt { + fn augment_args(cmd: clap::Command) -> clap::Command { + NetworkOptInner::augment_args(cmd) + } + fn augment_args_for_update(cmd: clap::Command) -> clap::Command { + NetworkOptInner::augment_args_for_update(cmd) + } } impl From for NetworkSelection { fn from(v: NetworkOpt) -> Self { - match v.network { - Some(network) => match Url::parse(&network) { - Ok(url) => NetworkSelection::Url(url), - Err(_) => NetworkSelection::Named(network), - }, - None => NetworkSelection::Default, + match v { + NetworkOpt::Url(url, RootKey(key)) => NetworkSelection::Url(url, key), + NetworkOpt::Name(name) => NetworkSelection::Named(name), + NetworkOpt::None => NetworkSelection::Default, } } } diff --git a/crates/icp-cli/tests/canister_call_root_key_tests.rs b/crates/icp-cli/tests/canister_call_root_key_tests.rs new file mode 100644 index 00000000..8005fa25 --- /dev/null +++ b/crates/icp-cli/tests/canister_call_root_key_tests.rs @@ -0,0 +1,139 @@ +use indoc::formatdoc; +use predicates::ord::eq; +use predicates::str::{PredicateStrExt, contains}; + +use crate::common::{ENVIRONMENT_RANDOM_PORT, NETWORK_RANDOM_PORT, TestContext}; +use icp::fs::write_string; + +mod common; + +#[tokio::test] +async fn canister_call_with_url_and_root_key() { + let ctx = TestContext::new(); + + // Setup project + let project_dir = ctx.create_project_dir("icp"); + + // Use vendored WASM + let wasm = ctx.make_asset("example_icp_mo.wasm"); + + // Project manifest + let pm = formatdoc! {r#" + canisters: + - name: my-canister + build: + steps: + - type: script + command: cp '{wasm}' "$ICP_WASM_OUTPUT_PATH" + + {NETWORK_RANDOM_PORT} + {ENVIRONMENT_RANDOM_PORT} + "#}; + + write_string(&project_dir.join("icp.yaml"), &pm).expect("failed to write project manifest"); + + // Start network + let _g = ctx.start_network_in(&project_dir, "random-network").await; + ctx.ping_until_healthy(&project_dir, "random-network"); + + // Deploy canister + ctx.icp() + .current_dir(&project_dir) + .args([ + "deploy", + "my-canister", + "--environment", + "random-environment", + ]) + .assert() + .success(); + + // Test calling with Candid text format + ctx.icp() + .current_dir(&project_dir) + .args([ + "canister", + "call", + "--environment", + "random-environment", + "my-canister", + "greet", + "(\"world\")", + ]) + .assert() + .success() + .stdout(eq("(\"Hello, world!\")").trim()); + + // Get the network information so we can call the network directly + let assert = ctx + .icp() + .current_dir(&project_dir) + .args([ + "network", + "status", + "--environment", + "random-environment", + "--json", + ]) + .assert() + .success(); + let output = assert.get_output(); + + let json: serde_json::Value = serde_json::from_slice(&output.stdout).unwrap(); + let gateway_url = json["gateway_url"].as_str().expect("Should be a string"); + let root_key = json["root_key"].as_str().expect("Should be a string"); + + // Get the canister information so we can call the network directly + let assert = ctx + .icp() + .current_dir(&project_dir) + .args([ + "canister", + "status", + "--environment", + "random-environment", + "my-canister", + "--id-only", + ]) + .assert() + .success(); + + let output = assert.get_output(); + let canister_id = + String::from_utf8(output.stdout.clone()).expect("canister id should be a valid string"); + let canister_id = canister_id.trim(); + + // Test calling with with url from external directory + ctx.icp() + .args([ + "canister", + "call", + "--network", + gateway_url, + "--root-key", + root_key, + canister_id, + "greet", + "(\"world\")", + ]) + .assert() + .success() + .stdout(eq("(\"Hello, world!\")").trim()); + + // Test calling with with url from external directory with bad root key + ctx.icp() + .args([ + "canister", + "call", + "--network", + gateway_url, + "--root-key", + "badbadbad", // This is an invalid root key + canister_id, + "greet", + "(\"world\")", + ]) + .assert() + .failure() + .stderr(contains("invalid value 'badbadbad' for '--root-key")); +} diff --git a/crates/icp-cli/tests/cycles_tests.rs b/crates/icp-cli/tests/cycles_tests.rs index ef0fb208..fb4e21a6 100644 --- a/crates/icp-cli/tests/cycles_tests.rs +++ b/crates/icp-cli/tests/cycles_tests.rs @@ -2,7 +2,7 @@ use indoc::formatdoc; use predicates::str::contains; use crate::common::{ENVIRONMENT_RANDOM_PORT, NETWORK_RANDOM_PORT, TestContext, clients}; -use icp::{fs::write_string, prelude::IC_MAINNET_NETWORK_API_URL}; +use icp::fs::write_string; mod common; @@ -169,14 +169,7 @@ async fn cycles_mint_on_ic() { // Run mint command with --network ctx.icp() .current_dir(&project_dir) - .args([ - "cycles", - "mint", - "--icp", - "1", - "--network", - IC_MAINNET_NETWORK_API_URL, - ]) + .args(["cycles", "mint", "--icp", "1", "--network", "ic"]) .assert() .stderr(contains( "Error: Insufficient funds: 1.00010000 ICP required, 0 ICP available.", diff --git a/crates/icp/src/context/mod.rs b/crates/icp/src/context/mod.rs index b91ccece..f4bad7aa 100644 --- a/crates/icp/src/context/mod.rs +++ b/crates/icp/src/context/mod.rs @@ -31,7 +31,7 @@ pub enum NetworkSelection { /// Use a named network Named(String), /// Use a network by URL - Url(Url), + Url(Url, Vec), } /// Selection type for environments - similar to IdentitySelection @@ -180,13 +180,13 @@ impl Context { } } NetworkSelection::Default => Err(GetNetworkError::DefaultNetwork), - NetworkSelection::Url(url) => Ok(crate::Network { + NetworkSelection::Url(url, root_key) => Ok(crate::Network { name: url.to_string(), configuration: crate::network::Configuration::Connected { connected: crate::network::Connected { api_url: url.clone(), http_gateway_url: Some(url.clone()), - root_key: IC_ROOT_KEY.to_vec(), + root_key: root_key.to_vec(), }, }, }), @@ -402,7 +402,7 @@ impl Context { match (environment, network) { // Error: Both environment and network specified (EnvironmentSelection::Named(_), NetworkSelection::Named(_)) - | (EnvironmentSelection::Named(_), NetworkSelection::Url(_)) => { + | (EnvironmentSelection::Named(_), NetworkSelection::Url(_, _)) => { Err(GetAgentError::EnvironmentAndNetworkSpecified) } @@ -428,7 +428,7 @@ impl Context { // Network specified (EnvironmentSelection::Default, NetworkSelection::Named(_)) - | (EnvironmentSelection::Default, NetworkSelection::Url(_)) => { + | (EnvironmentSelection::Default, NetworkSelection::Url(_, _)) => { Ok(self.get_agent_for_network(identity, network).await?) } } @@ -446,13 +446,13 @@ impl Context { match (environment, network) { // Error: Both environment and network specified (EnvironmentSelection::Named(_), NetworkSelection::Named(_)) - | (EnvironmentSelection::Named(_), NetworkSelection::Url(_)) => { + | (EnvironmentSelection::Named(_), NetworkSelection::Url(_, _)) => { Err(GetCanisterIdError::CanisterEnvironmentAndNetworkSpecified) } // Error: Canister by name with explicit network but no environment (EnvironmentSelection::Default, NetworkSelection::Named(_)) - | (EnvironmentSelection::Default, NetworkSelection::Url(_)) => { + | (EnvironmentSelection::Default, NetworkSelection::Url(_, _)) => { Err(GetCanisterIdError::AmbiguousCanisterName) } diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 69d8e119..9a12c2a7 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -144,7 +144,7 @@ Make a canister call ###### **Arguments:** -* `` — Name or principal of canister to target When using a name an environment must be specified +* `` — Name or principal of canister to target. When using a name an environment must be specified * `` — Name of canister method to call into * `` — Canister call arguments. Can be: @@ -158,7 +158,8 @@ Make a canister call ###### **Options:** -* `-n`, `--network ` — Name of the network to target, conflicts with environment argument +* `-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 * `--identity ` — The user identity to run this command as * `--proxy ` — Principal of a proxy canister to route the call through. @@ -183,11 +184,12 @@ Create a canister on a network ###### **Arguments:** -* `` — Name or principal of canister to target When using a name an environment must be specified +* `` — Name or principal of canister to target. When using a name an environment must be specified ###### **Options:** -* `-n`, `--network ` — Name of the network to target, conflicts with environment argument +* `-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 * `--identity ` — The user identity to run this command as * `--controller ` — One or more controllers for the canister. Repeat `--controller` to specify multiple @@ -211,11 +213,12 @@ Delete a canister from a network ###### **Arguments:** -* `` — Name or principal of canister to target When using a name an environment must be specified +* `` — Name or principal of canister to target. When using a name an environment must be specified ###### **Options:** -* `-n`, `--network ` — Name of the network to target, conflicts with environment argument +* `-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 * `--identity ` — The user identity to run this command as @@ -229,7 +232,7 @@ Install a built WASM to a canister on a network ###### **Arguments:** -* `` — Name or principal of canister to target When using a name an environment must be specified +* `` — Name or principal of canister to target. When using a name an environment must be specified ###### **Options:** @@ -247,7 +250,8 @@ Install a built WASM to a canister on a network - Candid text format (e.g., `(42)` or `(record { name = "Alice" })`) - File path (e.g., `args.txt` or `./path/to/args.candid`) The file should contain either hex or Candid format arguments. -* `-n`, `--network ` — Name of the network to target, conflicts with environment argument +* `-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 * `--identity ` — The user identity to run this command as @@ -273,11 +277,12 @@ Fetch and display canister logs ###### **Arguments:** -* `` — Name or principal of canister to target When using a name an environment must be specified +* `` — Name or principal of canister to target. When using a name an environment must be specified ###### **Options:** -* `-n`, `--network ` — Name of the network to target, conflicts with environment argument +* `-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 * `--identity ` — The user identity to run this command as * `-f`, `--follow` — Continuously fetch and display new logs until interrupted with Ctrl+C @@ -295,12 +300,13 @@ Read a metadata section from a canister ###### **Arguments:** -* `` — Name or principal of canister to target When using a name an environment must be specified +* `` — Name or principal of canister to target. When using a name an environment must be specified * `` — The name of the metadata section to read ###### **Options:** -* `-n`, `--network ` — Name of the network to target, conflicts with environment argument +* `-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 * `--identity ` — The user identity to run this command as @@ -314,11 +320,12 @@ Migrate a canister ID from one subnet to another ###### **Arguments:** -* `` — Name or principal of canister to target When using a name an environment must be specified +* `` — Name or principal of canister to target. When using a name an environment must be specified ###### **Options:** -* `-n`, `--network ` — Name of the network to target, conflicts with environment argument +* `-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 * `--identity ` — The user identity to run this command as * `--replace ` — The canister to replace with the source canister's ID @@ -356,7 +363,8 @@ By default this queries the status endpoint of the management canister. If the c ###### **Options:** -* `-n`, `--network ` — Name of the network to target, conflicts with environment argument +* `-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 * `--identity ` — The user identity to run this command as * `-i`, `--id-only` — Only print the canister ids @@ -373,11 +381,12 @@ Change a canister's settings to specified values ###### **Arguments:** -* `` — Name or principal of canister to target When using a name an environment must be specified +* `` — Name or principal of canister to target. When using a name an environment must be specified ###### **Options:** -* `-n`, `--network ` — Name of the network to target, conflicts with environment argument +* `-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 * `--identity ` — The user identity to run this command as * `-f`, `--force` — Force the operation without confirmation prompts @@ -411,11 +420,12 @@ Synchronize a canister's settings with those defined in the project ###### **Arguments:** -* `` — Name or principal of canister to target When using a name an environment must be specified +* `` — Name or principal of canister to target. When using a name an environment must be specified ###### **Options:** -* `-n`, `--network ` — Name of the network to target, conflicts with environment argument +* `-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 * `--identity ` — The user identity to run this command as @@ -446,11 +456,12 @@ Create a snapshot of a canister's state ###### **Arguments:** -* `` — Name or principal of canister to target When using a name an environment must be specified +* `` — Name or principal of canister to target. When using a name an environment must be specified ###### **Options:** -* `-n`, `--network ` — Name of the network to target, conflicts with environment argument +* `-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 * `--identity ` — The user identity to run this command as * `--replace ` — Replace an existing snapshot instead of creating a new one. The old snapshot will be deleted once the new one is successfully created @@ -465,12 +476,13 @@ Delete a canister snapshot ###### **Arguments:** -* `` — Name or principal of canister to target When using a name an environment must be specified +* `` — Name or principal of canister to target. When using a name an environment must be specified * `` — The snapshot ID to delete (hex-encoded) ###### **Options:** -* `-n`, `--network ` — Name of the network to target, conflicts with environment argument +* `-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 * `--identity ` — The user identity to run this command as @@ -484,12 +496,13 @@ Download a snapshot to local disk ###### **Arguments:** -* `` — Name or principal of canister to target When using a name an environment must be specified +* `` — Name or principal of canister to target. When using a name an environment must be specified * `` — The snapshot ID to download (hex-encoded) ###### **Options:** -* `-n`, `--network ` — Name of the network to target, conflicts with environment argument +* `-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 * `--identity ` — The user identity to run this command as * `-o`, `--output ` — Output directory for the snapshot files @@ -505,11 +518,12 @@ List all snapshots for a canister ###### **Arguments:** -* `` — Name or principal of canister to target When using a name an environment must be specified +* `` — Name or principal of canister to target. When using a name an environment must be specified ###### **Options:** -* `-n`, `--network ` — Name of the network to target, conflicts with environment argument +* `-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 * `--identity ` — The user identity to run this command as @@ -523,12 +537,13 @@ Restore a canister from a snapshot ###### **Arguments:** -* `` — Name or principal of canister to target When using a name an environment must be specified +* `` — Name or principal of canister to target. When using a name an environment must be specified * `` — The snapshot ID to restore (hex-encoded) ###### **Options:** -* `-n`, `--network ` — Name of the network to target, conflicts with environment argument +* `-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 * `--identity ` — The user identity to run this command as @@ -542,11 +557,12 @@ Upload a snapshot from local disk ###### **Arguments:** -* `` — Name or principal of canister to target When using a name an environment must be specified +* `` — Name or principal of canister to target. When using a name an environment must be specified ###### **Options:** -* `-n`, `--network ` — Name of the network to target, conflicts with environment argument +* `-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 * `--identity ` — The user identity to run this command as * `-i`, `--input ` — Input directory containing the snapshot files @@ -563,11 +579,12 @@ Start a canister on a network ###### **Arguments:** -* `` — Name or principal of canister to target When using a name an environment must be specified +* `` — Name or principal of canister to target. When using a name an environment must be specified ###### **Options:** -* `-n`, `--network ` — Name of the network to target, conflicts with environment argument +* `-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 * `--identity ` — The user identity to run this command as @@ -587,7 +604,8 @@ By default this queries the status endpoint of the management canister. If the c ###### **Options:** -* `-n`, `--network ` — Name of the network to target, conflicts with environment argument +* `-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 * `--identity ` — The user identity to run this command as * `-i`, `--id-only` — Only print the canister ids @@ -604,11 +622,12 @@ Stop a canister on a network ###### **Arguments:** -* `` — Name or principal of canister to target When using a name an environment must be specified +* `` — Name or principal of canister to target. When using a name an environment must be specified ###### **Options:** -* `-n`, `--network ` — Name of the network to target, conflicts with environment argument +* `-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 * `--identity ` — The user identity to run this command as @@ -622,12 +641,13 @@ Top up a canister with cycles ###### **Arguments:** -* `` — Name or principal of canister to target When using a name an environment must be specified +* `` — Name or principal of canister to target. When using a name an environment must be specified ###### **Options:** * `--amount ` — Amount of cycles to top up. Supports suffixes: k (thousand), m (million), b (billion), t (trillion) -* `-n`, `--network ` — Name of the network to target, conflicts with environment argument +* `-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 * `--identity ` — The user identity to run this command as @@ -655,7 +675,8 @@ Display the cycles balance ###### **Options:** -* `-n`, `--network ` — Name of the network to target, conflicts with environment argument +* `-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 * `--identity ` — The user identity to run this command as * `--subaccount ` — The subaccount to check the balance for @@ -674,7 +695,8 @@ Convert icp to cycles * `--cycles ` — Amount of cycles to mint. Automatically determines the amount of ICP needed. Supports suffixes: k (thousand), m (million), b (billion), t (trillion) * `--from-subaccount ` — Subaccount to withdraw the ICP from * `--to-subaccount ` — Subaccount to deposit the cycles to -* `-n`, `--network ` — Name of the network to target, conflicts with environment argument +* `-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 * `--identity ` — The user identity to run this command as @@ -695,7 +717,8 @@ Transfer cycles to another principal * `--to-subaccount ` — The subaccount to transfer to (only if the receiver is a principal) * `--from-subaccount ` -* `-n`, `--network ` — Name of the network to target, conflicts with environment argument +* `-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 * `--identity ` — The user identity to run this command as @@ -1280,7 +1303,8 @@ Display the token balance on the ledger (default token: icp) ###### **Options:** -* `-n`, `--network ` — Name of the network to target, conflicts with environment argument +* `-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 * `--identity ` — The user identity to run this command as * `--subaccount ` — The subaccount to check the balance for @@ -1302,7 +1326,8 @@ Transfer ICP or ICRC1 tokens through their ledger (default token: icp) * `--to-subaccount ` — The subaccount to transfer to (only if the receiver is a principal) * `--from-subaccount ` — The subaccount to transfer from -* `-n`, `--network ` — Name of the network to target, conflicts with environment argument +* `-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 * `--identity ` — The user identity to run this command as