Tools

Choose the correct repository tool for observation, offline storage inspection, workload validation, and bounded diagnostics.

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.

Confirm the target boundary first

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

Choose a tool

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

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, 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 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 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.