Skip to main content
skill CX Codex

sui-client — Claude Code skill: what it does, how to install

sui-client — a skill for Claude Code and Codex that handles Sui CLI setup, address management, and faucet tokens. Triggers on network switches, coin merges, or gas coin errors.

Apache-2.0 403 installs ★ 25 updated 2026-11-12

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add MystenLabs/skills --skill sui-client -a claude-code
Open on GitHub

What sui-client does

The skill manages Sui CLI configuration, key pairs, and network connections. It provides steps for initial client setup via sui client -y, lists environments, switches active addresses, and imports accounts from 12-word seed phrases using sui keytool. Settings reside in client.yaml, while Base64 private keys are written to sui.keystore.

When gas is required, the skill guides token acquisition across different networks. The CLI command sui client faucet operates strictly on Devnet and Localnet, requiring faucet.sui.io or Discord channels for Testnet tokens. To fix "Cannot find gas coin for signer address" errors, it outputs sui client ptb --merge-coins commands instead of deprecated legacy helpers.

Whenever available in the host environment, the skill queries the Sui documentation MCP server at https://sui.mcp.kapa.ai to verify CLI flags.

What it helps with

  • initialize Sui CLI and generate client.yaml
  • switch between Testnet, Devnet, and local networks
  • request test gas tokens from web or CLI faucets
  • merge fragmented SUI coin objects using programmable transaction blocks
  • restore wallet addresses from a 12-word recovery phrase

Example prompts for the agent

  • How do I request testnet tokens for my Sui address?
  • Merge multiple gas coin objects using sui client ptb
  • Switch the active Sui environment to devnet

How to install sui-client

1Skills CLI (Vercel)

npx skills add MystenLabs/skills --skill sui-client -a claude-code

2Manually: put the files in place

~/.claude/skills/sui-client/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/sui-client/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about sui-client

How to install sui-client in Claude Code?

Run npx skills add MystenLabs/skills --skill sui-client -a claude-code.

What does sui-client do?

It provides commands and reference rules for Sui CLI configuration, address switching, faucet token requests, and coin merging.

Why does sui client faucet fail on Testnet?

The CLI faucet command only functions on Devnet and Localnet. Testnet tokens must be requested through faucet.sui.io or Discord.

Source text

SKILL.md · Apache-2.0
---
name: sui-client
description: >
  Sui CLI client configuration, address management, and token acquisition. Use this
  skill when the user needs to configure the Sui client for the first time, manage
  environments or addresses, switch networks, get faucet tokens, check balances,
  recover keys from a recovery phrase, merge coin objects, or look up transactions
  on explorers. Also use when the user sees "Cannot find gas coin for signer
  address" errors or asks about sui client commands, client.yaml, sui.keystore,
  SuiVision, or Suiscan.
---

# Client Configuration & Tokens

> **MCP tool:** When available in your environment, also query the Sui documentation MCP server (`https://sui.mcp.kapa.ai`) for up-to-date answers. Use it for verification and for details not covered by these reference files.

> **Source constraint:** All information sourced exclusively from [docs.sui.io](https://docs.sui.io).

## Configuring the Sui client

### First-time setup

Running `sui client` for the first time prompts you to create a configuration file. Accept the default (press Enter or type `Y`). You can skip the prompt with `sui client -y`.

This generates:

- A new key pair and address
- A 12-word recovery phrase (displayed once, never stored — save it immediately)
- A `client.yaml` configuration file

### Configuration file

Sui stores its configuration at:

- **macOS/Linux:** `~/.sui/sui_config/client.yaml`
- **Windows:** `%USERPROFILE%\.sui\sui_config\client.yaml`

The file contains:

- Network environment connections (Mainnet, Testnet, Devnet, Localnet)
- The active environment (default: Testnet)
- The active address
- The keystore file path

### Managing environments and addresses

| Command | Purpose |
|---|---|
| `sui client active-env` | Show the current network |
| `sui client active-address` | Show the current address |
| `sui client envs` | List all configured environments |
| `sui client switch --env devnet` | Switch to a different network |
| `sui client switch --address <ADDRESS>` | Switch to a different address |
| `sui client new-address ed25519` | Create a new address |
| `sui client addresses` | List all local addresses with aliases |
| `sui client balance` | Check SUI token balance |
| `sui client gas` | List gas coin objects |

### Key storage

Private keys are stored in a separate file:

- **macOS/Linux:** `~/.sui/sui_config/sui.keystore`
- **Windows:** `%USERPROFILE%\.sui\sui_config\sui.keystore`

This file contains Base64-encoded private keys. It is not the same as your machine's system keystore.

### Recovery

To recover an address from a recovery phrase:

```bash
sui keytool import '<12-WORD-PHRASE>' ed25519
```

The entire phrase must be in single quotes and in the correct order.

## Getting SUI tokens

Development on Testnet and Devnet requires SUI tokens for gas. Tokens on these networks are free and hold no monetary value.

### Faucet methods

| Method | How |
|---|---|
| Web faucet | Visit `faucet.sui.io`, enter your address, select network, click Request SUI |
| CLI (Devnet/Localnet only) | `sui client faucet` — works on Devnet and Localnet only, **not Testnet** |
| TypeScript SDK | `requestSuiFromFaucetV2()` from `@mysten/sui/faucet` |
| Discord | Join the Sui Discord, use `!faucet <ADDRESS>` in `#devnet-faucet` or `#testnet-faucet` |
| Community faucets | N1Stake faucet, SuiLearn faucet (separate rate limits) |

**IMPORTANT: `sui client faucet` only works on Devnet and Localnet. It does NOT work on Testnet. For Testnet tokens, use the web faucet at `faucet.sui.io` or another method above. NEVER suggest `sui client faucet` for Testnet.**

Faucets are rate-limited. If you hit a limit, wait or try a different faucet.

### Coin management

If you have many small SUI coin objects but no single coin large enough for gas, merge them using `sui client ptb`:

```bash
# Merge one coin into another
sui client ptb \
  --merge-coins @0xPRIMARY_COIN_ID "[@0xCOIN_TO_MERGE_ID]"

# Merge multiple coins at once
sui client ptb \
  --merge-coins @0xPRIMARY_COIN_ID "[@0xCOIN_A, @0xCOIN_B, @0xCOIN_C]"
```

Use `sui client ptb` for all transaction operations from the CLI. Avoid legacy helpers like `sui client merge-coin` — they are less composable and may be deprecated. See the `ptbs` skill's `cli.md` for more patterns.

### Verify balance

```bash
sui client balance
```

Or use explorers: SuiVision (`suivision.xyz`) or Suiscan (`suiscan.xyz`).

## Explorers and data tools

Use SuiVision (`suivision.xyz`) or Suiscan (`suiscan.xyz`) to inspect transactions, objects, addresses, and token balances. Sui provides a GraphQL RPC for rich data queries per network. Use `sui replay` (CLI built-in) to locally re-execute past transactions for debugging.

## Rules

- Submit writes and reads to the same fullnode for consistency.
- Let wallets manage gas budget, gas price, and coin selection. Do not hardcode gas budgets in frontends.
- Use `sui client ptb` for all CLI transaction operations instead of legacy single-purpose commands (`merge-coin`, `split-coin`, `transfer`, etc.).

© MystenLabs · Apache-2.0 · MystenLabs/skills

Similar skills

All skills for Backend and APIs →

From the same set30

The whole set →
ptbs ptbs — a skill for Claude Code helps write, review, and debug Sui Programmable Transaction Blocks. It applies to TypeScript SDK and CLI transactions, gas handling, and sponsored flows. CX Codex +1 491installs sui-sdks sui-sdks — a Claude Code skill for navigating the Sui blockchain SDK ecosystem and wiring up projects. It triggers when starting a Sui project, porting code, or comparing SDK APIs. CX Codex +1 487installs frontend-apps The frontend-apps Claude Code skill guides frontend work on Sui browser apps. It covers wallet connections, on-chain queries, and transaction flows. CX Codex +1 479installs walrus-sites walrus-sites — a Claude Code skill for deploying, updating, and serving decentralized websites on Walrus and Sui. Helps set up a local portal for testnet and configure routing in ws-resources.json. CX Codex +1 467installs sui-overview The sui-overview Claude Code skill explains Sui’s design and ecosystem. It activates for blockchain comparisons, Sui architecture planning, and questions about moving from Ethereum or Solana. CX Codex +1 400installs sui-publish sui-publish — a skill for Claude Code deploys, tests, and upgrades Sui Move smart contract packages. Triggers on requests to publish packages, manage UpgradeCap, or troubleshoot dry run deployment failures. CX Codex +1 399installs generate-sui-agent-config generate-sui-agent-config — a skill for Claude Code and Codex generates CLAUDE.md or AGENT.md config files in Sui projects. Triggers when starting a new repo or when agent instructions are missing. CX Codex +1 391installs move-security The move-security Claude Code skill reviews security in Sui Move contracts. It activates for package audits, access-control design, and checks involving keys or randomness. CX Codex +1 381installs

Project sponsors

Companies that keep this analytics open