Dubhe CLI for Sui

Install the CLI (and shared config types) as dev dependencies in your project:

pnpm install -D @0xobelisk/sui-cli @0xobelisk/sui-common

@0xobelisk/sui-common provides the defineConfig helper and TypeScript types for dubhe.config.ts.

Why use the Dubhe CLI instead of `sui` directly?

The Dubhe CLI is not just a thin wrapper around sui move. It performs framework-level steps that the raw Sui CLI has no knowledge of:

Command	What the Dubhe CLI does in addition to the Sui CLI equivalent
`dubhe publish`	After publishing, automatically calls `genesis::run` to create the `DappStorage` object and run `deploy_hook`. Records `packageId`, `dappStorageId`, and `dappHubId` to `.history/sui_<network>/latest.json`.
`dubhe upgrade`	After upgrading, automatically calls the generated `migrate_to_vN` entry function, which registers the new package address and bumped version in `DappStorage` via `dapp_system::upgrade_dapp`.
`dubhe test`	Sets `--path` correctly from `dubhe.config.ts` and adds `--build-env testnet` when needed so framework dependencies resolve regardless of your active Sui client environment.
`dubhe build`	Resolves the correct package path from `dubhe.config.ts` so you don’t have to `cd` into the contracts directory.

If you use sui client publish directly, genesis::run is never called — DappStorage is never created and your DApp cannot function.

If you use sui client upgrade directly, migrate_to_vN is never called — DappStorage still records the old version, and ensure_latest_version will abort every entry function call in the new package.

Always use the Dubhe CLI for these operations.

Command overview

generate: Generate Move code automatically from your dubhe.config.ts
publish: Deploy your Dubhe projects to any Sui network (mainnet/testnet/devnet/localnet)
upgrade: Upgrade your Dubhe Move contracts
node: Manage local Sui node for development
faucet: Interface with Sui faucets to fund addresses on testnet/devnet/localnet
generate-key: Generate a new account key pair and save it to a .env file
check-balance: Check the balance of the account
store-config: Store configuration for the Dubhe project
build: Build Dubhe Move contracts
test: Run tests for Dubhe contracts
doctor: Check development environment and install required tools
wait: Wait for services to be ready
watch: Watch configuration file for changes
switch-env: Switch between different network environments
convert-json: Convert Dubhe config to JSON format
load-metadata: Load package metadata
info: Display account and network information
hello: Print the Dubhe banner
shell: Open an interactive Dubhe shell

Installation

The CLI should be installed as a project dependency rather than globally. When you create a new project using pnpm create dubhe, the CLI is automatically added as a dev dependency.

Using the CLI

Some commands expect a dubhe config in the same folder where the CLI is being executed. This includes generate and publish.

faucet and node can be executed anywhere.

Common options. Network-facing commands (publish, upgrade, build, faucet, check-balance, info, load-metadata, switch-env, shell, generate) accept --rpc-url <URL> to override the RPC fullnode endpoint for that single invocation (useful for private/custom nodes). The default value of --network is the literal default, which resolves to your active Sui CLI environment at runtime (faucet and switch-env default to localnet instead).

Commands

`generate`

Generate Move code from a dubhe.config.ts file. See the resources config and generate documentation for more details.

schemagen: alias for dubhe generate (same behavior).

dubhe generate [--config-path <path>] [--network <network>] [--mode <mode>]
 
Options:
  --config-path    Path to config file (default: "dubhe.config.ts")
  --network        Target network (mainnet/testnet/devnet/localnet/default)
  --mode           Settlement mode baked into generated code:
                   "user_pays" (default) | "dapp_subsidizes"

--mode controls who pays for storage writes in the generated code: user_pays settles from the user, dapp_subsidizes settles from the DApp credit pool.

`publish`

Deploy Dubhe contracts to Sui network. This tool uses dubhe.config.ts to detect all systems and declared resources, then deploys them to the specified network.

Before you deploy, ensure that:

You have sufficient tokens in your account for deployment fees
For testnet/devnet/localnet deployments, you can get test tokens via dubhe faucet
For localnet deployments, ensure your local node is running

dubhe publish [--network <network>] [--config-path <path>] [--gas-budget <number>] [--force]
 
Options:
  --network        Target network (mainnet/testnet/devnet/localnet) (default: active Sui env)
  --config-path    Path to config file (default: "dubhe.config.ts")
  --gas-budget     Optional gas budget for transaction
  --force          Force republish even if already deployed (default: false)

`upgrade`

Upgrade deployed Dubhe contracts.

dubhe upgrade [--network <network>] [--config-path <path>] [--bump-version]
 
Options:
  --network        Target network (mainnet/testnet/devnet/localnet) (default: active Sui env)
  --config-path    Path to config file (default: "dubhe.config.ts")
  --bump-version   Increment ON_CHAIN_VERSION in migrate.move (default: false)

Use --bump-version when you need to force all callers off an old package — for example, after fixing a security bug. This increments ON_CHAIN_VERSION so that ensure_latest_version permanently rejects calls from any previous package version.

Without --bump-version, the upgrade is compatible: old clients can still call the contract and existing UserStorage data is untouched.

`node`

Manage local Sui node using the official sui binary.

dubhe node [--data-dir <path>] [--force]
 
Options:
  --data-dir    Path to the data directory (default: ".chk")
  --force       Force restart: stop existing node and remove data directory (default: false)

Local RPC endpoint: http://127.0.0.1:9000

Note: Make sure your local node is running properly before using other commands that require a local node (e.g., dubhe publish --network localnet).

`faucet`

Request test tokens from the Sui faucet. The default faucet service automatically gives test tokens to accounts in .env.

dubhe faucet [--network <network>] [-r <address>] [--recipient <address>]
 
Options:
  --network        Network to request tokens on (testnet/devnet/localnet) (default: localnet)
  -r, --recipient  Optional recipient address (uses PRIVATE_KEY env if not specified)

`generate-key`

Generate new account keypair.

dubhe generate-key [--force] [--use-next-public]
 
Options:
  --force           Force generate new keypair (default: false)
  --use-next-public Use NEXT_PUBLIC_ prefix for client-side usage (default: false)

`check-balance`

Check account balance on specified network.

dubhe check-balance [--network <network>]
 
Options:
  --network    Network to check balance on (mainnet/testnet/devnet/localnet) (default: active Sui env)

`store-config`

Store configuration for the Dubhe project.

dubhe store-config [--output-ts-path <path>] [--network <network>] [--config-path <path>]
 
Options:
  --output-ts-path   Output path for the generated TypeScript file (default: "./deployment.ts")
  --network          Network to store config for (mainnet/testnet/devnet/localnet) (default: active Sui env)
  --config-path      Path to config file (default: "dubhe.config.ts")

`build`

Build your Dubhe Move contracts.

dubhe build [--network <network>] [--config-path <path>] [--dump-bytecode-as-base64]
 
Options:
  --network                Target network (mainnet/testnet/devnet/localnet) (default: active Sui env)
  --config-path           Path to config file (default: "dubhe.config.ts")
  --dump-bytecode-as-base64  Output bytecode as base64

`test`

Run Move unit tests for the package at src/<projectName>/ (from dubhe.config.ts). This wraps sui move test with the correct --path and, when needed, --build-env testnet so dependencies resolve even if your active Sui client environment is localnet or devnet.

dubhe test [filter] [--config-path <path>] [--gas-limit <limit>] [--list]
 
dubhe test [--config-path <path>] [--test <filter>] [--gas-limit <limit>] [--list]

Arguments / options:

Argument / option	Description
`[filter]`	Optional positional substring filter. A test runs only if its fully qualified name (`<address>::<module>::<function>`) contains this string. Same behavior as `sui move test [filter]` (see `sui move test --help`).
`--test <filter>`	Same as the positional `[filter]` (kept for backward compatibility). If both are set, the positional wins.
`--config-path`	Path to config file (default: `dubhe.config.ts`)
`--gas-limit`	Per-test gas bound passed to `sui move test` (default: `100000000`)
`--list`	List test names (`sui move test -l`) instead of executing them

Examples:

# Run all tests in the package
dubhe test
 
# Run only tests whose FQN contains this substring (e.g. one module or one function name)
dubhe test mygame::level_test::test_set_and_get_level
dubhe test test_set_and_get_level
 
# Equivalent to the above
dubhe test --test test_set_and_get_level
 
# List all tests
dubhe test --list

Note: On the sui move test CLI, the flag --test means something different (compile including the tests/ tree). Dubhe forwards your filter as Sui’s positional filter, not as that flag.

`doctor`

Check development environment and install required tools.

dubhe doctor [--install <tool>] [--list-versions <tool>] [--select-version] [--debug]
 
Options:
  --install <tool>       Install a specific tool: "sui" or "dubhe-indexer"
  --list-versions <tool> List available versions of "sui" or "dubhe-indexer"
  --select-version       Interactively select a version to install (default: false)
  --debug                Show verbose debug output (default: false)

The doctor command checks for:

Node.js version compatibility
Docker service availability
Required development tools (sui, dubhe-indexer, postgres, etc.)
Port availability for local services
Network connectivity

`wait`

Wait for service(s) to be ready before proceeding.

dubhe wait [--url <url>] [--localnet] [--local-node] [--local-database] [--local-indexer] [--timeout <ms>] [--interval <ms>]
 
Options:
  --url              URL to wait for (single service)
  --localnet         Wait for all dubhe localnet services (default: false)
  --local-node       Wait for the local Sui node only (default: false)
  --local-database   Wait for the local PostgreSQL database only (default: false)
  --local-indexer    Wait for the local dubhe-indexer only (default: false)
  --timeout          Timeout in milliseconds (default: 86400000 — 24 hours)
  --interval         Check interval in milliseconds (default: 1000)

Examples:

Wait for a specific service:

dubhe wait --url http://localhost:4000

Wait for all localnet services:

dubhe wait --localnet

`watch`

Watch configuration file for changes and automatically run generate.

dubhe watch

This command monitors dubhe.config.ts for changes and automatically runs dubhe generate when the file is modified.

`switch-env`

Switch between different network environments.

dubhe switch-env --network <network>
 
Options:
  --network    Target network (mainnet/testnet/devnet/localnet) (default: localnet)

`convert-json`

Convert Dubhe configuration to JSON format.

dubhe convert-json [--config-path <path>] [--output-path <path>]
 
Options:
  --config-path    Path to config file (default: "dubhe.config.ts")
  --output-path    Output path for JSON file (default: "dubhe.config.json")

`load-metadata`

Load package metadata for a deployed contract.

dubhe load-metadata [--network <network>] [--config-path <path>] [--package-id <id>]
 
Options:
  --network        Network to use (mainnet/testnet/devnet/localnet) (default: active Sui env)
  --config-path    Path to config file (default: "dubhe.config.ts")
  --package-id     Package ID to load metadata for (optional)

`info`

Display account and network information.

dubhe info [--network <network>]
 
Options:
  --network    Network to check (mainnet/testnet/devnet/localnet) (default: active Sui env)

This command shows:

Current network
Account address
Account balance

`hello`

Print the Dubhe banner.

dubhe hello

`shell`

Open an interactive Dubhe shell session.

dubhe shell [--network <network>]
 
Options:
  --network    Network to connect to (default: active Sui env)

Environment Setup

Some commands require environment variables to be set:

PRIVATE_KEY: Required for deployment and some other operations
Can be set up using a .env file in your project root

When using the deployer, you must set the private key of the deployer using the PRIVATE_KEY environment variable. You can make this easier by using dotenv before running commands.

Network Support

The CLI supports the following networks:

Mainnet
Testnet
Devnet
Localnet

For testnet/devnet/localnet operations, you can get test tokens using the faucet command.

Project setup Contracts

Dubhe CLI for Sui

Why use the Dubhe CLI instead of sui directly?

Command overview

Installation

Using the CLI

Commands

generate

publish

upgrade

node

faucet

generate-key

check-balance

store-config

build

test

doctor

wait

watch

switch-env

convert-json

load-metadata

info

hello

shell