Configuration

Configure the xyz CLI

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

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

Keyring Backend

The keyring backend determines how private keys are stored:

OS (Recommended)

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 prompts

Cons: Platform-specific

File

Encrypted file storage:

xyz config set keyring-backend file

Keys stored in ~/.xyz/keyring-file/ encrypted with a passphrase.

Pros: Portable, works everywhere

Cons: Requires passphrase for each operation

Test

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'