feat: operations, argument validation, and args for global mode by rikonor · Pull Request #148 · dfinity/icp-cli

rikonor · 2025-10-17T03:14:34Z

This change introduces a few new things:

Begins the separation of commands and operations. Commands act as an entrypoint for the cli, and in turn make use of lower-level operations that don't require knowledge of icp projects. This allows us to:
Introduce global and project mode - this means that one should be able to run the cli tool in both project context, as well as outside of a project. This enables one to use operations that should not necessarily be limited to a project's scope.
Introduce a crappy little framework for cli command validation, since more extensive validation is needed (e.g some things are allowed in global mode, but not project mode, and vice-versa).

The above are done for several initial commands, with the assumption that the same work can take place for the rest of the cli footprint (currently global mode and arg validation is implemented for icp canister start/stop and token transfer/balance).

viviveevee · 2025-10-21T07:21:16Z

+            // Argument (Canister)
+            let args::Canister::Name(name) = &args.canister else {
+                return Err(CommandError::Args);
+            };


I don't think we should forbid using principals in projects. Otherwise to talk to a specific canister on a non-default network one has to somehow hook up the principal to a name just for one-off calls

Alternate suggestion: #157

viviveevee · 2025-10-21T07:21:51Z


            // Ensure canister is included in the environment
-            if !env.canisters.contains_key(&args.name) {
+            if !env.canisters.contains_key(name) {


Similarly, this should probably only happen if a non-principal was supplied

viviveevee · 2025-10-21T07:25:06Z

+    #[error("an invalid argument was provided")]
+    Args,


I don't think this is enough detail to give a decent user experience. It's ok to leave this as-is, but at least make a ticket to improve the situation. We can easily say 'only provide one of network and environment, not both' here

viviveevee · 2025-10-21T07:41:12Z

+    // #[cfg(test)]
+    // pub(crate) trait IntoOptions<T> {
+    //     fn into_options(self) -> Vec<Option<T>>;
+    // }
+
+    // #[cfg(test)]
+    // impl<T> IntoOptions<T> for Vec<T> {
+    //     fn into_options(self) -> Vec<Option<T>> {
+    //         self.into_iter().fold(vec![None], |mut acc, cur| {
+    //             acc.push(Some(cur));
+    //             acc
+    //         })
+    //     }
+    // }
+
+    pub(crate) fn all_modes() -> Vec<Mode> {
+        vec![Mode::Global, Mode::Project("dir".into())]
+    }
+
+    // pub(crate) fn all_networks() -> Vec<args::Network> {
+    //     vec![
+    //         args::Network::Name("my-network".to_string()),
+    //         args::Network::Url("http::/www.example.com".to_string()),
+    //     ]
+    // }


Suggested change

// #[cfg(test)]

// pub(crate) trait IntoOptions<T> {

// fn into_options(self) -> Vec<Option<T>>;

// }

// #[cfg(test)]

// impl<T> IntoOptions<T> for Vec<T> {

// fn into_options(self) -> Vec<Option<T>> {

// self.into_iter().fold(vec![None], |mut acc, cur| {

// acc.push(Some(cur));

// acc

// })

// }

// }

pub(crate) fn all_modes() -> Vec<Mode> {

vec![Mode::Global, Mode::Project("dir".into())]

}

// pub(crate) fn all_networks() -> Vec<args::Network> {

// vec![

// args::Network::Name("my-network".to_string()),

// args::Network::Url("http::/www.example.com".to_string()),

// ]

// }

pub(crate) fn all_modes() -> Vec<Mode> {

vec![Mode::Global, Mode::Project("dir".into())]

}

viviveevee · 2025-10-21T07:43:53Z

+}
+
+const PLEASE_PROVIDE_A_CANISTER_PRINCIPAL_IN_GLOBAL_MODE: &str = r#"
+    Please provide a canister principal in global mode.


Not convinced this is the best wording. global mode makes me think of a flag that I could use to switch to local mode.

Suggested change

Please provide a canister principal in global mode.

{user_provided_string} is not a principal. Cannot use non-principals outside of a project.

viviveevee · 2025-10-21T07:44:23Z

+}
+
+const ENVIRONMENTS_ARE_NOT_AVAILABLE_IN_GLOBAL_MODE: &str = r#"
+    Environments are not available in global mode.


Suggested change

Environments are not available in global mode.

Environments are not available in outside of projects.

viviveevee · 2025-10-21T07:44:59Z

+}
+
+const A_NETWORK_URL_IS_REQUIRED_IN_GLOBAL_MODE: &str = r#"
+    A network `url` is required in global mode.


Suggested change

A network `url` is required in global mode.

A network `url` is required outside of a project.

raymondk · 2025-10-30T16:16:08Z

We moved away from this approach because it uses icp.yaml to decide the mode. Instead of adopted an approach where we decide the mode based on the command and arguments provided.

rikonor added 9 commits October 16, 2025 21:39

add args and update canister start to use canister arg

25adb3f

update canister commands to use pub(crate)

39723fe

update the rest of the commands to use pub(crate)

d991c25

update canister commands to use canister arg type

0c3cdf6

add operations module

95282e5

thread op initializers through context

54577ba

prep conversion of canister start and stop commands to use operations

987751a

add macros for arg validation and some arg validation functions

123aa1e

impl validation on canister start

8730f90

rikonor self-assigned this Oct 17, 2025

rikonor added 6 commits October 20, 2025 10:03

Merge branch 'main' into or-args

e5f8b14

Merge branch 'main' into or-args

291957b

temporary commenting of code

452bdf1

small fixes

3c26ac9

load project explicitly via directory path

33b4b0b

implement global mode for canister start command

dc568e1

rikonor force-pushed the or-args branch 2 times, most recently from 18028ae to 23ca480 Compare October 20, 2025 15:48

use environment arg

8d01a5a

rikonor force-pushed the or-args branch from 23ca480 to 8d01a5a Compare October 20, 2025 15:52

Merge branch 'main' into or-args

523d352

rikonor force-pushed the or-args branch from 92d1f4e to 523d352 Compare October 20, 2025 16:02

rikonor added 3 commits October 20, 2025 12:03

add arg validation for canister stop

213f01a

impl global mode for token transfer and balance

f16e21e

removing test

e8b2613

rikonor force-pushed the or-args branch from d74a18d to e8b2613 Compare October 20, 2025 16:22

update docs

429126f

rikonor marked this pull request as ready for review October 20, 2025 16:27

rikonor requested a review from a team as a code owner October 20, 2025 16:27

viviveevee approved these changes Oct 21, 2025

View reviewed changes

raymondk marked this pull request as draft October 23, 2025 18:47

raymondk closed this Oct 30, 2025

raymondk deleted the or-args branch February 24, 2026 21:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: operations, argument validation, and args for global mode#148

feat: operations, argument validation, and args for global mode#148
rikonor wants to merge 21 commits intomainfrom
or-args

rikonor commented Oct 17, 2025 •

edited

Loading

Uh oh!

viviveevee Oct 21, 2025

Uh oh!

viviveevee Oct 21, 2025

Uh oh!

viviveevee Oct 21, 2025

Uh oh!

viviveevee Oct 21, 2025

Uh oh!

viviveevee Oct 21, 2025

Uh oh!

viviveevee Oct 21, 2025

Uh oh!

viviveevee Oct 21, 2025

Uh oh!

viviveevee Oct 21, 2025

Uh oh!

raymondk commented Oct 30, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	Please provide a canister principal in global mode.
	{user_provided_string} is not a principal. Cannot use non-principals outside of a project.

	Environments are not available in global mode.
	Environments are not available in outside of projects.

	A network `url` is required in global mode.
	A network `url` is required outside of a project.

Conversation

rikonor commented Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

raymondk commented Oct 30, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rikonor commented Oct 17, 2025 •

edited

Loading