Skip to main content

CLI Reference

The sukko CLI manages your Sukko deployment — tenants, keys, testing, and local development.

Install​

# macOS / Linux
brew install sukko-dev/tap/sukko

# Windows
scoop bucket add sukko https://github.com/sukko-dev/scoop-bucket
scoop install sukko

Commands​

sukko api-keys​

Manage API keys for tenant authentication


sukko api-keys create​

Create a new API key

Flags:

FlagTypeDefaultDescription
--namestring—API key name (optional)
--tenantstring—Tenant ID (uses active tenant from context if not set)

sukko api-keys list​

List API keys for a tenant

Flags:

FlagTypeDefaultDescription
--tenantstring—Tenant ID (uses active tenant from context if not set)

sukko api-keys revoke​

Revoke an API key

Flags:

FlagTypeDefaultDescription
--key-idstring—API key ID (required)
--tenantstring—Tenant ID (uses active tenant from context if not set)

sukko auth​

Manage admin authentication keypairs

Generate, register, revoke, and list admin Ed25519 keypairs for JWT-based authentication.

sukko auth keygen​

Generate an Ed25519 admin keypair

Generates a new Ed25519 keypair and saves it to the active context directory.

sukko auth list​

List active admin keys


sukko auth pubkey​

Print the active context's admin public key

Prints the base64 Ed25519 admin public key for the active context.

This is the value the provisioning service must be booted with — ADMIN_BOOTSTRAP_KEY in Docker Compose, provisioning.adminBootstrapKey in Helm. `auth keygen` prints it once at creation and refuses to re-run, so use this to recover it later. The key is printed bare (no labels) so it can be piped:

ADMIN_BOOTSTRAP_KEY="$(sukko auth pubkey)"

sukko auth register​

Register your public key with provisioning

Sends your public key to the provisioning API to enable JWT-based admin authentication.

Flags:

FlagTypeDefaultDescription
--namestring—Admin name (defaults to context name)

sukko auth revoke <key-id>​

Revoke an admin key


sukko completion [bash|zsh|fish]​

Generate shell completion scripts

Generate shell completion scripts for sukko.

To load completions:

Bash:
$ source <(sukko completion bash)
# To load for each session, add to ~/.bashrc:
$ echo 'source <(sukko completion bash)' >> ~/.bashrc

Zsh:
$ source <(sukko completion zsh)
# To load for each session, add to ~/.zshrc:
$ echo 'source <(sukko completion zsh)' >> ~/.zshrc

Fish:
$ sukko completion fish | source
# To load for each session:
$ sukko completion fish > ~/.config/fish/completions/sukko.fish

sukko config​

Configuration management


sukko config defaults​

Show all configuration environment variables with defaults

Outputs all environment variables from Go config struct tags (the single source of truth).

Flags:

FlagTypeDefaultDescription
--formatstringtableOutput format (table

sukko config view​

Fetch active configuration from a running service


sukko connections​

Connection management and testing


sukko connections test​

Test WebSocket connectivity to the gateway (CLI-only, no tester needed)

Test WebSocket connectivity by opening a single connection directly from the CLI.

Verifies: WebSocket upgrade (101), subscribe, and basic message flow.
For full deployment validation (Kafka pipeline, multi-tenant isolation),
use 'sukko test smoke' which orchestrates the tester service.

Flags:

FlagTypeDefaultDescription
--api-keystring—API key for authentication
--gateway-urlstring—Gateway URL (overrides context)
--timeoutduration10sConnection timeout
--tokenstring—JWT token for authentication

sukko context​

Manage CLI contexts (environments)

Add, remove, switch, and list named contexts for different Sukko environments.

sukko context add <name>​

Add a new context

Flags:

FlagTypeDefaultDescription
--admin-tokenstring—Admin authentication token
--api-keystring—API key for gateway access
--gateway-urlstring—WebSocket gateway URL (e.g., ws://localhost:3000)
--provisioning-urlstring—Provisioning API URL (e.g., http://localhost:8080)
--tenantstring—Default active tenant ID
--tester-urlstring—Tester service URL (e.g., http://localhost:8090)

sukko context create [name]​

Create a context interactively

Create a named context for a Sukko environment. Prompts for required
fields (name, provisioning URL, gateway URL, admin token) and optional fields.
Secrets are entered with masked input to avoid shell history exposure.

All fields can also be provided as flags for non-interactive/CI use.

Flags:

FlagTypeDefaultDescription
--admin-tokenstring—Admin authentication token
--api-keystring—API key for gateway access
--environmentstring—Environment name (e.g., staging, production)
--forceboolfalseOverwrite existing context without confirmation
--gateway-urlstring—WebSocket gateway URL (e.g., wss://ws.example.com)
--provisioning-urlstring—Provisioning API URL (e.g., https://api.example.com)
--tenantstring—Default active tenant ID
--tester-urlstring—Tester service URL

sukko context current​

Show the active context


sukko context list​

List all contexts

Aliases: ls


sukko context remove <name>​

Remove a context

Aliases: rm


sukko context use <name>​

Set the active context


sukko down​

Stop the local development environment

Stop and remove local Docker Compose services. Use -v to also remove volumes.

Flags:

FlagTypeDefaultDescription
--volumes, -vboolfalseRemove volumes (full reset)

sukko edition​

Show current edition, limits, and usage

Show the current Sukko edition (Community/Pro/Enterprise), license status,
hard limits, and live resource usage.

Fetches data from provisioning's /edition endpoint (tenant usage) and
gateway's /edition endpoint (connection/shard usage), merging both.
Falls back to locally stored license key if the platform is unreachable.

sukko edition compare​

Compare Community, Pro, and Enterprise editions

Display a comparison table of all three Sukko editions.

This command works offline — the comparison data is hardcoded from the
published edition matrix. No running services required.

sukko grafana​

Open Grafana in the browser

Open the Grafana dashboard in the system browser. Requires observability to be enabled.

sukko health​

Check health of all Sukko components

Check health of all Sukko components.

Probes gateway, server, provisioning, and their dependencies. Reports
per-component status with troubleshooting suggestions on failure.

sukko init​

Initialize a local Sukko development environment

Initialize a local Sukko development environment.

Creates .sukko/config.json with infrastructure selections and sets up
a local context with dev credentials. Run 'sukko up' to start services.

Flags:

FlagTypeDefaultDescription
--defaultsboolfalseSkip prompts and use defaults (postgres + valkey + direct)

sukko keys​

Manage JWT signing keys


sukko keys create​

Register a new public key or generate a key pair

Flags:

FlagTypeDefaultDescription
--algorithmstring—Signing algorithm: ES256, RS256, EdDSA
--expires-atstring—Expiration time (RFC3339)
--generateboolfalseGenerate ES256 key pair, register public key, save private key locally
--key-idstring—Key ID (optional, auto-generated if not set)
--public-key-filestring—Path to PEM public key file
--tenantstring—Tenant ID (uses active tenant from context if not set)

sukko keys list​

List keys for a tenant

Flags:

FlagTypeDefaultDescription
--tenantstring—Tenant ID (uses active tenant from context if not set)

sukko keys revoke​

Revoke a key

Flags:

FlagTypeDefaultDescription
--key-idstring—Key ID (required)
--tenantstring—Tenant ID (uses active tenant from context if not set)

sukko license​

Manage Sukko license key

Store, view, and remove the Sukko license key from the CLI context.

sukko license push [key]​

Push a license key to a running deployment

Push a Sukko license key to a running provisioning service via
POST /api/v1/license. The license is applied immediately without
restarting services.

If no key argument is provided, you will be prompted for input to avoid
the key appearing in shell history.

This command does NOT modify the local context — use 'sukko license set'
to persist the key for future 'sukko up' invocations.

sukko license remove​

Remove the stored license key from the active context


sukko license set [key]​

Store a license key in the active context

Store a Sukko license key in the CLI context. The key is encrypted at rest.

If no key argument is provided, you will be prompted for input to avoid
the key appearing in shell history.

sukko license show​

Display the stored license key and decoded claims


sukko logs [service...]​

View logs from local Docker Compose services

View logs from local Docker Compose services.

Only available for local Docker Compose environments. Specify service names
to filter (e.g., 'sukko logs ws-gateway ws-server').

Flags:

FlagTypeDefaultDescription
--follow, -fboolfalseFollow log output

sukko publish <channel> <message>​

Publish a message to a channel via the gateway

Flags:

FlagTypeDefaultDescription
--api-keystring—API key for authentication
--countint1Number of messages to publish
--gateway-urlstring—Gateway URL (overrides context)
--intervalduration0sInterval between messages (e.g., 100ms, 1s)
--tokenstring—JWT token for authentication

sukko quota​

Manage tenant quotas


sukko quota get​

Get quotas for a tenant

Flags:

FlagTypeDefaultDescription
--tenantstring—Tenant ID (uses active context if not set)

sukko quota update​

Update quotas for a tenant

Flags:

FlagTypeDefaultDescription
--consumer-byte-rateint640Consumer throughput limit (bytes/sec)
--max-connectionsint0Maximum WebSocket connections
--max-partitionsint0Maximum partitions
--max-storage-bytesint640Maximum storage in bytes
--max-topicsint0Maximum topics
--producer-byte-rateint640Producer throughput limit (bytes/sec)
--tenantstring—Tenant ID (uses active context if not set)

sukko rules​

Manage routing and channel rules


sukko rules channels​

Manage channel permission rules


sukko rules channels delete​

Delete channel rules for a tenant

Flags:

FlagTypeDefaultDescription
--tenantstring—Tenant ID (uses active tenant from context if not set)

sukko rules channels get​

Get channel rules for a tenant

Flags:

FlagTypeDefaultDescription
--tenantstring—Tenant ID (uses active tenant from context if not set)

sukko rules channels set​

Set channel rules for a tenant

Flags:

FlagTypeDefaultDescription
--filestring—Path to JSON channel rules file (alternative to --public)
--publicstringSlice[]Public channel patterns (repeatable)
--tenantstring—Tenant ID (uses active tenant from context if not set)

sukko rules routing​

Manage topic routing rules


sukko rules routing add​

Add a single routing rule for a tenant

Flags:

FlagTypeDefaultDescription
--egress-topicsstring—Comma-separated topic suffixes that receive copies but are never delivered (Pro edition; e.g. audit,analytics)
--ingress-topicstring—Topic suffix the platform consumes and delivers for matching channels (e.g. trades)
--patternstring—Channel pattern (e.g. trades.**, **)
--priorityint0Rule priority (lower = higher precedence; must be unique per tenant)
--tenantstring—Tenant ID (uses active tenant from context if not set)

sukko rules routing delete​

Delete routing rules for a tenant

Flags:

FlagTypeDefaultDescription
--tenantstring—Tenant ID (uses active tenant from context if not set)

sukko rules routing get​

Get routing rules for a tenant

Flags:

FlagTypeDefaultDescription
--tenantstring—Tenant ID (uses active tenant from context if not set)

sukko rules routing set​

Set routing rules for a tenant from a JSON file

Flags:

FlagTypeDefaultDescription
--filestring—Path to JSON routing rules file (required)
--tenantstring—Tenant ID (uses active tenant from context if not set)

sukko rules test-access​

Test channel access for a subject

Flags:

FlagTypeDefaultDescription
--channelstring—Channel to test access for
--groupstringSlice[]Groups to test access for
--substring—Subject (user ID) to test access for
--tenantstring—Tenant ID (uses active tenant from context if not set)

sukko status​

Show status of all services

Show a unified view of all Sukko services with health status.

sukko subscribe <channel> [channel...]​

Subscribe to channels and stream messages to stdout

Flags:

FlagTypeDefaultDescription
--api-keystring—API key for authentication
--gateway-urlstring—Gateway URL (overrides context)
--tokenstring—JWT token for authentication

sukko tenant​

Manage tenants


sukko tenant create​

Create a new tenant

Flags:

FlagTypeDefaultDescription
--consumer-typestringsharedConsumer type (shared
--namestring—Display name
--slugstring—Tenant slug — Kafka namespace and URL identifier, e.g. "acme" (required)

sukko tenant delete [tenant-id]​

Delete a tenant (alias for deprovision)


sukko tenant deprovision [tenant-id]​

Initiate tenant deletion (grace period)


sukko tenant get [tenant-id]​

Get tenant details

Get tenant details. If no tenant-id is provided, uses the active tenant from context.

sukko tenant list​

List tenants

Flags:

FlagTypeDefaultDescription
--limitint50Maximum results
--offsetint0Results offset
--statusstring—Filter by status

sukko tenant reactivate [tenant-id]​

Reactivate a suspended tenant


sukko tenant suspend [tenant-id]​

Suspend a tenant


sukko tenant update [tenant-id]​

Update a tenant

Flags:

FlagTypeDefaultDescription
--namestring—New display name

sukko test​

Run tests against the Sukko platform

Run smoke, load, stress, soak, or validation tests via the sukko-tester service.

sukko test load​

Sustained load test with configurable connections

Flags:

FlagTypeDefaultDescription
--connectionsint10Number of WebSocket connections
--durationstring30sTest duration (e.g., 30s, 5m, 1h)
--follow, -fboolfalseStream metrics in real-time
--kafka-brokersstring—Per-run Kafka broker override for the kafka-ingest suite (comma-separated); credentials come from the tester's environment
--kafka-topic-namespacestring—Per-run Kafka topic namespace override for the kafka-ingest suite; MUST match the server-under-test
--publish-rateint10Messages per second
--ramp-rateint5Connections per second during ramp-up
--tenantstring—Tenant ID (uses active tenant from context if not set)
--tester-urlstring—Tester service URL (overrides context)

sukko test smoke​

Quick connectivity and health check

Flags:

FlagTypeDefaultDescription
--follow, -fboolfalseStream metrics in real-time
--kafka-brokersstring—Per-run Kafka broker override for the kafka-ingest suite (comma-separated); credentials come from the tester's environment
--kafka-topic-namespacestring—Per-run Kafka topic namespace override for the kafka-ingest suite; MUST match the server-under-test
--tenantstring—Tenant ID (uses active tenant from context if not set)
--tester-urlstring—Tester service URL (overrides context)

sukko test soak​

Long-running stability test

Flags:

FlagTypeDefaultDescription
--connectionsint10Number of WebSocket connections
--durationstring30sTest duration (e.g., 30s, 5m, 1h)
--follow, -fboolfalseStream metrics in real-time
--kafka-brokersstring—Per-run Kafka broker override for the kafka-ingest suite (comma-separated); credentials come from the tester's environment
--kafka-topic-namespacestring—Per-run Kafka topic namespace override for the kafka-ingest suite; MUST match the server-under-test
--publish-rateint10Messages per second
--ramp-rateint5Connections per second during ramp-up
--suitestring—Load suite to run (e.g. revocation); omit for default
--tenantstring—Tenant ID (uses active tenant from context if not set)
--tester-urlstring—Tester service URL (overrides context)

sukko test stress​

Push to maximum capacity and find limits

Flags:

FlagTypeDefaultDescription
--connectionsint10Number of WebSocket connections
--durationstring30sTest duration (e.g., 30s, 5m, 1h)
--follow, -fboolfalseStream metrics in real-time
--kafka-brokersstring—Per-run Kafka broker override for the kafka-ingest suite (comma-separated); credentials come from the tester's environment
--kafka-topic-namespacestring—Per-run Kafka topic namespace override for the kafka-ingest suite; MUST match the server-under-test
--publish-rateint10Messages per second
--ramp-rateint5Connections per second during ramp-up
--suitestring—Load suite to run (e.g. revocation); omit for default
--tenantstring—Tenant ID (uses active tenant from context if not set)
--tester-urlstring—Tester service URL (overrides context)

sukko test validate​

Run validation suites

Flags:

FlagTypeDefaultDescription
--follow, -fboolfalseStream metrics in real-time
--kafka-brokersstring—Per-run Kafka broker override for the kafka-ingest suite (comma-separated); credentials come from the tester's environment
--kafka-topic-namespacestring—Per-run Kafka topic namespace override for the kafka-ingest suite; MUST match the server-under-test
--suitestringauthValidation suite (fetch available suites from tester via --help)
--tenantstring—Tenant ID (uses active tenant from context if not set)
--tester-urlstring—Tester service URL (overrides context)

sukko token​

JWT token helpers


sukko token generate​

Generate a signed JWT token

Flags:

FlagTypeDefaultDescription
--algorithmstring—Signing algorithm (ES256, RS256, EdDSA)
--groupsstringSlice[]Groups (repeatable)
--key-filestring—Path to PEM private key
--key-idstring—Registered signing-key id, emitted as the JWT kid header (defaults to the --key-file basename, which is how 'keys create' names stored keys)
--rolesstringSlice[]Roles (repeatable)
--scopesstringSlice[]Scopes (repeatable)
--substring—Subject (user ID)
--tenantstring—Tenant ID
--ttlduration1h0m0sToken time-to-live (e.g., 1h, 30m, 24h)

sukko token revoke​

Revoke a token by session (jti) or user (sub)

Flags:

FlagTypeDefaultDescription
--expiresstring—Revocation expiry (duration like 2h or RFC3339 timestamp)
--jtistring—Revoke a specific session by JWT ID
--substring—Revoke all sessions for a user
--tenantstring—Tenant ID
--tokenstring—JWT to revoke (extracts jti and tenant_id)

sukko token validate <token>​

Decode and validate a JWT token

Flags:

FlagTypeDefaultDescription
--key-filestring—Path to PEM public key (for signature verification)

sukko topics​

Manage provisioned topics


sukko topics create​

Create a provisioned topic for a tenant

Flags:

FlagTypeDefaultDescription
--suffixstring—Topic suffix to provision (e.g. analytics); lowercase alphanumeric and hyphens
--tenantstring—Tenant ID (uses active tenant from context if not set)

sukko topics delete​

Delete a provisioned topic for a tenant

Flags:

FlagTypeDefaultDescription
--suffixstring—Topic suffix to delete
--tenantstring—Tenant ID (uses active tenant from context if not set)

sukko topics list​

List provisioned topics for a tenant

Flags:

FlagTypeDefaultDescription
--tenantstring—Tenant ID (uses active tenant from context if not set)

sukko up​

Start the local development environment

Start the local development environment using Docker Compose.

Reads .sukko/config.json (created by 'sukko init'), activates the selected
infrastructure profiles, waits for all services to become healthy, and
provisions a default tenant for immediate use.

Flags:

FlagTypeDefaultDescription
--pullboolfalseAlways pull latest images before starting

sukko version​

Show CLI version information


sukko webhook​

Manage webhook delivery registrations (operator, Pro+)

Manage a tenant's webhook registrations on its behalf.

Webhook management is operator-only: these commands authenticate with your admin
keypair and require a Pro or Enterprise license. Webhooks deliver channel events
to an external HTTPS endpoint, HMAC-signed with the shared secret.

sukko webhook create​

Register a webhook for a tenant

Flags:

FlagTypeDefaultDescription
--channel-patternstring—Channel pattern the webhook fires on (e.g. orders.*)
--max-retriesint0Max delivery retries (0 = provisioning default)
--secretstring—HMAC signing secret (or use --secret-file to avoid argv exposure)
--secret-filestring—Path to a file containing the HMAC signing secret
--tenantstring—Tenant ID (uses active tenant from context if not set)
--urlstring—Destination URL (https required; http allowed only in local/dev)

sukko webhook delete​

Delete a webhook by ID

Flags:

FlagTypeDefaultDescription
--tenantstring—Tenant ID (uses active tenant from context if not set)
--webhook-idstring—Webhook ID (required)

sukko webhook get​

Get a webhook by ID

Flags:

FlagTypeDefaultDescription
--tenantstring—Tenant ID (uses active tenant from context if not set)
--webhook-idstring—Webhook ID (required)

sukko webhook list​

List a tenant's webhooks

Flags:

FlagTypeDefaultDescription
--tenantstring—Tenant ID (uses active tenant from context if not set)

sukko webhook test​

Send a single synchronous test delivery to a webhook

Flags:

FlagTypeDefaultDescription
--tenantstring—Tenant ID (uses active tenant from context if not set)
--webhook-idstring—Webhook ID (required)

sukko webhook update​

Update a webhook (only the flags you set are changed)

Flags:

FlagTypeDefaultDescription
--channel-patternstring—New channel pattern
--max-retriesint0New max delivery retries (1–10)
--secretstring—Rotate the HMAC signing secret (or use --secret-file)
--secret-filestring—Rotate the HMAC signing secret, read from a file (keeps it out of argv)
--statusstring—New status (enabled
--tenantstring—Tenant ID (uses active tenant from context if not set)
--urlstring—New destination URL
--webhook-idstring—Webhook ID (required)