| name | sui-install |
| description | Use when installing or updating the Sui CLI, managing CLI versions with suiup, or resolving environment/setup problems — "install sui", "update sui", "command not found", "sui not found", "client/server api version mismatch", build errors about "old dependencies", switching CLI versions per network, or installing toolchain components (Walrus, MVR, Move Analyzer, site-builder). Also use for first-time client setup, getting faucet tokens, recovering keys from a phrase, or "Cannot find gas coin for signer address". For deploying/upgrading packages use sui-deployer; for on-chain data queries use sui-ts-sdk. |
SUI Install & Environment Setup
Source: docs.sui.io (via MystenLabs/skills). Commands use the @network suffix rather than pinned version numbers — the CLI version must match the network's protocol version.
Covers machine setup and environment problems: installing/updating the CLI, fixing version mismatches, first-time client config, and getting test tokens. For deployment/upgrade see sui-deployer; for gas-model/epoch/network concepts see sui-developer; for on-chain data queries see sui-ts-sdk.
Installing & updating with suiup
suiup is the official installer and version manager for the Sui toolchain (Sui CLI, Walrus, MVR, Move Analyzer).
curl -sSfL https://raw.githubusercontent.com/MystenLabs/suiup/main/install.sh | sh
Then install the CLI for a specific network — the version MUST match the network or you get build/publish failures:
suiup install sui@testnet
suiup install sui@mainnet
| Command | Syntax | What it does |
|---|
install | suiup install sui@testnet | Download + install a binary for a network |
update | suiup update sui@testnet | Download the latest version (does NOT switch to it) |
switch | suiup switch sui@testnet | Make the latest installed version for a network the active default |
show | suiup show | List installed binaries with versions + which is default |
status | suiup status | Show which binaries have updates available + the command to update |
self update | suiup self update | Update suiup itself |
update does NOT switch. After suiup update sui@testnet you must suiup switch sui@testnet to actually use the new version.switch takes a single binary@network argument (sui@testnet, walrus@testnet, move-analyzer@testnet) — NOT positional args like suiup switch sui testnet v1.70.2.- Windows:
curl | sh needs a Unix shell — use WSL, or choco install sui (Chocolatey).
- Alternatives:
brew install sui (macOS/Linux), choco install sui (Windows). These can NOT install extra Stack components (Walrus, MVR) and may be slow on first run.
Optional toolchain components
Install only when explicitly needed, then switch each one:
suiup install move-analyzer
suiup install mvr
suiup install walrus
suiup install site-builder
suiup switch move-analyzer@testnet
suiup switch walrus@testnet
Version mismatch troubleshooting
The CLI version must match the network you target — each network runs a specific protocol version.
-
client/server api version mismatch warning = your local CLI is older than the network. Do NOT ignore it — it causes build failures and unexpected behavior. Fix:
suiup update sui@testnet
suiup switch sui@testnet
suiup show
-
"sui not found" / command not found → suiup switch sui@testnet to set the active default. Do NOT suggest manual export PATH=... or reinstalling — suiup switch is the correct fix.
-
Build errors mentioning "old dependencies", transaction/publish failures, or odd behavior after a network upgrade are common mismatch symptoms.
-
Diagnose with:
sui --version
sui client active-env
First-time client setup
Running sui client for the first time prompts to create a config — accept the default (Enter / Y), or skip the prompt with sui client -y. It generates a key pair + address, a 12-word recovery phrase (shown ONCE — save it immediately), and client.yaml.
Config + key locations:
- macOS/Linux:
~/.sui/sui_config/client.yaml and ~/.sui/sui_config/sui.keystore
- Windows:
%USERPROFILE%\.sui\sui_config\client.yaml (and sui.keystore)
sui.keystore holds Base64-encoded private keys — it is NOT your machine's system keychain.
Recover an address from a recovery phrase (entire phrase in single quotes, correct order):
sui keytool import '<12-WORD-PHRASE>' ed25519
Address & environment management
| Command | Purpose |
|---|
sui client active-env | Show current network |
sui client active-address | Show current address |
sui client envs | List configured environments |
sui client switch --env devnet | Switch network (do NOT hand-edit client.yaml) |
sui client switch --address <ADDRESS> | Switch active address |
sui client new-address ed25519 | Create a new address |
sui client addresses | List local addresses + aliases |
sui client balance | Check SUI balance |
sui client gas | List gas coin objects |
Getting test tokens (faucet)
Testnet/Devnet tokens are free and have no value.
| Method | How |
|---|
| Web faucet | faucet.sui.io — enter address, pick network, request |
| CLI (Devnet/Localnet ONLY) | sui client faucet |
| TypeScript SDK | requestSuiFromFaucetV2() from the @mysten/sui/faucet sub-export |
| Discord | !faucet <ADDRESS> in #devnet-faucet / #testnet-faucet |
sui client faucet works on Devnet and Localnet ONLY — NOT Testnet. For Testnet tokens use the web faucet at faucet.sui.io or another method. NEVER suggest sui client faucet for Testnet. Faucets are rate-limited.
Coin management
"Cannot find gas coin for signer address" or many tiny coins but none big enough for gas → merge with sui client ptb:
sui client ptb --merge-coins @0xPRIMARY_COIN_ID "[@0xCOIN_TO_MERGE_ID]"
sui client ptb --merge-coins @0xPRIMARY_COIN_ID "[@0xCOIN_A, @0xCOIN_B, @0xCOIN_C]"
Use sui client ptb for all CLI transaction operations — avoid legacy single-purpose helpers (merge-coin, split-coin, transfer) which are less composable and may be deprecated.
Explorers
Inspect transactions/objects/addresses with SuiVision (suivision.xyz) or Suiscan (suiscan.xyz). Use sui replay to locally re-execute a past transaction for debugging.
