Skip to main content

​
Prerequisites

  • Rust 1.75.0 or later
  • Git
  • 8GB RAM minimum
  • 50GB available disk space

​
Installation Methods

​
Install from Source

The recommended way to install the IOTA CLI is from source:
1

Clone the repository

git clone https://github.com/iotaledger/iota.git
cd iota
2

Build the CLI

cargo build --release --bin iota
The binary will be available at target/release/iota.
3

Add to PATH (optional)

# Linux/macOS
sudo cp target/release/iota /usr/local/bin/

# Or add to PATH in your shell config
export PATH="$PATH:$(pwd)/target/release"
4

Verify installation

iota --version
Expected output:
iota 0.x.x

​
Build with Optional Features

The CLI supports optional features that can be enabled during build: 
# Enable indexer support (requires PostgreSQL)
cargo build --release --bin iota --features indexer

# Enable IOTA Names support
cargo build --release --bin iota --features iota-names

# Enable shell completions generation
cargo build --release --bin iota --features gen-completions

# Enable all features
cargo build --release --bin iota --all-features

​
Initial Configuration

After installation, initialize your configuration:
1

Create initial config

The first time you run most commands, you’ll be prompted to create a configuration:
iota client
This creates:
  • ~/.iota/iota_config/client.yaml
  • ~/.iota/iota_config/iota.keystore
2

Create your first address

Generate a new address:
iota client new-address ed25519
Output:
Created new keypair for address with scheme ED25519
Secret Recovery Phrase: [your 12 word mnemonic]
Save your mnemonic phrase securely. It’s the only way to recover your address.
3

Set active network

Connect to a network:
# Devnet
iota client new-env --alias devnet --rpc https://api.devnet.iota.cafe:443

# Testnet
iota client new-env --alias testnet --rpc https://api.testnet.iota.cafe:443

# Switch environment
iota client switch --env devnet
4

Get test tokens

Request tokens from the faucet:
iota client faucet
Verify your balance:
iota client balance

​
Shell Completions

Generate shell completions for your preferred shell: 
# Bash
iota generate-completions --shell bash > ~/.local/share/bash-completion/completions/iota

# Zsh
iota generate-completions --shell zsh > ~/.zsh/completions/_iota

# Fish
iota generate-completions --shell fish > ~/.config/fish/completions/iota.fish

# PowerShell
iota generate-completions --shell powershell > $PROFILE.CurrentUserAllHosts

​
Configuration Files

The CLI uses these configuration files:

​
client.yaml

Location: ~/.iota/iota_config/client.yaml 
keystore:
  File: /home/user/.iota/iota_config/iota.keystore
envs:
  - alias: devnet
    rpc: "https://api.devnet.iota.cafe:443"
    ws: null
  - alias: localnet  
    rpc: "http://127.0.0.1:9000"
    ws: null
active_env: devnet
active_address: "0x..."

​
iota.keystore

Location: ~/.iota/iota_config/iota.keystore Encrypted storage for private keys. Never share this file.

​
Updating the CLI

To update to the latest version: 
cd iota
git pull
cargo build --release --bin iota

​
Troubleshooting

​
Build Errors

If you encounter build errors: 
# Update Rust
rustup update stable

# Clean build cache
cargo clean
cargo build --release --bin iota

​
Configuration Issues

Reset your configuration: 
# Backup existing config
mv ~/.iota/iota_config ~/.iota/iota_config.backup

# Run CLI to create fresh config
iota client

​
Connection Issues

Verify network connectivity: 
curl -X POST https://api.devnet.iota.cafe:443 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"iota_getChainIdentifier","id":1}'

​
Next Steps

Client Commands

Start interacting with the IOTA network

Move Commands

Build your first Move package

Build docs developers (and LLMs) love

Get started for freeTalk to us