Struct CliClient 

pub struct CliClient(/* private fields */);

A Client configured using the CLI’s system user configuration.

This is a wrapper around Client<CliKeyStore> that provides convenient initialization methods while maintaining full compatibility with the underlying Client API through Deref.

Examples

use miden_client_cli::transaction::TransactionRequestBuilder;
use miden_client_cli::{CliClient, DebugMode};

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

// All Client methods work automatically via Deref
client.sync_state().await?;

// Build and submit transactions
let req = TransactionRequestBuilder::new()
    // ... configure transaction
    .build()?;

// client.submit_new_transaction(req, target_account_id)?;

Implementations

impl CliClient

pub async fn from_config( config: CliConfig, debug_mode: DebugMode, ) -> Result<Self, CliError>

Creates a new CliClient instance from an existing CliConfig.

⚠️ WARNING: This method bypasses the standard CLI configuration discovery logic and should only be used in specific scenarios such as testing or when you have explicit control requirements.

When NOT to use this method

• DO NOT use this method if you want your application to behave like the CLI tool
• DO NOT use this for general-purpose client initialization
• DO NOT use this if you expect automatic local/global config resolution

When to use this method

• Testing: When you need to test with a specific configuration
• Explicit Control: When you must load config from a non-standard location
• Programmatic Config: When you’re constructing configuration programmatically

Recommended Alternative

For standard client initialization that matches CLI behavior, use:

CliClient::from_system_user_config(debug_mode).await?

This method does not follow the CLI’s configuration priority logic (local → global). Instead, it uses exactly the configuration provided, which may not be what you expect.

Arguments

• config - The CLI configuration to use (bypasses standard config discovery)
• debug_mode - The debug mode setting (DebugMode::Enabled or DebugMode::Disabled)

Returns

A configured CliClient instance.

Errors

Returns a CliError if:

• Keystore initialization fails
• Client builder fails to construct the client
• Note transport connection fails (if configured)

Examples

use std::path::PathBuf;

use miden_client_cli::{CliClient, CliConfig, DebugMode};

// BEWARE: This bypasses standard config discovery!
// Only use if you know what you're doing.
let config = CliConfig::from_dir(&PathBuf::from("/path/to/.miden"))?;
let client = CliClient::from_config(config, DebugMode::Disabled).await?;

// Prefer this for standard CLI-like behavior:
let client = CliClient::from_system_user_config(DebugMode::Disabled).await?;

pub async fn from_system_user_config( debug_mode: DebugMode, ) -> Result<Self, CliError>

Creates a new CliClient instance configured using the system user configuration.

This method implements the configuration logic used by the CLI tool, allowing external projects to create a Client instance with the same configuration. It searches for configuration files in the following order:

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

The client is initialized with:

• SQLite store from the configured path
• gRPC client connection to the configured RPC endpoint
• Filesystem-based keystore authenticator
• Optional note transport client (if configured)
• Transaction graceful blocks delta
• Optional max block number delta

Arguments

• debug_mode - The debug mode setting (DebugMode::Enabled or DebugMode::Disabled).

Returns

A configured CliClient instance.

Errors

Returns a CliError if:

• No configuration file is found (local or global)
• Configuration file parsing fails
• Keystore initialization fails
• Client builder fails to construct the client
• Note transport connection fails (if configured)

Examples

use miden_client_cli::transaction::TransactionRequestBuilder;
use miden_client_cli::{CliClient, DebugMode};

// Create a client with default settings (debug disabled)
let mut client = CliClient::from_system_user_config(DebugMode::Disabled).await?;

// Or with debug mode enabled
let mut client = CliClient::from_system_user_config(DebugMode::Enabled).await?;

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

// Build and submit transactions
let req = TransactionRequestBuilder::new()
    // ... configure transaction
    .build()?;

// client.submit_new_transaction(req, target_account_id)?;

pub fn into_inner(self) -> Client<CliKeyStore>

Unwraps the CliClient to get the inner Client<CliKeyStore>.

This consumes the CliClient and returns the underlying client.

Examples

use miden_client_cli::{CliClient, DebugMode};

let cli_client = CliClient::from_system_user_config(DebugMode::Disabled).await?;
let inner_client = cli_client.into_inner();

Methods from Deref<Target = Client<CliKeyStore>>

pub async fn add_account( &mut self, account: &Account, overwrite: bool, ) -> Result<(), ClientError>

Adds the provided Account in the store so it can start being tracked by the client.

If the account is already being tracked and overwrite is set to true, the account will be overwritten. Newly created accounts must embed their seed (account.seed() must return Some(_)).

Errors

• If the account is new but it does not contain the seed.
• If the account is already tracked and overwrite is set to false.
• If overwrite is set to true and the account_data nonce is lower than the one already being tracked.
• If overwrite is set to true and the account_data commitment doesn’t match the network’s account commitment.
• If the client has reached the accounts limit (ACCOUNT_ID_LIMIT).
• If the client has reached the note tags limit (NOTE_TAG_LIMIT).

pub async fn import_account_by_id( &mut self, account_id: AccountId, ) -> Result<(), ClientError>

Imports an account from the network to the client’s store. The account needs to be public and be tracked by the network, it will be fetched by its ID. If the account was already being tracked by the client, it’s state will be overwritten.

Errors

• If the account is not found on the network.
• If the account is private.
• There was an error sending the request to the network.

pub async fn add_address( &mut self, address: Address, account_id: AccountId, ) -> Result<(), ClientError>

Adds an Address to the associated AccountId, alongside its derived NoteTag.

Errors

• If the account is not found on the network.
• If the address is already being tracked.
• If the client has reached the note tags limit (NOTE_TAG_LIMIT).

pub async fn remove_address( &mut self, address: Address, account_id: AccountId, ) -> Result<(), ClientError>

Removes an Address from the associated AccountId, alongside its derived NoteTag.

Errors

• If the account is not found on the network.
• If the address is not being tracked.

pub async fn get_account_headers( &self, ) -> Result<Vec<(AccountHeader, AccountStatus)>, ClientError>

Returns a list of AccountHeader of all accounts stored in the database along with their statuses.

Said accounts’ state is the state after the last performed sync.

pub async fn get_account( &self, account_id: AccountId, ) -> Result<Option<AccountRecord>, ClientError>

Retrieves a full AccountRecord object for the specified account_id. This result represents data for the latest state known to the client, alongside its status. Returns None if the account ID is not found.

pub async fn get_account_header_by_id( &self, account_id: AccountId, ) -> Result<Option<(AccountHeader, AccountStatus)>, ClientError>

Retrieves an AccountHeader object for the specified AccountId along with its status. Returns None if the account ID is not found.

Said account’s state is the state according to the last sync performed.

pub async fn try_get_account( &self, account_id: AccountId, ) -> Result<AccountRecord, ClientError>

Attempts to retrieve an AccountRecord by its AccountId.

Errors

• If the account record is not found.
• If the underlying store operation fails.

pub async fn try_get_account_header( &self, account_id: AccountId, ) -> Result<(AccountHeader, AccountStatus), ClientError>

Attempts to retrieve an AccountHeader by its AccountId.

Errors

• If the account header is not found.
• If the underlying store operation fails.

pub async fn register_account_public_key_commitments( &self, account_id: &AccountId, pub_keys: &[PublicKey], ) -> Result<(), ClientError>

Adds a list of public key commitments associated with the given account ID.

Commitments are stored as a BTreeSet, so duplicates are ignored. If the account already has known commitments, the new ones are merged into the existing set.

This is useful because with a public key commitment, we can retrieve its corresponding secret key using, for example, FilesystemKeyStore::get_key. This yields an indirect mapping from account ID to its secret keys: account ID -> public key commitments -> secret keys (via keystore).

To identify these keys and avoid collisions, the account ID is turned into its hex representation and a suffix is added. If the resulting set is empty, any existing settings entry is removed.

pub async fn deregister_account_public_key_commitment( &self, account_id: &AccountId, pub_key_commitments: &[PublicKeyCommitment], ) -> Result<bool, ClientError>

Removes a list of public key commitments associated with the given account ID.

Commitments are stored as a BTreeSet, so duplicates in pub_key_commitments are ignored and missing commitments are skipped. If the account is not registered or has no stored commitments, this is a no-op.

If the resulting set is empty, the settings entry is removed. Returns true if at least one commitment was removed, or false otherwise.

pub async fn get_account_public_key_commitments( &self, account_id: &AccountId, ) -> Result<Vec<PublicKeyCommitment>, ClientError>

Returns the previously stored public key commitments associated with the given AccountId, if any.

Once retrieved, this list of public key commitments can be used in conjunction with FilesystemKeyStore::get_key to retrieve secret keys.

Commitments are stored as a BTreeSet, so the returned list is deduplicated. Returns an empty vector if the account is not registered or no commitments are stored.

pub async fn import_notes( &mut self, note_files: &[NoteFile], ) -> Result<Vec<NoteId>, ClientError>

Imports a batch of new input notes into the client’s store. The information stored depends on the type of note files provided. If the notes existed previously, it will be updated with the new information. The tags specified by the NoteFiles will start being tracked. Returns the IDs of notes that were successfully imported or updated.

• If the note files are NoteFile::NoteId, the notes are fetched from the node and stored in the client’s store. If the note is private or doesn’t exist, an error is returned.
• If the note files are NoteFile::NoteDetails, new notes are created with the provided details and tags.
• If the note files are NoteFile::NoteWithProof, the notes are stored with the provided inclusion proof and metadata. The block header data is only fetched from the node if the note is committed in the past relative to the client.

Errors

• If an attempt is made to overwrite a note that is currently processing.
• If the client has reached the note tags limit (NOTE_TAG_LIMIT).

Note: This operation is atomic. If any note file is invalid or any existing note is in the processing state, the entire operation fails and no notes are imported.

pub async fn get_input_notes( &self, filter: NoteFilter, ) -> Result<Vec<InputNoteRecord>, ClientError>

Retrieves the input notes managed by the client from the store.

Errors

Returns a ClientError::StoreError if the filter is NoteFilter::Unique and there is no Note with the provided ID.

pub async fn get_consumable_notes( &self, account_id: Option<AccountId>, ) -> Result<Vec<(InputNoteRecord, Vec<(AccountId, NoteConsumptionStatus)>)>, ClientError>

Returns the input notes and their consumability. Assuming the notes will be consumed by a normal consume transaction. If account_id is None then all consumable input notes are returned.

The note screener runs a series of checks to determine whether the note can be executed as part of a transaction for a specific account. If the specific account ID can consume it (ie, if it’s compatible with the account), it will be returned as part of the result list.

pub async fn get_note_consumability( &self, note: InputNoteRecord, ) -> Result<Vec<(AccountId, NoteConsumptionStatus)>, ClientError>

Returns the consumability conditions for the provided note.

The note screener runs a series of checks to determine whether the note can be executed as part of a transaction for a specific account. If the specific account ID can consume it (ie, if it’s compatible with the account), it will be returned as part of the result list.

pub async fn get_input_note( &self, note_id: NoteId, ) -> Result<Option<InputNoteRecord>, ClientError>

Retrieves the input note given a NoteId. Returns None if the note is not found.

pub async fn get_output_notes( &self, filter: NoteFilter, ) -> Result<Vec<OutputNoteRecord>, ClientError>

Returns output notes managed by this client.

pub async fn get_output_note( &self, note_id: NoteId, ) -> Result<Option<OutputNoteRecord>, ClientError>

Retrieves the output note given a NoteId. Returns None if the note is not found.

pub fn is_note_transport_enabled(&self) -> bool

Check if note transport connection is configured

pub async fn send_private_note( &mut self, note: Note, _address: &Address, ) -> Result<(), ClientError>

Send a note through the note transport network.

The note will be end-to-end encrypted (unimplemented, currently plaintext) using the provided recipient’s address details. The recipient will be able to retrieve this note through the note’s NoteTag.

pub async fn fetch_private_notes(&mut self) -> Result<(), ClientError>

Fetch notes for tracked note tags.

The client will query the configured note transport node for all tracked note tags. To list tracked tags please use Client::get_note_tags. To add a new note tag please use Client::add_note_tag. Only notes directed at your addresses will be stored and readable given the use of end-to-end encryption (unimplemented). Fetched notes will be stored into the client’s store.

An internal pagination mechanism is employed to reduce the number of downloaded notes. To fetch the full history of private notes for the tracked tags, use Client::fetch_all_private_notes.

pub async fn fetch_all_private_notes(&mut self) -> Result<(), ClientError>

Fetches all notes for tracked note tags.

Similar to Client::fetch_private_notes however does not employ pagination, fetching all notes stored in the note transport network for the tracked tags. Please prefer using Client::fetch_private_notes to avoid downloading repeated notes.

pub async fn set_setting<T>( &mut self, key: String, value: T, ) -> Result<(), ClientError>

where T: Serializable,

Sets a setting value in the store. It can then be retrieved using get_setting.

pub async fn get_setting<T>( &self, key: String, ) -> Result<Option<T>, ClientError>

where T: Deserializable,

Retrieves the value for key, or None if it hasn’t been set.

pub async fn remove_setting(&mut self, key: String) -> Result<(), ClientError>

Deletes the setting value from the store.

pub async fn list_setting_keys(&self) -> Result<Vec<String>, ClientError>

Returns all the setting keys from the store.

pub async fn ensure_genesis_in_place( &mut self, ) -> Result<BlockHeader, ClientError>

Attempts to retrieve the genesis block from the store. If not found, it requests it from the node and store it.

pub async fn get_current_partial_mmr(&self) -> Result<PartialMmr, ClientError>

Fetches from the store the current view of the chain’s PartialMmr.

pub async fn get_note_tags(&self) -> Result<Vec<NoteTagRecord>, ClientError>

Returns the list of note tags tracked by the client along with their source.

When syncing the state with the node, these tags will be added to the sync request and note-related information will be retrieved for notes that have matching tags. The source of the tag indicates its origin. It helps distinguish between:

• Tags added manually by the user.
• Tags automatically added by the client to track notes.
• Tags added for accounts tracked by the client.

Note: Tags for accounts that are being tracked by the client are managed automatically by the client and don’t need to be added here. That is, notes for managed accounts will be retrieved automatically by the client when syncing.

pub async fn add_note_tag(&mut self, tag: NoteTag) -> Result<(), ClientError>

Adds a note tag for the client to track. This tag’s source will be marked as User.

pub async fn insert_note_tag( &self, tag_record: NoteTagRecord, ) -> Result<bool, ClientError>

Wrapper around the store’s add_note_tag method that checks the note tags limit before the insert.

pub async fn remove_note_tag(&mut self, tag: NoteTag) -> Result<(), ClientError>

Removes a note tag for the client to track. Only tags added by the user can be removed.

pub async fn get_sync_height(&self) -> Result<BlockNumber, ClientError>

Returns the block number of the last state sync block.

pub async fn sync_state(&mut self) -> Result<SyncSummary, ClientError>

Syncs the client’s state with the current state of the Miden network and returns a SyncSummary corresponding to the local state update.

The sync process is done in multiple steps:

1. A request is sent to the node to get the state updates. This request includes tracked account IDs and the tags of notes that might have changed or that might be of interest to the client.
2. A response is received with the current state of the network. The response includes information about new/committed/consumed notes, updated accounts, and committed transactions.
3. Tracked notes are updated with their new states.
4. New notes are checked, and only relevant ones are stored. Relevant notes are those that can be consumed by accounts the client is tracking (this is checked by the crate::note::NoteScreener)
5. Transactions are updated with their new states.
6. Tracked public accounts are updated and private accounts are validated against the node state.
7. The MMR is updated with the new peaks and authentication nodes.
8. All updates are applied to the store to be persisted.

pub async fn apply_state_sync( &mut self, update: StateSyncUpdate, ) -> Result<(), ClientError>

Applies the state sync update to the store.

See crate::Store::apply_state_sync() for what the update implies.

pub async fn get_transactions( &self, filter: TransactionFilter, ) -> Result<Vec<TransactionRecord>, ClientError>

Retrieves tracked transactions, filtered by TransactionFilter.

pub async fn submit_new_transaction( &mut self, account_id: AccountId, transaction_request: TransactionRequest, ) -> Result<TransactionId, ClientError>

Executes a transaction specified by the request against the specified account, proves it, submits it to the network, and updates the local database.

Uses the client’s default prover (configured via crate::builder::ClientBuilder::prover).

If the transaction utilizes foreign account data, there is a chance that the client doesn’t have the required block header in the local database. In these scenarios, a sync to the chain tip is performed, and the required block header is retrieved.

pub async fn submit_new_transaction_with_prover( &mut self, account_id: AccountId, transaction_request: TransactionRequest, tx_prover: Arc<dyn TransactionProver>, ) -> Result<TransactionId, ClientError>

Executes a transaction specified by the request against the specified account, proves it with the provided prover, submits it to the network, and updates the local database.

This is useful for falling back to a different prover (e.g., local) when the default prover (e.g., remote) fails with a ClientError::TransactionProvingError.

If the transaction utilizes foreign account data, there is a chance that the client doesn’t have the required block header in the local database. In these scenarios, a sync to the chain tip is performed, and the required block header is retrieved.

pub async fn execute_transaction( &mut self, account_id: AccountId, transaction_request: TransactionRequest, ) -> Result<TransactionResult, ClientError>

Creates and executes a transaction specified by the request against the specified account, but doesn’t change the local database.

If the transaction utilizes foreign account data, there is a chance that the client doesn’t have the required block header in the local database. In these scenarios, a sync to the chain tip is performed, and the required block header is retrieved.

Errors

• Returns ClientError::MissingOutputRecipients if the TransactionRequest output notes are not a subset of executor’s output notes.
• Returns a ClientError::TransactionExecutorError if the execution fails.
• Returns a ClientError::TransactionRequestError if the request is invalid.

pub async fn prove_transaction( &mut self, tx_result: &TransactionResult, ) -> Result<ProvenTransaction, ClientError>

Proves the specified transaction using the prover configured for this client.

pub async fn prove_transaction_with( &mut self, tx_result: &TransactionResult, tx_prover: Arc<dyn TransactionProver>, ) -> Result<ProvenTransaction, ClientError>

Proves the specified transaction using the provided prover.

pub async fn submit_proven_transaction( &mut self, proven_transaction: ProvenTransaction, transaction_inputs: impl Into<TransactionInputs>, ) -> Result<BlockNumber, ClientError>

Submits a previously proven transaction to the RPC endpoint and returns the node’s chain tip upon mempool admission.

pub async fn get_transaction_store_update( &self, tx_result: &TransactionResult, submission_height: BlockNumber, ) -> Result<TransactionStoreUpdate, ClientError>

Builds a TransactionStoreUpdate for the provided transaction result at the specified submission height.

pub async fn apply_transaction( &self, tx_result: &TransactionResult, submission_height: BlockNumber, ) -> Result<(), ClientError>

Persists the effects of a submitted transaction into the local store, updating account data, note metadata, and future note tracking.

pub async fn apply_transaction_update( &self, tx_update: TransactionStoreUpdate, ) -> Result<(), ClientError>

pub async fn execute_program( &mut self, account_id: AccountId, tx_script: TransactionScript, advice_inputs: AdviceInputs, foreign_accounts: BTreeSet<ForeignAccount>, ) -> Result<[BaseElement; 16], ClientError>

Executes the provided transaction script against the specified account, and returns the resulting stack. Advice inputs and foreign accounts can be provided for the execution.

The transaction will use the current sync height as the block reference.

pub async fn validate_request( &mut self, account_id: AccountId, transaction_request: &TransactionRequest, ) -> Result<(), ClientError>

Validates that the specified transaction request can be executed by the specified account.

This does’t guarantee that the transaction will succeed, but it’s useful to avoid submitting transactions that are guaranteed to fail. Some of the validations include:

• That the account has enough balance to cover the outgoing assets.
• That the client is not too far behind the chain tip.

pub fn in_debug_mode(&self) -> bool

Returns true if the client is in debug mode.

pub fn code_builder(&self) -> CodeBuilder

Returns an instance of the CodeBuilder

pub fn rng(&mut self) -> &mut ClientRng

Returns a reference to the client’s random number generator. This can be used to generate randomness for various purposes such as serial numbers, keys, etc.

pub fn prover(&self) -> Arc<dyn TransactionProver + Sync + Send>

pub async fn check_note_tag_limit(&self) -> Result<(), ClientError>

Checks if the note tag limit has been exceeded.

pub async fn check_account_limit(&self) -> Result<(), ClientError>

Checks if the account limit has been exceeded.

Trait Implementations

impl Deref for CliClient

Allows using CliClient like Client<CliKeyStore> through deref coercion.

This enables calling all Client methods on CliClient directly.

type Target = Client<FilesystemKeyStore>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for CliClient

Allows mutable access to Client<CliKeyStore> methods.

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.