Tools

Choose by live, offline, workload, migration, or diagnostic target and confirm scope first.

One wkcli; choose its command family by target. Start with bounded read-only checks, then follow an explicit change procedure.

Confirm the target boundary first

Every deployment is a cluster, including a single-node cluster. The physical hash-slot count is 256, and the generated default configuration uses 12 logical Slot Raft Groups. A node-local snapshot, database directory, or Top result does not automatically represent the cluster.

Choose a tool

Inspect live clusters

wkcli: Top and node evidence; mutations need a controlled procedure.

Inspect offline data

wkcli db: one-node queries and transfer; import writes the target.

Validate workloads

wkcli bench: real traffic in an isolated cluster.

Migrate original v2

wkcli migrate: cold backups into new offline v3 directories.

Bounded diagnostics

Correlate logs, metrics, Top, and bounded pprof.

Check a symptom

Choose the first check from the current symptom.

Output is evidence. Manager approval, permissions, and cluster safety gates still apply.

Complete tool comparison and boundaries

WuKongIM provides one operator binary, wkcli, with command families for each target: wkcli uses live cluster APIs, wkcli db reads one node's offline data, wkcli bench generates real traffic in an isolated target, and diagnostic surfaces answer one bounded question. Tool output is evidence, not permission to bypass Manager approval or cluster safety gates.

Objective	Use	Read or write	Not for
Inspect live nodes, Top, or dynamic-node state	wkcli	Most inspection is read-only; node-lifecycle subcommands call controlled Manager write APIs	Direct Controller/Slot editing or process management
Query, export, or compare node-local storage	wkcli db	Offline and read-mostly; only `import` writes the target store	Online cluster queries, global snapshots, or automatic migration
Validate protocol traffic, a capacity hypothesis, or a regression gate	wkcli bench	Generates real connections, channels, users, and messages	Unbounded production load or universal capacity numbers
Migrate stopped original v2 backups to a new v3 cluster	wkcli migrate	Reads cold backups and writes new offline target directories	In-place upgrades or online incremental replication
Correlate logs, metrics, Top, diagnostics, and pprof	Diagnostics	Read-only by default; pprof is a bounded active observation	Automatic repair, arbitrary commands, or arbitrary queries

Common workflow

Bound targets, concurrency, duration, rows, and artifact directories; define stop conditions first. Keep commands, time, exit codes, and redacted output. Manager, Benchmark, Debug, and Operations MCP need separate authorization.

Complete six-step workflow

Confirm identity: record repository version, binary digest, cluster ID, node ID, and target addresses.
Choose the minimum surface: begin read-only, low-cost, and short-lived; do not start with profiling or load generation.
Isolate permission: use least-privilege credentials and controlled networks. Manager, Benchmark, Debug, and Operations MCP have separate trust boundaries.
Set budgets: bound target, concurrency, duration, returned rows, and artifact directory; write down a stop condition.
Retain context: keep the command, time range, exit code, and redacted output, not only the final summary.
Remove temporary capability: disable Debug, Benchmark, temporary credentials, simulators, and extra sampling, then confirm resources return to baseline.

Obtain wkcli

Since v3.0.0-beta.12, official archives and Linux native packages include matching wkcli. Install and verify versions, then choose a command family.

Complete distribution and version history

Since v3.0.0-beta.12, the official archives and Linux native packages include wkcli alongside the server. Start with installation and version checks. All examples use this one executable; you do not need separate benchmark, database, or migration binaries.

Build from source

Build only a reviewed revision. Record tool and target versions; do not use development-branch tools directly in production or assume unknown versions are compatible. Expand for build commands.

Complete source build and compatibility boundaries

Build the required binary from a reviewed repository revision:

go build -o ./bin/wkcli ./cmd/wkcli
./bin/wkcli --help

For source development, replace wkcli in examples with ./bin/wkcli or go run ./cmd/wkcli from the repository root. The latter requires the Go version in go.mod.

Record a traceable version for both tool and target server. Do not use a development-branch tool against production or assume offline formats, Manager APIs, or benchmark protocols are compatible across unknown versions.

Handling failure

Stop if identity, authentication, connectivity, or freshness is unclear; do not retry with broader permission. Read authoritative task state after failed writes. Retain conflicting evidence; stop loads, profiles, and scans at their budget.

Complete failure handling and troubleshooting paths

Stop when authentication, connectivity, state freshness, or target identity cannot be proven; do not keep trying with broader credentials.
When read-only outputs disagree, retain both and check their time, node, version, and source.
After a write command fails, read authoritative task state before retrying; the previous request may already have taken effect.
Stop a load, profile, or scan when its budget is reached even if it has not produced the expected conclusion.

Use Troubleshooting to choose the first check from a symptom.