linera-io · ma2bd · Sep 15, 2025 · Sep 15, 2025 · Sep 15, 2025 · Sep 15, 2025
diff --git a/CLI.md b/CLI.md
@@ -122,9 +122,10 @@ Client implementation and command-line tool for the Linera blockchain
 
 ###### **Options:**
 
-* `--wallet <WALLET_STATE_PATH>` — Sets the file storing the private state of user chains (an empty one will be created if missing)
-* `--keystore <KEYSTORE_PATH>` — Sets the file storing the keystore state
-* `-w`, `--with-wallet <WITH_WALLET>` — Given an ASCII alphanumeric parameter `X`, read the wallet state and the wallet storage config from the environment variables `LINERA_WALLET_{X}` and `LINERA_STORAGE_{X}` instead of `LINERA_WALLET` and `LINERA_STORAGE`
+* `--wallet <WALLET_STATE_PATH>` — DEPRECATED: Use --with-wallet=NAME instead. Sets the file storing the private state of user chains (an empty one will be created if missing)
+* `--keystore <KEYSTORE_PATH>` — DEPRECATED: Use --with-wallet=NAME instead. Sets the file storing the keystore state
+* `--home-directory <HOME_DIRECTORY>` — Sets the home directory for storing Linera wallets. Alternatively, one may set the environment variable LINERA_HOME
+* `-w`, `--with-wallet <NAME>` — Name of the wallet to be used. Data will be stored in the corresponding subdirectory of the home directory -- unless other (deprecated) options are used
 * `--send-timeout-ms <SEND_TIMEOUT>` — Timeout for sending queries (milliseconds)
 
   Default value: `4000`

diff --git a/README.md b/README.md
@@ -93,10 +93,8 @@ FAUCET_URL=http://localhost:8080
 #   LINERA_TMP_DIR=$(mktemp -d)
 #   FAUCET_URL=https://faucet.testnet-XXX.linera.net  # for some value XXX
 
-# Set the path of the future wallet.
-export LINERA_WALLET="$LINERA_TMP_DIR/wallet.json"
-export LINERA_KEYSTORE="$LINERA_TMP_DIR/keystore.json"
-export LINERA_STORAGE="rocksdb:$LINERA_TMP_DIR/client.db"
+# Set the home directory for future wallets.
+export LINERA_HOME="$LINERA_TMP_DIR"
 
 # Initialize a new user wallet.
 linera wallet init --faucet $FAUCET_URL

diff --git a/examples/amm/README.md b/examples/amm/README.md
@@ -53,9 +53,8 @@ linera_spawn linera net up --with-faucet --faucet-port $FAUCET_PORT
 Create the user wallet and add chains to it:
 
 ```bash
-export LINERA_WALLET="$LINERA_TMP_DIR/wallet.json"
-export LINERA_KEYSTORE="$LINERA_TMP_DIR/keystore.json"
-export LINERA_STORAGE="rocksdb:$LINERA_TMP_DIR/client.db"
+# Set the home directory for future wallets.
+export LINERA_HOME="$LINERA_TMP_DIR"
 
 linera wallet init --faucet $FAUCET_URL
 

diff --git a/examples/counter/README.md b/examples/counter/README.md
@@ -40,9 +40,8 @@ linera_spawn linera net up --with-faucet --faucet-port $LINERA_FAUCET_PORT
 Create the user wallet and add chains to it:
 
 ```bash
-export LINERA_WALLET="$LINERA_TMP_DIR/wallet.json"
-export LINERA_KEYSTORE="$LINERA_TMP_DIR/keystore.json"
-export LINERA_STORAGE="rocksdb:$LINERA_TMP_DIR/client.db"
+# Set the home directory for future wallets.
+export LINERA_HOME="$LINERA_TMP_DIR"
 
 linera wallet init --faucet $LINERA_FAUCET_URL
 

diff --git a/examples/crowd-funding/README.md b/examples/crowd-funding/README.md
@@ -65,12 +65,8 @@ linera_spawn linera net up --with-faucet --faucet-port $FAUCET_PORT
 Create the user wallets and add chains to them:
 
 ```bash
-export LINERA_WALLET_1="$LINERA_TMP_DIR/wallet_1.json"
-export LINERA_KEYSTORE_1="$LINERA_TMP_DIR/keystore_1.json"
-export LINERA_STORAGE_1="rocksdb:$LINERA_TMP_DIR/client_1.db"
-export LINERA_WALLET_2="$LINERA_TMP_DIR/wallet_2.json"
-export LINERA_KEYSTORE_2="$LINERA_TMP_DIR/keystore_2.json"
-export LINERA_STORAGE_2="rocksdb:$LINERA_TMP_DIR/client_2.db"
+# Set the home directory for future wallets.
+export LINERA_HOME="$LINERA_TMP_DIR"
 
 linera --with-wallet 1 wallet init --faucet $FAUCET_URL
 linera --with-wallet 2 wallet init --faucet $FAUCET_URL
@@ -83,9 +79,6 @@ OWNER_1="${INFO_1[1]}"
 OWNER_2="${INFO_2[1]}"
 ```
 
-Note that `linera --with-wallet 1` is equivalent to `linera --wallet "$LINERA_WALLET_1" --keystore "$LINERA_KEYSTORE_1"
---storage "$LINERA_STORAGE_1"`.
-
 The command below can be used to list the chains created for the test as known by each
 wallet:
 

diff --git a/examples/fungible/README.md b/examples/fungible/README.md
@@ -57,9 +57,8 @@ linera_spawn linera net up --with-faucet --faucet-port $FAUCET_PORT
 Create the user wallet and add chains to it:
 
 ```bash
-export LINERA_WALLET="$LINERA_TMP_DIR/wallet.json"
-export LINERA_KEYSTORE="$LINERA_TMP_DIR/keystore.json"
-export LINERA_STORAGE="rocksdb:$LINERA_TMP_DIR/client.db"
+# Set the home directory for future wallets.
+export LINERA_HOME="$LINERA_TMP_DIR"
 
 linera wallet init --faucet $FAUCET_URL
 

diff --git a/examples/gen-nft/README.md b/examples/gen-nft/README.md
@@ -52,9 +52,8 @@ linera_spawn linera net up --with-faucet --faucet-port $FAUCET_PORT
 Create the user wallet and add chains to it:
 
 ```bash
-export LINERA_WALLET="$LINERA_TMP_DIR/wallet.json"
-export LINERA_KEYSTORE="$LINERA_TMP_DIR/keystore.json"
-export LINERA_STORAGE="rocksdb:$LINERA_TMP_DIR/client.db"
+# Set the home directory for future wallets.
+export LINERA_HOME="$LINERA_TMP_DIR"
 
 linera wallet init --faucet $FAUCET_URL
 

diff --git a/examples/hex-game/README.md b/examples/hex-game/README.md
@@ -48,12 +48,8 @@ linera_spawn linera net up --with-faucet --faucet-port $FAUCET_PORT
 Create the user wallets and add chains to them:
 
 ```bash
-export LINERA_WALLET_1="$LINERA_TMP_DIR/wallet_1.json"
-export LINERA_KEYSTORE_1="$LINERA_TMP_DIR/keystore_1.json"
-export LINERA_STORAGE_1="rocksdb:$LINERA_TMP_DIR/client_1.db"
-export LINERA_WALLET_2="$LINERA_TMP_DIR/wallet_2.json"
-export LINERA_KEYSTORE_2="$LINERA_TMP_DIR/keystore_2.json"
-export LINERA_STORAGE_2="rocksdb:$LINERA_TMP_DIR/client_2.db"
+# Set the home directory for future wallets.
+export LINERA_HOME="$LINERA_TMP_DIR"
 
 linera --with-wallet 1 wallet init --faucet $FAUCET_URL
 linera --with-wallet 2 wallet init --faucet $FAUCET_URL
@@ -66,9 +62,6 @@ OWNER_1="${INFO_1[1]}"
 OWNER_2="${INFO_2[1]}"
 ```
 
-Note that `linera --with-wallet 1` or `linera -w1` is equivalent to `linera --wallet
-"$LINERA_WALLET_1"  --keystore "$LINERA_KEYSTORE_1" --storage "$LINERA_STORAGE_1"`.
-
 ### Creating the Game Chain
 
 We open a new chain owned by both `$OWNER_1` and `$OWNER_2`, create the application on it, and

diff --git a/examples/how-to/perform-http-requests/README.md b/examples/how-to/perform-http-requests/README.md
@@ -90,9 +90,8 @@ FAUCET_URL=http://localhost:8081
 We then create a wallet and obtain a chain to use with the application.
 
 ```bash
-export LINERA_WALLET="$LINERA_TMP_DIR/wallet.json"
-export LINERA_KEYSTORE="$LINERA_TMP_DIR/keystore.json"
-export LINERA_STORAGE="rocksdb:$LINERA_TMP_DIR/client.db"
+# Set the home directory for future wallets.
+export LINERA_HOME="$LINERA_TMP_DIR"
 
 linera wallet init --faucet $FAUCET_URL
 

diff --git a/examples/llm/README.md b/examples/llm/README.md
@@ -55,9 +55,8 @@ linera_spawn linera net up --with-faucet --faucet-port $FAUCET_PORT
 Create the user wallet and add chains to it:
 
 ```bash
-export LINERA_WALLET="$LINERA_TMP_DIR/wallet.json"
-export LINERA_KEYSTORE="$LINERA_TMP_DIR/keystore.json"
-export LINERA_STORAGE="rocksdb:$LINERA_TMP_DIR/client.db"
+# Set the home directory for future wallets.
+export LINERA_HOME="$LINERA_TMP_DIR"
 
 linera wallet init --faucet $FAUCET_URL
 

diff --git a/examples/matching-engine/README.md b/examples/matching-engine/README.md
@@ -64,9 +64,8 @@ linera_spawn linera net up --with-faucet --faucet-port $FAUCET_PORT
 Create the user wallet and add chains to it:
 
 ```bash
-export LINERA_WALLET="$LINERA_TMP_DIR/wallet.json"
-export LINERA_KEYSTORE="$LINERA_TMP_DIR/keystore.json"
-export LINERA_STORAGE="rocksdb:$LINERA_TMP_DIR/client.db"
+# Set the home directory for future wallets.
+export LINERA_HOME="$LINERA_TMP_DIR"
 
 linera wallet init --faucet $FAUCET_URL
 

diff --git a/examples/native-fungible/README.md b/examples/native-fungible/README.md
@@ -35,9 +35,8 @@ linera_spawn linera net up --with-faucet --faucet-port $LINERA_FAUCET_PORT
 Create the user wallet and add chains to it:
 
 ```bash
-export LINERA_WALLET="$LINERA_TMP_DIR/wallet.json"
-export LINERA_KEYSTORE="$LINERA_TMP_DIR/keystore.json"
-export LINERA_STORAGE="rocksdb:$LINERA_TMP_DIR/client.db"
+# Set the home directory for future wallets.
+export LINERA_HOME="$LINERA_TMP_DIR"
 
 linera wallet init --faucet $LINERA_FAUCET_URL
 

diff --git a/examples/non-fungible/README.md b/examples/non-fungible/README.md
@@ -52,9 +52,8 @@ linera_spawn linera net up --with-faucet --faucet-port $FAUCET_PORT
 Create the user wallet and add chains to it:
 
 ```bash
-export LINERA_WALLET="$LINERA_TMP_DIR/wallet.json"
-export LINERA_KEYSTORE="$LINERA_TMP_DIR/keystore.json"
-export LINERA_STORAGE="rocksdb:$LINERA_TMP_DIR/client.db"
+# Set the home directory for future wallets.
+export LINERA_HOME="$LINERA_TMP_DIR"
 
 linera wallet init --faucet $FAUCET_URL
 

diff --git a/examples/rfq/README.md b/examples/rfq/README.md
@@ -65,12 +65,8 @@ linera_spawn linera net up --with-faucet --faucet-port $FAUCET_PORT
 Create the user wallets and add chains to them:
 
 ```bash
-export LINERA_WALLET_1="$LINERA_TMP_DIR/wallet_1.json"
-export LINERA_KEYSTORE_1="$LINERA_TMP_DIR/keystore_1.json"
-export LINERA_STORAGE_1="rocksdb:$LINERA_TMP_DIR/client_1.db"
-export LINERA_WALLET_2="$LINERA_TMP_DIR/wallet_2.json"
-export LINERA_KEYSTORE_2="$LINERA_TMP_DIR/keystore_2.json"
-export LINERA_STORAGE_2="rocksdb:$LINERA_TMP_DIR/client_2.db"
+# Set the home directory for future wallets.
+export LINERA_HOME="$LINERA_TMP_DIR"
 
 linera --with-wallet 1 wallet init --faucet $FAUCET_URL
 linera --with-wallet 2 wallet init --faucet $FAUCET_URL
@@ -83,9 +79,6 @@ OWNER_1="${INFO_1[1]}"
 OWNER_2="${INFO_2[1]}"
 ```
 
-Note that `linera --with-wallet 1` is equivalent to `linera --wallet "$LINERA_WALLET_1" --keystore "$LINERA_KEYSTORE_1"
---storage "$LINERA_STORAGE_1"`.
-
 Now, we can publish the fungible module and create the fungible applications.
 
 ```bash

diff --git a/examples/social/README.md b/examples/social/README.md
@@ -53,12 +53,8 @@ linera_spawn linera net up --with-faucet --faucet-port $FAUCET_PORT
 Create the user wallets and add chains to them:
 
 ```bash
-export LINERA_WALLET_1="$LINERA_TMP_DIR/wallet_1.json"
-export LINERA_KEYSTORE_1="$LINERA_TMP_DIR/keystore_1.json"
-export LINERA_STORAGE_1="rocksdb:$LINERA_TMP_DIR/client_1.db"
-export LINERA_WALLET_2="$LINERA_TMP_DIR/wallet_2.json"
-export LINERA_KEYSTORE_2="$LINERA_TMP_DIR/keystore_2.json"
-export LINERA_STORAGE_2="rocksdb:$LINERA_TMP_DIR/client_2.db"
+# Set the home directory for future wallets.
+export LINERA_HOME="$LINERA_TMP_DIR"
 
 linera --with-wallet 1 wallet init --faucet $FAUCET_URL
 linera --with-wallet 2 wallet init --faucet $FAUCET_URL
@@ -71,9 +67,6 @@ OWNER_1="${INFO_1[3]}"
 OWNER_2="${INFO_2[3]}"
 ```
 
-Note that `linera --with-wallet 1` is equivalent to `linera --wallet "$LINERA_WALLET_1" --keystore "$LINERA_KEYSTORE_1"
---storage "$LINERA_STORAGE_1"`.
-
 Compile the `social` example and create an application with it:
 
 ```bash

diff --git a/linera-client/src/client_options.rs b/linera-client/src/client_options.rs
@@ -45,19 +45,25 @@ util::impl_from_infallible!(Error);
 
 #[derive(Clone, clap::Parser)]
 pub struct ClientContextOptions {
-    /// Sets the file storing the private state of user chains (an empty one will be created if missing)
+    /// DEPRECATED: Use --with-wallet=NAME instead. Sets the file
+    /// storing the private state of user chains (an empty one will be created if missing)
     #[arg(long = "wallet")]
     pub wallet_state_path: Option<PathBuf>,
 
-    /// Sets the file storing the keystore state.
+    /// DEPRECATED: Use --with-wallet=NAME instead. Sets the file
+    /// storing the keystore state.
     #[arg(long = "keystore")]
     pub keystore_path: Option<PathBuf>,
 
-    /// Given an ASCII alphanumeric parameter `X`, read the wallet state and the wallet
-    /// storage config from the environment variables `LINERA_WALLET_{X}` and
-    /// `LINERA_STORAGE_{X}` instead of `LINERA_WALLET` and
-    /// `LINERA_STORAGE`.
-    #[arg(long, short = 'w', value_parser = util::parse_ascii_alphanumeric_string)]
+    /// Sets the home directory for storing Linera wallets. Alternatively, one may set the
+    /// environment variable LINERA_HOME.
+    #[arg(long, env = "LINERA_HOME")]
+    pub home_directory: Option<PathBuf>,
+
+    /// Name of the wallet to be used. Data will be stored in the corresponding
+    /// subdirectory of the home directory -- unless other (deprecated) options are
+    /// used.
+    #[arg(long, short = 'w', value_name = "NAME", value_parser = util::parse_ascii_alphanumeric_string)]
     pub with_wallet: Option<String>,
 
     /// Timeout for sending queries (milliseconds)

diff --git a/linera-service/src/cli/main.rs b/linera-service/src/cli/main.rs
@@ -1814,17 +1814,21 @@ impl ClientOptions {
             .unwrap_or_default()
     }
 
-    fn config_path() -> Result<PathBuf, Error> {
-        let mut config_dir = dirs::config_dir().ok_or_else(|| anyhow!(
+    fn config_path(&self, file: &str) -> Result<PathBuf, Error> {
+        let mut path = self.context_options.home_directory.clone().or_else(dirs::config_dir).ok_or_else(|| anyhow!(
             "Default wallet directory is not supported in this platform: please specify storage and wallet paths"
         ))?;
-        config_dir.push("linera");
-        if !config_dir.exists() {
-            debug!("Creating default wallet directory {}", config_dir.display());
-            fs_err::create_dir_all(&config_dir)?;
+        path.push("linera");
+        if let Some(name) = &self.context_options.with_wallet {
+            path.push(name);
         }
-        info!("Using default wallet directory {}", config_dir.display());
-        Ok(config_dir)
+        if !path.exists() {
+            debug!("Creating default wallet directory {}", path.display());
+            fs_err::create_dir_all(&path)?;
+        }
+        path.push(file);
+        info!("Using wallet path {}", path.display());
+        Ok(path)
     }
 
     fn storage_config(&self) -> Result<StorageConfig, Error> {
@@ -1834,14 +1838,15 @@ impl ClientOptions {
         let suffix = self.suffix();
         let storage_env_var = env::var(format!("LINERA_STORAGE{suffix}")).ok();
         if let Some(config) = storage_env_var {
+            warn!("LINERA_STORAGE_* is deprecated. Use --with-wallet=NAME or --storage=CONFIG instead.");
             return config.parse();
         }
         cfg_if::cfg_if! {
             if #[cfg(feature = "rocksdb")] {
                 let spawn_mode =
                     linera_views::rocks_db::RocksDbSpawnMode::get_spawn_mode_from_runtime();
                 let inner_storage_config = linera_service::storage::InnerStorageConfig::RocksDb {
-                    path: Self::config_path()?.join("wallet.db"),
+                    path: self.config_path("wallet.db")?,
                     spawn_mode,
                 };
                 let namespace = "default".to_string();
@@ -1857,28 +1862,30 @@ impl ClientOptions {
 
     fn wallet_path(&self) -> Result<PathBuf, Error> {
         if let Some(path) = &self.context_options.wallet_state_path {
+            warn!("Option --wallet is deprecated. Use --with-wallet=NAME instead.");
             return Ok(path.clone());
         }
         let suffix = self.suffix();
         let wallet_env_var = env::var(format!("LINERA_WALLET{suffix}")).ok();
         if let Some(path) = wallet_env_var {
+            warn!("LINERA_WALLET_* is deprecated. Use --with-wallet=NAME instead.");
             return Ok(path.parse()?);
         }
-        let config_path = Self::config_path()?;
-        Ok(config_path.join("wallet.json"))
+        self.config_path("wallet.json")
     }
 
     fn keystore_path(&self) -> Result<PathBuf, Error> {
         if let Some(path) = &self.context_options.keystore_path {
+            warn!("Option --keystore is deprecated. Use --with-wallet=NAME instead.");
             return Ok(path.clone());
         }
         let suffix = self.suffix();
         let keystore_env_var = env::var(format!("LINERA_KEYSTORE{suffix}")).ok();
         if let Some(path) = keystore_env_var {
+            warn!("LINERA_KEYSTORE_* is deprecated. Use --with-wallet=NAME instead.");
             return Ok(path.parse()?);
         }
-        let config_path = Self::config_path()?;
-        Ok(config_path.join("keystore.json"))
+        self.config_path("keystore.json")
     }
 
     pub fn create_wallet(

diff --git a/linera-service/src/cli/net_up_utils.rs b/linera-service/src/cli/net_up_utils.rs
@@ -311,29 +311,16 @@ async fn print_messages_and_create_faucet(
 
     eprintln!(
         "To use the admin wallet of this test network, you may set \
-         the environment variables LINERA_WALLET, LINERA_KEYSTORE, \
-         and LINERA_STORAGE as follows.\n"
+         the environment variable LINERA_HOME as follows.\n"
     );
     println!(
         "{}",
         format!(
-            "export LINERA_WALLET=\"{}\"",
-            client.wallet_path().display(),
+            "export LINERA_HOME=\"{}\"",
+            client.path_provider.path().display()
         )
         .bold(),
     );
-    println!(
-        "{}",
-        format!(
-            "export LINERA_KEYSTORE=\"{}\"",
-            client.keystore_path().display(),
-        )
-        .bold()
-    );
-    println!(
-        "{}",
-        format!("export LINERA_STORAGE=\"{}\"", client.storage_path()).bold(),
-    );
 
     let wallet = client.load_wallet()?;
     let chains = wallet.chain_ids();