wkcli

Verify paired versions, inspect nodes read-only, and expand mutations and load commands as needed.

Install matching binaries, configure target addresses, then retain evidence with one Top snapshot and read-only node commands.

Install and verify

On Linux amd64, use APT / DNF via Linux deployment. Linux arm64 and macOS use the matching release archive with checksum verification. Paired wkcli and wukongim must match version, commit, and build_source. Version checks need no running server.

Complete installation, verification, and version commands

wkcli is WuKongIM's unified operator CLI. Online operations use HTTP and WKProto entry points; db and migrate operate on offline data. Since v3.0.0-beta.12, official Linux/macOS archives and Linux native packages include both wkcli and wukongim from the same release.

On Linux amd64, follow Linux deployment to install the wukongim package through APT or DNF; it also installs wkcli. For Linux arm64 or macOS, download the matching OS and architecture archive from GitHub Releases, verify it against the release checksum file, and extract both binaries. The current documentation release is v3.0.0-beta.24. Add the extracted directory to PATH, or use ./wkcli and ./wukongim there.

wukongim version --output json
wkcli version --output json
wkcli bench --help
wkcli db --help
wkcli migrate --help

For the paired release binaries, version, commit, and build_source must match. These commands need no running server and do not start a benchmark or migration. The examples below assume wkcli is on PATH; see Tools for source builds.

Command boundaries

Online read-only: top, node ls, and node diagnose; context saves only local target addresses.
Controlled writes: node lifecycles retain Manager permissions, audit, and safety gates; they neither edit Controller / Slot directly nor manage server processes.
Other tasks: bench / sim generate real traffic, db import writes offline storage, and migrate creates new offline data.

Old standalone entrypoints are removed. Use wkcli bench, wkcli db, and wkcli migrate; database global flags precede the operation.

Complete commands, risks, and old entrypoint mapping

Command	Purpose	Risk class
`bench`	Distributed workloads, workers, capacity and reports	Generates real traffic
`db`	Offline query, REPL, import, export and diff	Import writes the target store
`migrate`	Original v2-to-v3 migration	Creates new offline v3 data
`context`	Save and select a set of WuKongIM HTTP API addresses	Writes only the local user configuration directory
`top`	Read and aggregate `/top/v1/snapshot` from one or more nodes	Online read-only
`node ls` / `node diagnose`	Read dynamic-node state and bounded root-cause evidence	Manager read-only
`node activate` / `node onboarding` / `node scale-in`	Advance a dynamic-node lifecycle	Controlled Manager writes
`bench send`	Run a lightweight SEND/SENDACK check	Generates real connections and messages
`sim`	Prepare test metadata and sustain real group-message traffic	Controlled simulation environments only

wkcli node neither starts nor stops server processes and never writes Controller or Slot state directly. Manager permissions, audit, and safety gates still apply.

Replace old invocations wkbench …, wkdb …, and wkmigrate … with wkcli bench …, wkcli db …, and wkcli migrate …. Old executable entrypoints are removed. Command arguments, output formats and family-specific exit codes remain unchanged. Database global flags must precede its verb.

Configure named contexts

Configure absolute http:// / https:// API addresses. Repeat --server or comma-separate addresses. Recheck cluster identity and credential scope after selection; a context name does not grant approval.

Complete context configuration commands

wkcli context add dev \
  --server http://127.0.0.1:5001 \
  --server http://127.0.0.1:5002 \
  --description "development cluster" \
  --select

wkcli context ls
wkcli context show
wkcli context current

--server may be repeated or comma-separated, and every address must be an absolute http:// or https:// API URL. A context stores target addresses; selecting a context named production does not grant operational approval. Recheck cluster identity and credential scope before execution.

Use Top

After configuring the context, run:

wkcli top --context dev \
  --once --json

Result: retain the node snapshots and cross-check /readyz, Manager, and Prometheus. Aggregates are not globally consistent snapshots. Top needs no Prometheus and refreshes continuously by default; use --once or --max-refresh to bound scripts.

Complete Top output and refresh options

wkcli top --context dev --once
wkcli top --context dev --once --json
wkcli top --context dev --interval 2s --max-refresh 5
wkcli top --context dev --alerts

Top reads bounded node-local history and does not depend on Prometheus. It refreshes until interrupted by default; use --once or --max-refresh for scripts and incident evidence. Cross-check aggregates with /readyz, Manager, and Prometheus.

Read dynamic-node evidence

Use node ls, node diagnose, and node scale-in status. Keep health freshness, control revision, blocked_reasons, safe_to_remove, drain counters, and task / audit / Slot evidence. Missing data stays unknown.

Complete read-only dynamic-node commands

wkcli node ls --context dev
wkcli node diagnose 4 --context dev
wkcli node diagnose 4 --context dev --json
wkcli node scale-in status 4 --context dev

Retain health freshness, control revision, blocked_reasons, safe_to_remove, gateway drain counters, and bounded task/audit/Slot evidence. Missing data stays unknown; never infer healthy from an empty value.

Node mutations

Run mutations only within Scaling. Joining does not automatically assign Slot replicas or leaders; Controller voter changes require a separate decision. Removal needs authoritative safe_to_remove=true; diagnostic advice cannot replace it.

Complete node mutations and lifecycle gates

wkcli node activate 4 --context dev
wkcli node onboarding start 4 --context dev --max-slot-moves 1
wkcli node scale-in start 4 --context dev
wkcli node scale-in drain 4 --context dev --draining=true
wkcli node scale-in remove 4 --context dev

Run these only inside the explicit Scaling procedure. A dynamically joined node does not automatically receive Slot replicas or leaders, and Controller voter change is a separate explicit decision. Removal must wait for authoritative safe_to_remove=true; a CLI diagnostic recommendation does not replace that gate.

Lightweight send checks

bench send creates real sessions and messages to check WKProto SEND throughput and SENDACK latency. Use dedicated test identities/channels and bound clients, messages, channels, and time. Use wkcli bench for full scenarios.

Complete lightweight send example

wkcli bench send \
  --gateway 127.0.0.1:5100 \
  --clients 8 \
  --msgs 1000 \
  --channels 10 \
  --channel-prefix check-g \
  --channel-type group \
  --size 128B

bench send is a quick WKProto SEND-throughput and SENDACK-latency check, not a replacement for a complete wkcli bench scenario. It creates real sessions and messages. Bound clients, messages, channels, and runtime, and use dedicated test identities and channels.

Long-running simulation

sim prepares metadata through Benchmark APIs and sends real SEND → SENDACK gateway traffic. Use only isolated development / benchmark clusters with explicitly enabled Benchmark API and a reachable advertised gateway.

--rate is per group; total rate grows with group count. Stop at the time limit, disable Benchmark API, and clean generated data according to the plan.

Complete bounded simulation and capacity path

sim prepares group metadata through /bench/v1/*, keeps users online through the real WKProto gateway, and sends SEND -> SENDACK traffic. The target must explicitly enable the Benchmark API and advertise a reachable gateway.

wkcli sim \
  --server http://127.0.0.1:5001 \
  --users 100 \
  --groups 50 \
  --group-members 10 \
  --rate 0.25/s \
  --max-runtime 30s

--rate is per group, so aggregate offered traffic grows with group count. Run only against an isolated development or benchmark cluster, then disable the Benchmark API and remove generated data. Use wkcli bench for full validation, capacity search, and reports.

Stop safely

Stop when identity, Manager permission, or authoritative state is unclear. Read task state after write timeouts before retrying. Stop Top and workloads at their budget. Check for simulators, temporary contexts, Benchmark API, and unfinished node tasks afterward.

Complete stopping checklist

Do not run node mutations when target identity, Manager permission, or authoritative state is unclear.
After a write request times out, read task state before retrying.
Stop Top, send checks, and simulations when their time or traffic budget is reached.
On exit, confirm there is no simulator, temporary context, exposed Benchmark API, or unfinished node task left behind.

Offline database

Queries, export, and controlled import.

Full workload validation

Use isolated clusters and reviewable reports.

wkcli

Offline database

Full workload validation

On this page