feat: implement CliClient #1642

Keinberger · 2026-01-07T13:57:26Z

Updates

There has been the following update since the beginning of this PR: #1642 (comment)

Summary

This PR implements a from_system_user_config() method for CliClient that creates a Client instance using the same configuration as the CLI tool (reading from .miden/miden-client.toml or local config). This enables anyone to programmatically obtain a properly configured CLI client.

This change is required for implementing the mint command https://github.com/0xMiden/midenup/issues/128, in particular with the new implementation strategy described in 0xMiden/midenup#130 (comment). The https://github.com/0xMiden/miden-faucet repository needs to create a CLI-configured client instance to consume notes and sync state after making the mint request when using the miden-faucet-client, see this PR description for more details: 0xMiden/miden-faucet#196.

Details

New `CliClient` wrapper type

A newtype wrapper CliClient(Client<CliKeyStore>) has been added to miden-client-cli with Deref and DerefMut implementations. This allows external projects to:

Initialize a client with CLI configuration via CliClient::from_system_user_config()
Use all Client methods transparently through deref coercion
Access the inner Client<CliKeyStore> when needed via into_inner(), inner(), or inner_mut()

Configuration loading behavior

The from_system_user_config() method searches for configuration files in order:

Local .miden/miden-client.toml in the current working directory
Global .miden/miden-client.toml in the home directory

The client is initialized with the same settings as the CLI:

SQLite store from configured path
gRPC client connection to configured RPC endpoint
Filesystem-based keystore authenticator
Optional note transport client (if configured)
Transaction graceful blocks delta
Optional max block number delta
Debug mode (accepts DebugMode enum, matching ClientBuilder::in_debug_mode() API)

The new CliClient has been integrated into the existing CLI logic to ensure that the CliClient is the single source of configuration for the CLI client instance.

Usage example

use miden_client::DebugMode;
use miden_client_cli::CliClient;

// Create a CLI-configured client
let client = CliClient::from_system_user_config(DebugMode::Disabled).await?;

// Use it like a regular Client
client.sync_state().await?;

// Build and submit transactions
let req = TransactionRequest::builder()
    .consume_notes(recently_minted_note)
    .build()?;

client.submit_new_transaction(req, target_account_id)?;

This pattern was originally described by @igamigo in the following comment: 0xMiden/midenup#130 (comment)

…n with CLI config

igamigo · 2026-01-07T17:19:40Z

bin/miden-cli/tests/cli.rs

+    // Clean up any existing global config
+    cleanup_global_config();


These home dirs are process-global environments, right? So depending on how nextest runs tests there could be cases where this messes up with some other tests, is that correct? If so, I wonder if we should run these serially.

Good catch! You're absolutely right, these tests manipulate process-global resources (~/.miden home directory and env::set_current_dir()). I've added #[serial_test::serial(global_config)] to all four tests to ensure they run serially and avoid race conditions with nextest or parallel test execution.

igamigo · 2026-01-07T17:22:46Z

bin/miden-cli/tests/cli.rs

+    // Verify the client is functional by syncing
+    let sync_result = client.sync_state().await;
+    assert!(sync_result.is_ok(), "Client sync failed: {:?}", sync_result.err());


I think this doesn't really assert that the test ends up using the local config (although this might not be simple anyway)

Same applies for the global one

Yeah I think unfortuantely there is no good way to test this. The assertions didn't actually verify which config was used.

I've fixed this by looking at the actual store file path that was created.

igamigo · 2026-01-07T17:23:32Z

bin/miden-cli/tests/cli.rs

+    // Attempt to create a client (should fail)
+    let client = miden_client_cli::CliClient::from_system_user_config(DebugMode::Disabled).await;
+


Should this not silently initialize the client? Or is that not ideal?

Absolutely correct, I missed that one. I implemented that now!

Updated the implementation to call InitCmd::default().execute() when no config is found, and adjusted the test to verify silent initialization works correctly.

igamigo · 2026-01-07T17:27:40Z

bin/miden-cli/src/lib.rs

+    /// # Ok(())
+    /// # }
+    /// ```
+    pub async fn from_system_user_config(debug_mode: DebugMode) -> Result<Self, CliError> {


One thing that would be nice is passing a CliConfig to a client constructor, and then have different constructors/loaders for CliConfig (for example, one for local config, one for global, one that respects the priority); it can also save the TOML automatically on the correct directories. We can still keep this from_system_user_config() as well.
I think this also makes tests better in the sense that you don't have to change the working dir.

I completely agree with your suggestion! However, are you fine if we move this to a separate issue to speed up this PR and the mint command (mint has taken quite long already)?

Nevermind, I addressed this too and refactored the CLI config

igamigo · 2026-01-07T18:01:49Z

bin/miden-cli/tests/cli.rs

+    // Change to the temp directory to ensure the local config is picked up
+    let original_dir = env::current_dir().unwrap();
+    env::set_current_dir(&temp_dir)?;


I think this is also process-wide which could be problematic

Fixed according with #1642 (comment)

feat(cli): add silent initialization for CliClient test(cli): refactor tests not to use global resources test(cli): modify from_system_user_config CliClient tests to run serially test(cli): modify from_system_user_config tests to effectively assert global and local config prioritization test(cli): add silent initialization tests for from_system_user_config

Keinberger · 2026-01-08T15:39:19Z

Update

Hey everyone, I made a commit with several changes to address the code feedback from @igamigo .

Here's what changed:

Config separation architecture: Split configuration loading from client construction. Added CliConfig::from_system(), from_dir(), from_local_dir(), and from_global_dir() methods. Added CliClient::from_config() to build client from explicit config.
Test changes: Removed all env::set_current_dir() calls from tests (process-wide side effect). Tests now use explicit paths via CliConfig::from_dir().
Safety warnings: Added prominent "⚠️ WARNING: Advanced Use Only" documentation to from_dir(), from_local_dir(), from_global_dir(), and from_config(). These methods bypass CLI's standard config discovery logic (local → global priority). I think this is important: without warnings, external developers might use these testing/advanced methods in production, causing their apps to behave differently than the CLI tool (e.g., ignoring local configs). Marked from_system() and from_system_user_config() as "✅ Recommended" for standard use. The emoji usage serves as eye-catchers to catch awareness when reading the docs.
Silent initialization: from_system_user_config() now auto-initializes config if none exists, matching the standard CLI behavior.

igamigo

LGTM. I left some comments, most of which are minor. If you prefer to tackle them separately, let's open an issue for them before merging this.

igamigo · 2026-01-12T19:16:22Z

bin/miden-cli/src/utils.rs

+///
+/// # Deprecated
+/// This function is deprecated in favor of `CliConfig::from_system()` which provides
+/// the same functionality with a cleaner API.
 pub(super) fn load_config_file() -> Result<(CliConfig, PathBuf), CliError> {


I think we can just delete this and use the new functions instead.

Done! Deleted load_config_file() from utils.rs and replaced all usages with CliConfig::from_system() directly

igamigo · 2026-01-12T19:31:53Z

bin/miden-cli/src/lib.rs

+    ///
+    /// # Returns
+    ///
+    /// A configured `CliClient` instance.


nit: These can be doc-linked if you use [] instead:

Suggested change

/// A configured `CliClient` instance.

/// A configured [`CliClient`] instance.

This happens throughout the file. It's not critical though so if you prefer the current state that's fine too

Good catch! Updated all documentation to use proper doc-links like [CliClient], [CliConfig],[CliError],[DebugMode::Enabled], etc. Also added cross-references between related methods.

igamigo · 2026-01-12T19:35:13Z

bin/miden-cli/src/config.rs

+        // Try local first
+        match Self::from_local_dir() {
+            Ok(config) => Ok(config),
+            Err(_) => {
+                // Fall back to global
+                Self::from_global_dir().map_err(|_| {
+                    CliError::Config(
+                        "No configuration file found".to_string().into(),
+                        "Neither local nor global config file exists. Run 'miden-client init' to create one.".to_string()
+                    )
+                })
+            },
+        }


This is fine, but it will also silently eat any errors that are not "file not found" too. For example, if I have a local config but for some reason it fails to parse correctly, it will go through the Err(_) branch and load the global config and this could be confusing. I believe we should check that the file has not been found instead of matching for any error, what do you think?
Maybe it could be addressed on a different issue unless you prefer doing it here.

Great point! Added a new CliError::ConfigNotFound variant specifically for "file not found" errors. Now from_system() only falls back to global config when encountering ConfigNotFound, parse errors and other issues are propagated immediately

igamigo · 2026-01-12T19:36:41Z

bin/miden-cli/tests/cli.rs

+
+// FROM_SYSTEM_USER_CONFIG TESTS
+// ================================================================================================
+/// Tests that `CliClient::from_system_user_config()` successfully creates a client with the same


I don't see a call to CliClient::from_system_user_config in this test

Fixed! The test now properly changes the working directory to the temp directory and calls CliClient::from_system_user_config() instead of from_config(). Also added cleanup_global_config() for proper isolation.

igamigo · 2026-01-13T13:15:08Z

One more small thing: For users to make use of client structs and code, I think we'll want to re-export everything from miden-client through the CLI library. This way, they won't have to also manually import miden-client as well as the CLI library.

Keinberger · 2026-01-15T12:48:37Z

One more small thing: For users to make use of client structs and code, I think we'll want to re-export everything from miden-client through the CLI library. This way, they won't have to also manually import miden-client as well as the CLI library.

Added pub use miden_client as client. All miden-client types can now be accessed through miden_client_cli::client::*

feat(cli): add ConfigNotFound error variant for better error handling feat(cli): re-export miden_client as client module docs(cli): use doc-links for type references in documentation fix(cli): update test to call from_system_user_config

igamigo · 2026-01-15T14:53:35Z

One more small thing: For users to make use of client structs and code, I think we'll want to re-export everything from miden-client through the CLI library. This way, they won't have to also manually import miden-client as well as the CLI library.

Added pub use miden_client as client. All miden-client types can now be accessed through miden_client_cli::client::*

I think it might be better to do pub use miden_client::* unless there is a good reason not to (sorry I didn't specify more in my previous comment). The alternative would be to do a curated set of re-exports at the top-level and the rest under a namespace.
Otherwise, if you wanted to refer to the Client type you'd have to do miden_client_cli::client::Client which is a bit redundant and doesn't add much in terms of code organization.

feat: implement and export CliClient for default Client initializatio…

038330b

…n with CLI config

Keinberger requested a review from igamigo January 7, 2026 13:57

Keinberger linked an issue Jan 7, 2026 that may be closed by this pull request

Implement Client::from_system_user_config() helper function #1639

Open

Keinberger self-assigned this Jan 7, 2026

chore: amend changelog

fc3fab5

Keinberger marked this pull request as draft January 7, 2026 14:02

Keinberger added 2 commits January 7, 2026 16:16

chore: linting

698187d

chore: lint

4b5621c

Keinberger marked this pull request as ready for review January 7, 2026 16:13

Keinberger requested a review from mmagician January 7, 2026 16:13

Keinberger changed the title ~~feat: implement and export CliClient for default Client initializatio…~~ feat: implement CliClient Jan 7, 2026

igamigo reviewed Jan 7, 2026

View reviewed changes

Keinberger requested a review from igamigo January 8, 2026 15:40

Keinberger mentioned this pull request Jan 10, 2026

feat: support multiple commands and multiple binaries in aliases 0xMiden/midenup#130

Open

fkrause98 approved these changes Jan 12, 2026

View reviewed changes

igamigo approved these changes Jan 12, 2026

View reviewed changes

Keinberger added 2 commits January 15, 2026 14:50

Merge branch 'main' into kbg/feat/cli-client

2ed494e

		// Clean up any existing global config
		cleanup_global_config();

		// Attempt to create a client (should fail)
		let client = miden_client_cli::CliClient::from_system_user_config(DebugMode::Disabled).await;

	/// A configured `CliClient` instance.
	/// A configured [`CliClient`] instance.

feat: implement CliClient #1642

Are you sure you want to change the base?

feat: implement CliClient #1642

Conversation

Keinberger commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Updates

Summary

Details

New CliClient wrapper type

Configuration loading behavior

Usage example

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!

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!

Keinberger commented Jan 8, 2026

Update

Uh oh!

igamigo left a comment

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

igamigo commented Jan 13, 2026

Uh oh!

Keinberger commented Jan 15, 2026

Uh oh!

igamigo commented Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Keinberger commented Jan 7, 2026 •

edited

Loading

New `CliClient` wrapper type

igamigo commented Jan 15, 2026 •

edited

Loading