> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genlabs.co/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI configuration

> Configure the gen CLI: named RPC environments, default headers, wallet root, and where the config file lives.

`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.

<Note>
  **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](#migrating-an-old-config).
</Note>

## Where the config lives

The CLI stores its client config at `~/.gen/client_config.yml`. Print the resolved path:

```bash theme={null}
gen config 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](/reference/cli/wallet).

## Config schema

```yaml theme={null}
client:
  environments:
    - name: local
      rpc_url: "http://127.0.0.1:30001"
    - name: mainnet
      rpc_url: "https://rpc.mainnet.example.com"
      rpc_transport: grpc          # optional: jsonrpc (default) | grpc
      headers:                     # optional default headers for this env
        authorization: "Bearer <token>"
  active_env: local                # env used when --env is not passed
  wallet_root: "/custom/path/to/wallets"   # optional
```

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.

```bash theme={null}
gen config env new --name devnet --rpc https://devnet.genlabs.co/rpc/
```

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 `*`.

```bash theme={null}
gen config env list
```

### `gen config env show <name>`

Show one environment's detail. Header values are redacted by default; pass `--show-secrets` to reveal them.

```bash theme={null}
gen config env show devnet
```

```text theme={null}
name:          devnet [active]
rpc_url:       https://devnet.genlabs.co/rpc/
rpc_transport: jsonrpc (default)
headers:
  authorization: <redacted>
  (header values hidden; use --show-secrets to reveal)
```

Add `--show-secrets` to reveal the header values:

```bash theme={null}
gen config env show devnet --show-secrets
```

### `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.

```bash theme={null}
gen config env set devnet --header "authorization: Bearer <your-jwt>"
```

### `gen config env switch <name>`

Set the active environment.

```bash theme={null}
gen config env switch devnet
```

### `gen config env delete <name>`

Remove an environment.

```bash theme={null}
gen config env delete devnet
```

## `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.

```bash theme={null}
gen config init
```

## `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.

```bash theme={null}
gen config show
```

```text theme={null}
Global settings:
  wallet root:  (default: ~/.gen/wallets)

Environments:
  local                 http://127.0.0.1:30001
* devnet                https://devnet.genlabs.co/rpc/
  Run `gen config env show <name>` to see an environment's full configuration.
```

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](#wallet-root-resolution)).

```bash theme={null}
gen config set wallet-root /custom/path/to/wallets
gen config unset wallet-root
```

## Configuring for DevNet

The sequence a new partner runs after receiving their JWT:

```bash theme={null}
gen config env new --name devnet --rpc https://devnet.genlabs.co/rpc/
gen config env set devnet --header "authorization: Bearer <jwt-from-gen-labs>"
gen config env switch devnet
gen config show
```

After this, `gen wallet` and `gen client` calls reach DevNet automatically. For the current URL and access policy, see [Network status](/user-guide/network-status).

To hit a different endpoint for a single command without switching, pass `--env`:

```bash theme={null}
gen client --env mainnet get-account --account grd@1...
```

## 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

| Setting   | Precedence (highest → lowest)                                                  |
| --------- | ------------------------------------------------------------------------------ |
| RPC URL   | `--rpc-url` → `--env` → active env → built-in local (`http://127.0.0.1:30001`) |
| Transport | `--rpc-transport` → env → `jsonrpc`                                            |
| Headers   | `--header` flags merge over env headers                                        |

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](/user-guide/network-status): the current RPC endpoint and the access requirements for each network.
* [gen wallet](/reference/cli/wallet): wallet store layout and how the active wallet is selected.
* [Quickstart](/quickstart/index): configure the CLI against DevNet and send your first transfer.