Configuration

The xyz CLI uses a layered configuration system. This guide explains how to configure the CLI for different environments.

Configuration Commands

Set a Value

xyz config set <key> <value>

Get a Value

xyz config get <key>

List All Values

xyz config list

Available Configuration Keys

Key	Description	Default	Valid Values
`node`	RPC endpoint	`tcp://localhost:26657`	URL
`chain-id`	Chain identifier	`xyz-testnet-1`	String
`keyring-backend`	Key storage method	`os`	`os`, `file`, `test`
`home`	Data directory	`~/.xyz`	Path
`cw20-code-id`	CW20 contract code	-	Positive integer
`cw20-tokens`	Tracked token contracts	-	Comma-separated addresses

Setting Up for Different Networks

Local Development

xyz config set node tcp://localhost:26657
xyz config set chain-id xyz-testnet-1
xyz config set keyring-backend test

Testnet

xyz config set node tcp://rpc.testnet.xyz.com:26657
xyz config set chain-id xyz-testnet-1
xyz config set keyring-backend os

Production

xyz config set node tcp://rpc.xyz.com:26657
xyz config set chain-id xyz-mainnet-1
xyz config set keyring-backend os

Configuration File

Configuration is stored in ~/.xyz/config.yaml:

node: tcp://localhost:26657
chain-id: xyz-testnet-1
keyring-backend: os
cw20-code-id: 1
cw20-tokens:
  - xyz1tokencontract1...
  - xyz1tokencontract2...

The config file is created automatically when you first run xyz config set. File permissions are set to 0600 for security.

Environment Variables

Override any config value with environment variables:

# Format: XYZ_<KEY>
export XYZ_NODE=tcp://rpc.testnet.xyz.com:26657
export XYZ_CHAIN_ID=xyz-testnet-1
export XYZ_KEYRING_BACKEND=os

Precedence

Flags - --node tcp://... (highest)
Environment - XYZ_NODE=tcp://...
Config file - ~/.xyz/config.yaml
Defaults (lowest)

Keyring Backend

The keyring backend determines how private keys are stored:

OS (Recommended)
File
Test

Uses the operating system’s secure keychain:

xyz config set keyring-backend os

Platform	Storage
macOS	Keychain Access
Windows	Credential Manager
Linux	Secret Service API

Pros: Most secure, no passphrase promptsCons: Platform-specific

Encrypted file storage:

xyz config set keyring-backend file

Keys stored in ~/.xyz/keyring-file/ encrypted with a passphrase.Pros: Portable, works everywhereCons: Requires passphrase for each operation

Plain text storage (development only):

xyz config set keyring-backend test

Never use for real funds. Keys are stored unencrypted.

Pros: No password prompts (great for scripts)Cons: Zero security

CW20 Token Configuration

Track CW20 tokens for balance queries:

Set CW20 Code ID

After deploying the CW20 base contract, save its code ID:

xyz config set cw20-code-id 1

This is used by xyz token create to instantiate new tokens.

Track Token Contracts

Add token contracts to track in balance queries:

# Add a single token
xyz config set cw20-tokens xyz1tokenaddress...

# View tracked tokens
xyz config get cw20-tokens

Then query all balances including CW20 tokens:

xyz balance --all --key mykey

Validation

The CLI validates configuration values:

Key	Validation
`node`	Must start with `http://` or `tcp://`
`keyring-backend`	Must be `os`, `file`, or `test`
`cw20-code-id`	Must be positive integer
`chain-id`	Non-empty string

Invalid values are rejected:

xyz config set keyring-backend invalid
# Error: invalid keyring-backend: must be 'os', 'file', or 'test'

Multiple Profiles

For multiple networks, use separate home directories:

# Testnet profile
xyz --home ~/.xyz-testnet config set node tcp://rpc.testnet.xyz.com:26657
xyz --home ~/.xyz-testnet config set chain-id xyz-testnet-1

# Mainnet profile
xyz --home ~/.xyz-mainnet config set node tcp://rpc.xyz.com:26657
xyz --home ~/.xyz-mainnet config set chain-id xyz-mainnet-1

Use with commands:

xyz --home ~/.xyz-testnet balance mykey
xyz --home ~/.xyz-mainnet balance mykey

Or create shell aliases:

alias xyz-testnet='xyz --home ~/.xyz-testnet'
alias xyz-mainnet='xyz --home ~/.xyz-mainnet'

Reset Configuration

To reset to defaults, delete the config file:

rm ~/.xyz/config.yaml

Or reset specific values:

xyz config set node tcp://localhost:26657

Debugging

View Effective Configuration

xyz config list

Check Environment

env | grep XYZ_

Verbose Mode

For debugging connection issues, check the node status:

curl http://localhost:26657/status | jq '.result.sync_info'

Getting Started

Chain

Products

Developer Tools

Token Operations

Smart Contracts

Local Development

Chain API

Launchpad API

Configuration

Configuration

Configuration Commands

Set a Value

Get a Value

List All Values

Available Configuration Keys

Setting Up for Different Networks

Local Development

Testnet

Production

Configuration File

Environment Variables

Precedence

Keyring Backend

CW20 Token Configuration

Set CW20 Code ID

Track Token Contracts

Validation

Multiple Profiles

Reset Configuration

Debugging

View Effective Configuration

Check Environment

Verbose Mode

​Configuration

​Configuration Commands

​Set a Value

​Get a Value

​List All Values

​Available Configuration Keys

​Setting Up for Different Networks

​Local Development

​Testnet

​Production

​Configuration File

​Environment Variables

​Precedence

​Keyring Backend

​CW20 Token Configuration

​Set CW20 Code ID

​Track Token Contracts

​Validation

​Multiple Profiles

​Reset Configuration

​Debugging

​View Effective Configuration

​Check Environment

​Verbose Mode

Configuration

Configuration Commands

Set a Value

Get a Value

List All Values

Available Configuration Keys

Setting Up for Different Networks

Local Development

Testnet

Production

Configuration File

Environment Variables

Precedence

Keyring Backend

CW20 Token Configuration

Set CW20 Code ID

Track Token Contracts

Validation

Multiple Profiles

Reset Configuration

Debugging

View Effective Configuration

Check Environment

Verbose Mode