feat: Implement shell completions (#697)

Author: adamspofford

CHANGELOG.md

@@ -7,6 +7,7 @@ bump. Currently experimental: project bundling, project dependencies
 
 # Unreleased
 
+* feat: `icp completions <SHELL>` prints a shell completion script for `bash`, `zsh`, `fish`, `powershell`, or `elvish` to stdout. See the [installation guide](docs/guides/installation.md#shell-completions) for where to put it.
 * fix: `icp canister logs` output formats are corrected. `--json` now emits machine-readable JSON and the default emits the human-readable lines (the two were swapped), and `--follow --json` emits newline-delimited JSON, one record per line, streamed as each record arrives. This is breaking for scripts: parsing the default output as JSON now requires `--json`, and consumers of `--follow --json` must read one JSON object per line.
 
 # v1.3.0

Cargo.lock

@@ -34,8 +34,9 @@ cargo-generate = "0.23.7"
 camino-tempfile = "1"
 candid = "0.10.19"
 candid_parser = "0.3.0"
-clap = { version = "4.5.3", features = ["derive", "env"] }
+clap = { version = "4.5.3", features = ["derive", "env", "unstable-ext"] }
 clap-markdown = "0.1.5"
+clap_complete = { version = "4.5.3", features = ["unstable-dynamic"] }
 cryptoki = "0.12.0"
 console = "0.16.3"
 dialoguer = "0.12.0"

Cargo.toml

@@ -28,6 +28,7 @@ candid.workspace = true
 cargo-generate.workspace = true
 clap-markdown.workspace = true
 clap.workspace = true
+clap_complete.workspace = true
 dialoguer.workspace = true
 dunce.workspace = true
 elliptic-curve.workspace = true
@@ -45,6 +46,7 @@ icp-canister-interfaces.workspace = true
 icp = { workspace = true, features = ["clap"] }
 icrc-ledger-types.workspace = true
 indicatif.workspace = true
+indoc.workspace = true
 itertools.workspace = true
 k256.workspace = true
 lazy_static.workspace = true
@@ -85,7 +87,6 @@ cargo-generate = { workspace = true, features = ["vendored-openssl"] }
 assert_cmd.workspace = true
 camino-tempfile.workspace = true
 cryptoki.workspace = true
-indoc.workspace = true
 predicates.workspace = true
 rand.workspace = true
 send_ctrlc.workspace = true

crates/icp-cli/Cargo.toml

@@ -3,7 +3,8 @@ use std::str::FromStr;
 
 use anyhow::{Context as _, bail};
 use candid::Principal;
-use clap::Args;
+use clap::{Args, ValueHint};
+use clap_complete::ArgValueCandidates;
 use ic_ledger_types::AccountIdentifier;
 use icp::context::{CanisterSelection, EnvironmentSelection, NetworkSelection};
 use icp::identity::IdentitySelection;
@@ -27,6 +28,7 @@ pub(crate) struct CanisterCommandArgs {
     // Note: Could have flattened CanisterEnvironmentArg to avoid adding child field
     /// Name or principal of canister to target.
     /// When using a name an environment must be specified.
+    #[arg(add = ArgValueCandidates::new(crate::complete::canisters))]
     pub(crate) canister: Canister,
 
     #[command(flatten)]
@@ -87,6 +89,7 @@ impl OptionalCanisterCommandArgs {
 pub(crate) struct OptionalCanisterCommandArgs {
     /// Name or principal of canister to target.
     /// When using a name an environment must be specified.
+    #[arg(add = ArgValueCandidates::new(crate::complete::canisters))]
     pub(crate) canister: Option<Canister>,
 
     #[command(flatten)]
@@ -216,7 +219,7 @@ pub(crate) struct ArgsOpt {
     pub(crate) args: Option<String>,
 
     /// Path to a file containing arguments.
-    #[arg(long, conflicts_with = "args")]
+    #[arg(long, conflicts_with = "args", value_hint = ValueHint::FilePath)]
     pub(crate) args_file: Option<PathBuf>,
 
     /// Format of the arguments.

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

@@ -1,4 +1,5 @@
 use clap::Args;
+use clap_complete::ArgValueCandidates;
 use futures::future::try_join_all;
 use icp::context::{Context, EnvironmentSelection};
 
@@ -10,6 +11,7 @@ use crate::{operations::build::build_many_with_progress_bar, options::Environmen
 #[derive(Debug, Args)]
 pub(crate) struct BuildArgs {
     /// Canister names (if empty, build all canisters in environment)
+    #[arg(add = ArgValueCandidates::new(crate::complete::canisters))]
     pub(crate) canisters: Vec<String>,
 
     #[command(flatten)]

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

@@ -4,7 +4,7 @@ use candid::{IDLArgs, Principal, TypeEnv, types::Function};
 use candid_parser::assist;
 use candid_parser::parse_idl_args;
 use candid_parser::utils::CandidSource;
-use clap::{Args, ValueEnum};
+use clap::{Args, ValueEnum, ValueHint};
 use dialoguer::console::Term;
 use ic_agent::Agent;
 use icp::context::Context;
@@ -51,7 +51,7 @@ pub(crate) struct CallArgs {
     pub(crate) args: Option<String>,
 
     /// Path to a file containing call arguments.
-    #[arg(long, conflicts_with = "args")]
+    #[arg(long, conflicts_with = "args", value_hint = ValueHint::FilePath)]
     pub(crate) args_file: Option<PathBuf>,
 
     /// Format of the call arguments.
@@ -63,7 +63,7 @@ pub(crate) struct CallArgs {
     /// When set, this interface is used to assist method selection, build
     /// arguments, and decode the response, instead of fetching the canister's
     /// Candid interface from the network.
-    #[arg(long, value_name = "PATH")]
+    #[arg(long, value_name = "PATH", value_hint = ValueHint::FilePath)]
     pub(crate) candid: Option<PathBuf>,
 
     /// Principal of a proxy canister to route the call through.

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

@@ -2,7 +2,7 @@ use std::io::IsTerminal;
 
 use anyhow::{Context as _, anyhow, bail};
 use candid::Principal;
-use clap::Args;
+use clap::{Args, ValueHint};
 use dialoguer::Confirm;
 use ic_management_canister_types::CanisterInstallMode;
 use icp::context::{CanisterSelection, Context};
@@ -42,7 +42,7 @@ pub(crate) struct InstallArgs {
     pub(crate) wasm_memory_persistence: Option<WasmMemoryPersistenceOpt>,
 
     /// Path to the WASM file to install. Uses the build output if not explicitly provided.
-    #[arg(long)]
+    #[arg(long, value_hint = ValueHint::FilePath)]
     pub(crate) wasm: Option<PathBuf>,
 
     #[command(flatten)]

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

@@ -1,6 +1,7 @@
 use anyhow::bail;
 use candid::Principal;
 use clap::Args;
+use clap_complete::ArgValueCandidates;
 use icp::context::{Context, EnvironmentSelection};
 use tracing::info;
 
@@ -15,6 +16,7 @@ use crate::options::EnvironmentOpt;
 pub(crate) struct LinkArgs {
     /// Name of the project canister to associate the ID with.
     /// Must be declared in the target environment.
+    #[arg(add = ArgValueCandidates::new(crate::complete::canisters))]
     pub(crate) name: String,
 
     /// Principal of the existing canister to link.

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

@@ -3,6 +3,7 @@ use std::time::{Duration, Instant};
 
 use anyhow::bail;
 use clap::Args;
+use clap_complete::ArgValueCandidates;
 use dialoguer::Confirm;
 use ic_management_canister_types::{
     CanisterIdRecord, CanisterSettings, CanisterStatusType, UpdateSettingsArgs,
@@ -33,7 +34,7 @@ pub(crate) struct MigrateIdArgs {
     pub(crate) cmd_args: args::CanisterCommandArgs,
 
     /// The canister to replace with the source canister's ID
-    #[arg(long)]
+    #[arg(long, add = ArgValueCandidates::new(crate::complete::canisters))]
     replace: String,
 
     /// Skip confirmation prompts