Skip to main content
gen wallet manages the local wallet store used to sign Grid activations. Wallets live under ~/.gen/wallets/: keystore.json holds the wallet records and config.toml tracks the active wallet. New wallets are encrypted with a password by default; leaving the password blank, or passing --plaintext, stores secret material unencrypted. This page covers wallet identity and key management only. For balance queries, transfers, and faucet bootstrap, see gen wallet transfers. For RPC connection settings (--rpc-url, headers), see CLI configuration.

​
Common options

These options work on every gen wallet subcommand:
  • --json, -j: emit a single JSON envelope ({ ok, command, timestamp, result | error }) instead of human output. Required for scripting.
  • --plaintext: on commands that store new secret material (create, import seed, import mnemonic, import private-key), skip password encryption and write the wallet in plaintext. Unsafe; use only for disposable local automation.
  • --wallet <NAME>: on commands that take an optional positional NAME, this is the named-flag form of the same argument.
Wallet selection precedence for commands that need an active wallet:
  1. explicit NAME argument or --wallet <NAME>
  2. active wallet recorded in ~/.gen/wallets/config.toml
  3. error if neither is set
Hex output (public keys, private keys, seeds) is always 0x-prefixed.

​
gen wallet init

Interactive onboarding flow. Walks through choosing seed create/import, mnemonic create/import, or private-key import; prompts for an optional name; prompts for an encryption password; and sets the resulting wallet as active. 
gen wallet init
Output: prompts to stdin/stdout, then a confirmation that the wallet was created and set active. Use this when you do not yet have a wallet and want a guided setup.

​
gen wallet create

Create a new wallet from fresh CSPRNG entropy. Defaults to a 32-byte seed; pass --mnemonic to generate a BIP-39 phrase instead. 
gen wallet create [NAME] [--mnemonic [--12-word]] [--plaintext]
Key flags:
  • --mnemonic: generate a BIP-39 recovery phrase instead of a raw seed.
  • --12-word: with --mnemonic, produce a 12-word phrase instead of the default 24-word phrase.
  • --plaintext: store the wallet without password encryption.
Example: 
gen wallet create alice --mnemonic --12-word
Output: prints the wallet name, the Address: (grd@... 1-part account locator), the public key, and the recovery material (seed or mnemonic) once. Record the recovery material immediately; the store does not retain it.

​
gen wallet import

Import a wallet from existing key material. Each flavor is its own subcommand.

​
gen wallet import seed

Import from a 32-byte seed (64 hex characters, optionally 0x-prefixed). 
gen wallet import seed [NAME] [--seed-file <PATH>] [--derivation-path <PATH>] [--plaintext]
Key flags:
  • --seed-file <PATH>: read the seed from a file instead of prompting.
  • --derivation-path <PATH>: custom BIP-44 path, e.g. m/44'/218'/0'/0/7.
Example: 
gen wallet import seed alice --seed-file ./alice.seed
Output: confirms the imported wallet name, address, and public key.

​
gen wallet import mnemonic

Import from a BIP-39 recovery phrase. 
gen wallet import mnemonic [NAME] [--mnemonic-file <PATH>] [--derivation-path <PATH>] [--plaintext]
Key flags:
  • --mnemonic-file <PATH>: read the phrase from a file instead of prompting.
  • --derivation-path <PATH>: custom BIP-44 path.
Example: 
gen wallet import mnemonic alice --mnemonic-file ./alice.mnemonic
Output: confirms the imported wallet name, address, and public key.

​
gen wallet import private-key

Import from a raw private key (hex, optionally 0x-prefixed). 
gen wallet import private-key [NAME] [--private-key-file <PATH>] [--plaintext]
Key flags:
  • --private-key-file <PATH>: read the private key from a file instead of prompting.
Example: 
gen wallet import private-key alice --private-key-file ./alice.key
Output: confirms the imported wallet name, address, and public key.

​
gen wallet import encrypted

Import a portable encrypted wallet bundle previously produced by gen wallet export encrypted. 
gen wallet import encrypted <PATH> [NAME] [--wallet <NAME>]
Prompts for the bundle password, validates the decrypted key against the bundle metadata, prompts for a destination wallet name if not supplied, then prompts for a local storage password. Sets the imported wallet active. Example: 
gen wallet import encrypted ./alice.wallet alice-restored
Output: confirms the destination wallet name and address.

​
gen wallet list

Show all stored wallets as a table. 
gen wallet list
Columns: NAME, ACTIVE, STORAGE, SOURCE, ADDRESS. With --json, returns an array of records with the same fields.

​
gen wallet show

Show metadata for one wallet. With no argument, shows the active wallet. 
gen wallet show [NAME] [--public-key-only] [--account-address-only]
Key flags:
  • --public-key-only: print only the public key (0x-prefixed hex).
  • --account-address-only: print only the grd@... account locator. Useful for piping into --to flags.
Example: 
gen wallet show alice --account-address-only
Output: human-readable metadata block with Address and Public key, or just the requested field. JSON mode returns a result object with name, account, public_key_hex, storage, and source.

​
gen wallet set-active

Set which wallet is used by default for wallet-backed commands. 
gen wallet set-active alice
Output: confirmation that the active wallet has changed. Persisted to ~/.gen/wallets/config.toml.

​
gen wallet rename

Rename a stored wallet. If the renamed wallet was active, it stays active under the new name. 
gen wallet rename alice alice-prod
Output: confirmation of the rename.

​
gen wallet remove

Delete a wallet from the local store. If the removed wallet was active, the active wallet is cleared. 
gen wallet remove alice
Output: confirmation of the removal. There is no recovery; make sure recovery material is backed up first.

​
gen wallet export

Export wallet material. Two flavors: raw private key, or a portable encrypted bundle.

​
gen wallet export private-key

Print the wallet’s private key to stdout as 0x-prefixed hex. Requires explicit --unsafe acknowledgement. 
gen wallet export private-key <NAME> --unsafe
Example: 
gen wallet export private-key alice --unsafe
Output: a single 0x-prefixed hex string on stdout. This is the only command in the wallet surface that prints the private key; treat the output as a secret.

​
gen wallet export encrypted

Write a portable encrypted wallet bundle to a file. Secret material never touches stdout. 
gen wallet export encrypted <NAME> --output <PATH>
If the wallet is already encrypted, the bundle inherits the wallet’s existing password. If the wallet is plaintext, the command prompts for a new bundle password. Example: 
gen wallet export encrypted alice --output ./alice.wallet
Output: confirmation that the bundle was written. Restore on another machine with gen wallet import encrypted.

​
See also