Skip to main content
Version: 0.17 (unstable)

CLI

The following document lists the commands that the CLI currently supports.

Use --help as a flag on any command for more information.

Usage

Call a command on the miden-client like this:

miden-client <command> <flags> <arguments>

Commands

init

Creates a global configuration file for the client. Pass --local to create one in the current directory. Running this command is optional, as the client will self-initialize by default. By default, the command uses the Testnet network.

# This will create a config file named `miden-client.toml` using default values
# This file contains information useful for the CLI like the RPC provider and database path
miden-client init

# You can set up the CLI for any of the default networks
miden-client init --network testnet
miden-client init --network devnet
miden-client init --network localhost

# You can also specify a custom network
miden-client init --network http://18.203.155.106
# You can specify the port
miden-client init --network http://18.203.155.106:8080
# You can use HTTPS
miden-client init --network https://18.203.155.106
# You can specify both
miden-client init --network https://18.203.155.106:1234

# You can use the --store-path flag to override the default store config
miden-client init --store-path db/store.sqlite3

# You can use the --block-delta flag to set maximum number of blocks the client can be behind
miden-client init --block-delta 250

# You can provide both flags
miden-client init --network http://18.203.155.106 --store-path db/store.sqlite3

# You can set a remote prover to offload the proving process (along with the `--delegate-proving` flag in transaction commands)
miden-client init --remote-prover-endpoint <PROVER_URL>

# To enable the transport layer, specify the endpoint
miden-client init --note-transport-endpoint <MIDEN_NOTE_TRANSPORT_URL>

More information on the configuration file can be found in the configuration section.

account

Inspect account details.

Action Flags

FlagsDescriptionShort Flag
--listList all accounts monitored by this client-l
--show <ID>Show details of the account for the specified ID-s
--inspect <ID[:PROCEDURE]>List the procedures an account exposes, or resolve a single one
--default <ID>Manage the setting for the default account-d

The --show flag also accepts a partial ID instead of the full ID. For example, instead of:

miden-client account --show 0x8fd4b86a6387f8d8

You can call:

miden-client account --show 0x8fd4b86

For the --default flag, if <ID> is "none" then the previous default account is cleared. If no <ID> is specified then the default account is shown.

The --inspect flag lists the procedures an account exposes, grouped into resolved procedures (shown in a table with their name, signature, and MAST root) and unresolved ones (listed by their MAST root under a hint to pass --package). Pass <ID>:<PROCEDURE> to resolve a single procedure by name; if no procedure with that name can be resolved (the account does not expose it, or its defining package was not provided) the command fails with an error. Like --show, it accepts a partial ID. It supports two additional flags:

  • -p, --package <FILE>: Supplies an additional .masp package used to resolve procedure MAST roots to their names and signatures, on top of the packages in the configured packages directory. It is repeatable (pass it once per package); when the same MAST root is exported by more than one package the first-loaded one wins (passed packages are consulted first) and a warning lists the packages involved. Procedures whose name cannot be resolved are still listed by their MAST root.
  • -v, --verbose: Prints the MASM disassembly of each procedure.

new-wallet

Creates a new wallet account.

A basic wallet is comprised of a basic authentication component (for RPO Falcon signature verification), alongside a basic wallet component (for sending and receiving assets).

This command has three optional flags:

  • -t, --account-type <ACCOUNT_TYPE>: Used to select the account visibility (private if not specified). It may receive "private" or "public". This is the only thing the protocol's AccountType encodes.
  • --extra-packages <PACKAGES>: Specifies a list of file paths for packages holding account components to include in the account. If the packages contain placeholders, the CLI will prompt the user to enter the required data for instantiating storage appropriately.
  • --init-storage-data-path <INIT_STORAGE_DATA_PATH>: Specifies an optional file path to a TOML file containing key/value pairs used for initializing storage. Each key should map to a placeholder within the packages' component metadata. The CLI will prompt for any keys that are not present in the file.

After creating an account with the new-wallet command, it is automatically stored and tracked by the client. This means the client can execute transactions that modify the state of accounts and track related changes by synchronizing with the Miden network.

new-account

Creates a new account and saves it locally.

An account may be composed of one or more components, each with its own storage and distinct functionality. This command lets you build a custom account by selecting an account type and optionally adding extra component packages.

This command has four flags:

  • -t, --account-type <ACCOUNT_TYPE>: Specifies the account visibility. It accepts either "private" or "public", with "private" as the default. This is the only thing the protocol's AccountType encodes.

There is no --faucet flag: faucet-vs-regular is derived from the packages. If any package contributes the FungibleFaucet component, the resulting account is treated as a fungible faucet and an implicit TokenPolicyManager is installed when one is not already provided. --account-type only selects visibility.

  • --packages <PACKAGES>: Specifies a list of file paths for packages holding account components to include in the account. If the packages contain placeholders, the CLI will prompt the user to enter the required data for instantiating storage appropriately.
  • --init-storage-data-path <INIT_STORAGE_DATA_PATH>: Specifies an optional file path to a TOML file containing key/value pairs used for initializing storage. Each key should map to a placeholder within the packages' component metadata. The CLI will prompt for any keys that are not present in the file.

After creating an account with the new-account command, the account is stored locally and tracked by the client, enabling it to execute transactions and synchronize state changes with the Miden network.

Examples

# Create a new wallet with default settings (private visibility, no extra components)
miden-client new-wallet

# Create a new wallet with public visibility
miden-client new-wallet -t public

# Create a new wallet that includes custom packages
miden-client new-wallet --extra-packages packages/custom-package.masp

# Create a fungible faucet with interactive input
# (the resulting account is a faucet because basic-fungible-faucet.masp contributes the
# `FungibleFaucet` component — no extra flag is needed)
miden-client new-account --packages packages/basic-fungible-faucet.masp

# Create a fungible faucet with preset fields
miden-client new-account --packages packages/basic-fungible-faucet.masp --init-storage-data-path init_data.toml

where init_data.toml is a TOML file with the following example content:

token_metadata.max_supply = 1000000000
token_metadata.decimals = 6
token_metadata.ticker = "TEST"

info

View a summary of the current client state.

Action Flags

FlagDescriptionShort Flag
--rpc-statusDisplay detailed RPC node status information-r

When using the --rpc-status flag, the command displays additional information about the RPC node including:

  • Node version
  • Genesis commitment
  • Store connection status and chain tip
  • Block producer status and chain tip

notes

View and manage notes. Also, exchange private notes using the note transport network.

Action Flags

FlagsDescriptionShort Flag
--list [<filter>]List input notes-l
--show <ID>Show details of the input note for the specified note ID-s
--send <ID> <address>Send a note using the note transport network
--fetchFetch notes from the note transport network

The --list flag receives an optional filter: - expected: Only lists expected notes. - committed: Only lists committed notes. - consumed: Only lists consumed notes. - processing: Only lists processing notes. - consumable: Only lists consumable notes. An additional --account-id <ID> flag may be added to only show notes consumable by the specified account. If no filter is specified then all notes are listed.

The --show flag also accepts a partial ID instead of the full ID. For example, instead of:

miden-client notes --show 0x70b7ecba1db44c3aa75e87a3394de95463cc094d7794b706e02a9228342faeb0

You can call:

miden-client notes --show 0x70b7ec

To send a private note, the --send flag sends a note using the note transport network. The note ID (hex, in full or a prefix) and recipient's address (bech32) must be provided. The note is assumed to be stored in the store (e.g., imported using import).

You can call:

miden-client notes --send 0xc1234567 mm1qpkdyek2c0ywwvzupakc7zlzty8qn2qnfc

To fetch private notes, the --fetch allows to download notes from the note transport network. Only notes for tracked tags will be fetched (e.g. miden-client tags --list). The downloaded notes will be added to the store.

miden-client notes --fetch

network-note-status

Query the network for the processing status of a note. This is useful for diagnosing issues with network transactions (NTX), such as notes that are stuck or have been discarded.

miden-client network-note-status <NOTE_ID>

The command displays a table with the following information:

  • Status: The current processing state of the note (Pending, Processed, Discarded, or Committed).
  • Attempt Count: The number of times the node has attempted to process the note.
  • Last Error: The last error encountered during processing, if any.
  • Last Attempt Block: The block number of the most recent processing attempt.

The note ID must be provided as a full hex string:

miden-client network-note-status 0x70b7ecba1db44c3aa75e87a3394de95463cc094d7794b706e02a9228342faeb0

This command queries the Miden node directly and does not require the note to be tracked locally.

sync

Sync the client with the latest state of the Miden network. Shows a brief summary at the end.

tags

View and add tags.

Action Flags

FlagDescriptionAliases
--listList all tags monitored by this client-l
--add <tag>Add a new tag to the list of tags monitored by this client-a
--remove <tag>Remove a tag from the list of tags monitored by this client-r

tx

View transactions.

Action Flags

CommandDescriptionAliases
--listList tracked transactions-l

After a transaction gets executed, two entities start being tracked:

  • The transaction itself: It follows a lifecycle from Pending (initial state) and Committed (after the node receives it). It may also be Discarded if the transaction was not included in a block.
  • Output notes that might have been created as part of the transaction (for example, when executing a pay-to-id transaction).

Transaction creation commands

mint

Creates a note that contains a specific amount tokens minted by a faucet, that the target Account ID can consume.

Usage: miden-client mint --target <TARGET ACCOUNT ID> --asset <AMOUNT>::<FAUCET ID> --note-type <NOTE_TYPE>

consume-notes

Account ID consumes a list of notes, specified by their Note ID.

Usage: miden-client consume-notes --account <ACCOUNT ID> [NOTES]

For this command, you can also provide a partial ID instead of the full ID for each note. So instead of

miden-client consume-notes --account <some-account-id> 0x70b7ecba1db44c3aa75e87a3394de95463cc094d7794b706e02a9228342faeb0 0x80b7ecba1db44c3aa75e87a3394de95463cc094d7794b706e02a9228342faeb0

You can do:

miden-client consume-notes --account <some-account-id> 0x70b7ecb 0x80b7ecb

Additionally, you can optionally not specify note IDs, in which case any note that is known to be consumable by the executor account ID will be consumed.

Either Expected or Committed notes may be consumed by this command, changing their state to Processing. It's state will be updated to Consumed after the next sync.

transfer

Transfers assets to another account. Sender Account creates a note that a target Account ID can consume. The asset is identified by the tuple (FAUCET ID, AMOUNT). The note can be configured to be recallable making the sender able to consume it after a height is reached.

Usage: miden-client transfer --sender <SENDER ACCOUNT ID> --target <TARGET ACCOUNT ID> --asset <AMOUNT>::<FAUCET ID> --note-type <NOTE_TYPE> [--recall-height <RECALL_HEIGHT>]

swap

The source account creates a SWAP note that offers some asset in exchange for some other asset. When another account consumes that note, it will receive the offered asset amount and the requested asset will removed from its vault (and put into a new note which the first account can then consume). Consuming the note will fail if the account doesn't have enough of the requested asset.

Usage: miden-client swap --source <SOURCE ACCOUNT ID> --offered-asset <OFFERED AMOUNT>::<OFFERED FAUCET ID> --requested-asset <REQUESTED AMOUNT>::<REQUESTED FAUCET ID> --note-type <NOTE_TYPE> [--payback-note-type <NOTE_TYPE>]

The --payback-note-type option controls the visibility of the payback note created when the swap is consumed. It defaults to private.

address

View and manage addresses.

Action Subcommands

SubcommandDescription
list <ID>List all addresses or only for the specified account ID (default command)
add <ID> <ADDRESS>Track a bech32-encoded address on the specified account ID
remove <ID> <ADDRESS>Remove a bech32-encoded address from the specified account ID
encode <ID> <INTERFACE> <TAG_LEN>Produce a bech32 address from the account ID, interface, and optional tag length

The list subcommand optionally takes an account ID to only show the addresses of that account, if it is not provided, it will show all addresses of all accounts.

miden-client address list 0x17f13f4f83a8e8100c19d2961dfda2

add and remove take the account ID and a bech32-encoded address as arguments. add validates that the bech32 address encodes the same account ID and that its network matches the CLI's configured network.

Use encode to produce a bech32 address from its fields — this output is what add expects. The interface can be:

  • basic-wallet: The basic wallet interface.

Note: Unspecified (shown by address list) denotes an address not bound to any interface, it's the default address for every account created.

# Produce a bech32 address for the given account, interface, and tag length
miden-client address encode 0x17f13f4f83a8e8100c19d2961dfda2 basic-wallet 10

# Track that address on the account
miden-client address add 0x17f13f4f83a8e8100c19d2961dfda2 mlcl1qple0ejnutx8zyp0cm0pme9wjfgqz0u9djq_qruqqypuyph
miden-client address remove 0x17f13f4f83a8e8100c19d2961dfda2 mlcl1qple0ejnutx8zyp0cm0pme9wjfgqz0u9djq

Tips

For transfer and consume-notes, you can omit the --sender and --account flags to use the client's default account. If you omit the flag but have no default account set, you'll get an error instead.

For every command which needs an account ID (either wallet or faucet), you can also provide a partial ID instead of the full ID for each account. So instead of

miden-client transfer --sender 0x80519a1c5e3680fc --target 0x8fd4b86a6387f8d8 --asset 100::0xa99c5c8764d4e011 --note-type private

You can do:

miden-client transfer --sender 0x80519 --target 0x8fd4b --asset 100::0xa99c5c8764d4e011 --note-type private

!!! note The only exception is for using IDs as part of the asset, those should have the full faucet's account ID.

Transaction confirmation

When creating a new transaction, a summary of the transaction updates will be shown and confirmation for those updates will be prompted:

miden-client <tx command> ...

TX Summary:

...

Continue with proving and submission? Changes will be irreversible once the proof is finalized on the network (y/N)

This confirmation can be skipped in non-interactive environments by providing the --force flag (miden-client transfer --force ...).

Delegated proving

If a remote prover is configured, the CLI can offload the proving process to it. This is done by providing the --delegate-proving flag when creating a transaction. The CLI will then send the transaction to the remote prover for processing.

keys

Manage authentication keys in the configured filesystem keystore.

Supported authentication schemes are falcon512-poseidon2 and ecdsa-k256-keccak.

keys --list

List each stored key's public key commitment, authentication scheme, and associated account IDs:

miden-client keys --list

Running miden-client keys without an action also lists the keys. The associated accounts column contains - for a standalone key. Associated keys are included in account exports unless --no-keys is used.

The command reads the keystore directory and skips every file that does not hold a readable key, so a damaged file does not hide the keys that are readable.

keys --generate

Generate a key for the selected authentication scheme and store it in the keystore:

miden-client keys --generate falcon512-poseidon2
miden-client keys --generate ecdsa-k256-keccak

The command prints the public key commitment. It does not print the secret key.

keys --import

Import and store one serialized authentication secret key:

miden-client keys --import <FILE>

The file must contain exactly one AuthSecretKey in the Miden binary serialization format. PEM, DER, and raw secret-key files are not accepted. The command rejects data after the serialized key.

Generated and imported keys are standalone until they are associated with an account.

keys --associate and keys --disassociate

Add or remove an association between a stored key and an account:

miden-client keys --associate <COMMITMENT> --account-id <ACCOUNT_ID>
miden-client keys --disassociate <COMMITMENT> --account-id <ACCOUNT_ID>

COMMITMENT must be a 0x-prefixed hexadecimal word, as keys --list prints it. ACCOUNT_ID accepts a hexadecimal account ID or a bech32 address.

An association is client bookkeeping. It selects the keys that an account export includes. It does not change the authentication component of the account, and it does not give the key the right to authorize a transaction for that account.

--associate fails if the keystore holds no key for the commitment. --disassociate accepts a commitment that is not associated with the account and reports that nothing changed, so it can be used to clear an association whose key file is gone.

keys --commitment

Calculate a public key commitment without storing the public key:

miden-client keys --commitment <PUBLIC_KEY>

PUBLIC_KEY must be a 0x-prefixed hexadecimal serialization of the key. The CLI identifies the scheme from the key length. For ECDSA, provide the 33-byte compressed SEC1 public key. For Falcon, provide the 897-byte serialized Falcon public key.

Importing and exporting

export

Export an output note or a local account to a binary file.

FlagDescriptionAliases
--filename <FILENAME>Desired filename for the binary file.-f
--accountExport account data.
--noteExport note data.
--export-type <EXPORT_TYPE>Exported note type. Required when exporting a note.-e
--no-keysLeave secret keys out of an exported account file.
Export an account

Use --account to export a locally tracked account:

miden-client export <ACCOUNT_ID> --account
miden-client export <ACCOUNT_ID> --account --filename account.mac

The default filename is <ACCOUNT_ID>.mac. A .mac file contains the account state and the authentication secret keys that the keystore associates with the account. If the keystore has no associated key, the export succeeds and the file contains no secret key.

Use --no-keys to omit associated secret keys from the file:

miden-client export <ACCOUNT_ID> --account --no-keys

This option is useful when another party needs the account state but must not receive signing authority.

An account file without secret keys can still contain sensitive data. An undeployed account file contains the account seed, which is required to deploy the account.

Export a note

Use --note and select an export type:

miden-client export <NOTE_ID> --note --export-type partial
Export type

The user needs to specify how the note should be exported via the --export-type flag. The following options are available:

  • id: Only the note ID is exported. When importing, if the note ID is already tracked by the client, the note will be updated with missing information fetched from the node. This works for both public and private notes. If the note isn't tracked and the note is public, the whole note is fetched from the node and is stored for later use.
  • full: The note is exported with all of its information (metadata and inclusion proof). When importing, the note is considered unverified. The note may not be consumed directly after importing as its block header will not be stored in the client. The block header will be fetched and be used to verify the note during the next sync. At this point the note will be committed and may be consumed.
  • partial: The note is exported with minimal information and may be imported even if the note is not yet committed on chain. At the moment of importing the note, the client will check the state of the note by doing a note sync, using the note's tag. Depending on the response, the note will be either stored as "Expected" or "Committed".

import

Import one or more account or note files. The CLI infers each file type from its contents.

miden-client import <FILE>...

Importing a .mac account file adds the account to the client. The CLI also stores each secret key in the file and associates it with the account. A keyless account file still imports successfully, but it does not grant signing authority.

The --overwrite flag can be used when importing accounts. It allows the user to overwrite existing accounts with the same ID. This is useful when you want to update the account's information or replace it with a new version.

miden-client import --overwrite account.mac

Executing scripts

exec

Execute the specified program against the specified account.

FlagDescriptionAliases
--account <ACCOUNT_ID>Account ID to use for the program execution.-a
--script-path <SCRIPT_PATH>Path to script's source code to be executed.-s
--inputs-path <INPUTS_PATH>Path to the inputs file.-i
--hex-wordsPrint the output stack grouped into words.

The file referenced by --inputs-path should contain a TOML array of inline tables, where each table has two fields: - key: a 256-bit hexadecimal string representing a word to be used as a key for the input entry. The hexadecimal value must be prefixed with 0x. - values: an array of 64-bit unsigned integers representing field elements to be used as values for the input entry. Each integer must be written as a separate string, within double quotes.

The input file should contain a TOML table called inputs, as in the following example:

inputs = [ { key = "0x0000000000000000000000000000000000000000000000000000001000000000", values = ["13", "9"]}, { key = "0x0000000000000000000000000000000000000000000000000000000000000000" , values = ["1", "2"]}, ]

call

Call a procedure on an account and show what it returns, along with the state changes the call would produce.

Usage: miden-client call <ACCOUNT_ID>:<PROCEDURE> [ARGS]... [--package <PACKAGE>]

FlagDescriptionAliases
--package <PACKAGE>The .masp package that exports the procedure, as a path or a name resolved in the packages directory. Optional.-p
--inputs-path <INPUTS_PATH>Path to a TOML file with advice map entries.-i

The target is a single argument of the form <ACCOUNT_ID>:<PROCEDURE>. For an account tracked by the client, the ID may be given as a partial ID; an account that isn't tracked has to be named by its full hex ID or its bech32 address, since a prefix is resolved against the local store. The procedure name is matched against the package's exports with _ and - treated as equivalent, so it can be written in either snake_case or kebab-case (get_count matches the export get-count).

--package takes either a path to a .masp file or a bare name, which is looked up in the configured packages directory. It is optional: without it, <PROCEDURE> must be the procedure's hex digest instead of its name, and the output stack is printed as raw field elements since there is no manifest to read the signature from.

Arguments are passed positionally after the target, one token per value in the procedure's signature. The signature comes from the package manifest, and it also decides how each token is read and how the result is printed:

TypeToken formExample
feltdecimal field element42
integers (u8u128, i8i128)decimal, range-checked against the type-1
booltrue, false, 1 or 0true
wordhex0x00..
account-idhex account ID, or a bech32 address naming one0x4614b8bf575eab71455e97bd394e90
asset<AMOUNT>::<FAUCET_ID>, fungible only, the faucet in either account ID spelling100::0xabcdef0123456789
records and fixed arraysone token per field, in order3 4 for point { x, y }

An account-id argument takes the same two spellings the target does, so both can be written the same way in one command line. A hex prefix of a tracked account is not one of them: resolving a prefix reads the client's store, and an argument is read on its own.

Only procedures exported from a WIT interface carry a signature. A procedure without one is still called, with one raw field element per argument written in decimal (a 0x hex literal is not accepted); the argument count is not checked and the result is printed as a stack dump.

The arguments are pushed onto the stack so that the first one ends up on top, and together they may occupy at most 16 stack values — that is all a called procedure can see.

--inputs-path takes the same TOML format as exec. The entries are loaded into the VM's advice map and are visible to the called procedure.

Example

Calling increment-count on a counter contract:

miden-client call 0x4614b8bf575eab71455e97bd394e90:increment-count --package target/miden/dev/counter-contract.masp

The command first prints the procedure's signature and its return values, then the effects the call has on the account:

Signature: increment-count() -> felt

Result: 1
The transaction will have the following effects:

No notes will be consumed.

No notes will be created as a result of this transaction.

Account Storage will not be changed.
Storage map changes:
┌──────────────────────────────────┬──────────────────────────────────┬─────────────────────────────────┐
│ Storage Slot ┆ Map Key ┆ New Value │
╞══════════════════════════════════╪══════════════════════════════════╪═════════════════════════════════╡
│ counter_contract::counter_contra ┆ 0x000000000000000000000000000000 ┆ 0x01000000000000000000000000000 │
│ ct::count_map ┆ 00000000000000000001000000000000 ┆ 0000000000000000000000000000000 │
│ ┆ 00 ┆ 0000 │
└──────────────────────────────────┴──────────────────────────────────┴─────────────────────────────────┘
Account Vault will not be changed.
Nonce incremented by: 1.

A procedure that only reads leaves the transaction with no effects at all, which the transaction kernel does not allow. The result is still printed, followed by a note that the transaction was rejected for having no effects.

The call is executed locally. No proof is generated, nothing is submitted to the network, and the account's stored state is left unchanged.

Calling an account that isn't tracked locally

If the target account is not in the local store, the client reads its state from the network and runs the call from one of your own accounts — the default account if one is set, otherwise the first usable one. That account only runs the call; nothing about it changes.

This requires the target account's state to be public, so the node can serve it, and it requires at least one of your own accounts to run the call from (accounts whose local state is out of sync with the node are skipped). Such calls can only read the account: the transaction kernel rejects any procedure that would mutate an account other than the one running the transaction, so only the return values are printed. No state delta is shown either — the only account a delta could describe is the one running the call, whose changes come from its own authentication and nonce rather than from the procedure. The account has to be named by its full hex ID or its bech32 address — a partial ID is resolved against the local store, which by definition does not have this account.

miden-client call 0x4614b8bf575eab71455e97bd394e90:get-count --package target/miden/dev/counter-contract.masp
Account 0x4614b8bf575eab71455e97bd394e90 isn't tracked locally; reading its state from the network and running the call from your account 0x8fa1c2....

Signature: get-count() -> felt

Result: 1

A call on an account read from the network can only read it; no state delta.

The account state read this way comes from the transaction's reference block, which the wallet running the call picks. It is not revalidated against the account's current on-chain state, so run miden-client sync first if you need a recent value.

note-transport

Send and fetch private notes using the transport layer.