Skip to main content
gen config manages the persisted client configuration the CLI uses to reach an RPC endpoint. As of 0.17.0 the config holds one or more named RPC environments (for example local, devnet, mainnet) instead of a single RPC URL. You define environments, mark one active, and override per command. Each environment carries its own RPC URL, optional transport, and optional default headers. You can always override the active environment on a single call with the global --env <name> flag, or override individual values with --rpc-url <URL>, --rpc-transport <jsonrpc|grpc>, and --header <NAME=VALUE>. The persisted file is the default; flags win for that invocation only.
Upgrading from 0.16.x? The config schema changed. The old client.rpc_url / gen config set rpc-url / gen config set header form is gone. A config still in the old format is rejected on load with an IncompatibleConfig error — see Migrating an old config.

​
Where the config lives

The CLI stores its client config at ~/.gen/client_config.yml. Print the resolved path:
The file is plain YAML. You can edit it by hand, but the gen config subcommands handle the read-modify-write for you and avoid format mistakes. Wallets are stored separately under ~/.gen/wallets/ (or the configured wallet_root); see gen wallet.

​
Config schema

Each environment has a name, an rpc_url, an optional rpc_transport, and optional headers. active_env names the environment used when --env is not passed. wallet_root is a global (non-env) setting. The CLI works zero-config: a built-in local environment (http://127.0.0.1:30001) is virtual until gen config init (or the first config-writing command) persists it.

​
gen config env

Manage named environments.

​
gen config env new

Create an environment. --rpc defaults to the built-in local URL. Creating an environment does not change the active one.
Flags: --name <name> (required), --rpc <url>, --rpc-transport <grpc|jsonrpc>, --header NAME=VALUE (repeatable).

​
gen config env list

List environments. The active one is marked with *.

​
gen config env show <name>

Show one environment’s detail. Header values are redacted by default; pass --show-secrets to reveal them.
Add --show-secrets to reveal the header values:

​
gen config env set [<name>]

Edit an environment in place (the active env if no name is given). Only the flags you pass change; headers merge over existing headers. At least one field is required.

​
gen config env switch <name>

Set the active environment.

​
gen config env delete <name>

Remove an environment.

​
gen config init

Seed the config file with an active local environment. This is now optional — the env subcommands create the file on demand — and safe to run on a fresh machine.

​
gen config show

Print the stored config. The output renders a Global settings section (wallet_root) and an Environments section listing each environment’s name and RPC URL, with the active environment marked *. Headers are not shown here — use gen config env show <name> for an environment’s full detail.
The CLI auto-injects the reserved x-gen-protocol-version header to pin the wire-protocol version it speaks. You cannot set it manually.

​
gen config set / unset wallet-root

Manage the persisted wallet store path. This value is now honored by all wallet commands (see Wallet root resolution).

​
Configuring for DevNet

The sequence a new partner runs after receiving their JWT:
After this, gen wallet and gen client calls reach DevNet automatically. For the current URL and access policy, see Network status. To hit a different endpoint for a single command without switching, pass --env:

​
Global flags

These global flags apply to every gen client and gen wallet subcommand that talks to RPC:
  • --env <name>: use a named environment for this invocation only.
  • --rpc-url <URL>: override the environment’s RPC URL for this call only.
  • --rpc-transport <jsonrpc|grpc>: override the transport for this call only.
  • --header <NAME=VALUE>: add or override a header for this call only. Accepts name=value or quoted 'name: value'. Repeat for multiple headers; values merge over env headers.
  • -j, --json: emit the JSON envelope ({ ok, command, timestamp, result | error }) instead of human output. A proper global flag — works in any position.
  • --wallet-root <PATH>: point at a wallet store other than the configured/default location.

​
Resolution precedence

If environments exist but none is active, RPC commands fail with NoActiveEnvironment rather than guessing.

​
Wallet root resolution

Wallet commands resolve the store path as: --wallet-root flag → persisted client.wallet_root → WalletStore default. A malformed config falls back to the default rather than breaking wallet commands.

​
Secret hygiene

Header values (such as Authorization tokens) are redacted by default in gen config env show and gen config env list, in both text and JSON output. Pass --show-secrets to reveal them — mirroring gen wallet export private-key --unsafe.

​
Migrating an old config

Any config that does not match the current schema — the old single-RPC client.rpc_url, unknown fields, wrong types, or hand-edit mistakes — is rejected on load with a single actionable IncompatibleConfig error. The check is general, not a hardcoded old-key list. To recover:
  1. Back up ~/.gen/client_config.yml.
  2. Remove or fix the file.
  3. Re-create your environments with gen config env new.

​
See also

  • Network status: the current RPC endpoint and the access requirements for each network.
  • gen wallet: wallet store layout and how the active wallet is selected.
  • Quickstart: configure the CLI against DevNet and send your first transfer.