Nimbus — Minecraft Cloud System

Full reference for all Nimbus interactive console commands — service management, groups, permissions, plugins, cluster, load balancer, and more.

Nimbus provides an interactive console with tab completion, command history, and ANSI-colored output. Type help or ? to see all available commands.

All console commands are also available remotely via the Remote CLI (nimbus-cli). The CLI connects to the controller's API and provides the same experience — same commands, same tab completion, same formatting.

Service Management

`list`

Show all running services with status, health, port, player count, and uptime.

Syntax: list [group]

Nimbus

nimbus » list
── Services ──────────────────────────────────────
NAME            GROUP       STATE           HP  PORT    PLAYERS  PID     UPTIME
────────────────────────────────────────────────────────────────────────────────────
Proxy-1         Proxy       ● READY          ✓   25565/19132   36       48190   2h 15m
Lobby-1         Lobby       ● READY          ✓   30001   12       48201   2h 15m
Lobby-2         Lobby       ● READY          ✗   30002   8        48215   1h 42m
BedWars-1       BedWars     ● READY          ✓   30003   16       48230   0h 55m
BedWars-2       BedWars     ● STARTING       -   30004   0        48245   0m 01s
5 service(s)

The HP column shows a quick health indicator: ✓ healthy, ✗ unhealthy, or - for services not yet READY.

Filter by group name: list Lobby shows only Lobby instances. When Bedrock support is enabled, proxy services show both TCP and UDP ports (e.g., 25565/19132).

Tab completion: Group names.

`start`

Start a new instance of a server group.

Syntax: start <group>

Nimbus

nimbus » start BedWars
ℹ Starting new instance for group 'BedWars'...
✓ Service 'BedWars-3' starting on port 30005.

Fails if the group has reached its max_instances limit or the server JAR is unavailable.

Tab completion: Group names.

`stop`

Gracefully stop a running service. Sends the Minecraft stop command to the process.

Syntax: stop <service>

Nimbus

nimbus » stop BedWars-2
ℹ Stopping service 'BedWars-2'...
✓ Service 'BedWars-2' stop initiated.

Tab completion: Running service names.

`restart`

Stop a service and start a new instance in its place.

Syntax: restart <service>

Nimbus

nimbus » restart Lobby-1
ℹ Restarting service 'Lobby-1'...
✓ Service restarted as 'Lobby-3' on port 30006.

Tab completion: Running service names.

`migrate`

Move a service between cluster nodes. For sync-enabled services the graceful stop triggers a state push to the controller canonical, then the start on the target node pulls that canonical before launching.

Syntax: migrate <service> <target-node|local>

Nimbus

nimbus » migrate Lobby-1 worker-2
ℹ Migrating 'Lobby-1' from worker-1 → worker-2...
✓ Service 'Lobby-1' now running on node 'worker-2' (port 30000).

target-node must be an agent node name that is currently connected.
Pass local to move a service back to the controller.
For non-sync services, the data on the source node is lost. Migration is only safe for [group.sync] enabled = true or [dedicated.sync] enabled = true.
Same-name slot reuse: the service keeps its name across the migration so canonical state stays keyed to the same name.

Tab completion: Running service names, then connected node names.

`purge`

Force-kill a service process, clean up crashed services, or kill a process by PID. Use this when a service is stuck and stop doesn't work.

Syntax: purge <service|crashed|pid:<pid>>

Nimbus

nimbus » purge crashed
⚠ Purging 2 crashed service(s)...
  Purged 'BedWars-3'
  Purged 'BedWars-5'
✓ Purged 2/2 crashed service(s).

Argument	Description
`<service>`	Force-kill and remove a specific service
`crashed`	Remove all services in CRASHED state
`pid:<pid>`	Kill any process by its system PID

purge force-kills processes immediately without graceful shutdown. Use stop first whenever possible.

Tab completion: Running service names.

`screen`

Attach to a service's live console output. You can type commands directly into the server.

Syntax: screen <service>

Nimbus

nimbus » screen Lobby-1
ℹ Attached to Lobby-1 (ESC or Ctrl+Q to detach)
────────────────────────────────────────────────────────
[14:23:01 INFO]: Done (2.341s)! For help, type "help"
[14:23:05 INFO]: Player Steve joined the game
> say Hello from Nimbus!
[14:23:12 INFO]: [Server] Hello from Nimbus!
────────────────────────────────────────────────────────
ℹ Detached from Lobby-1

Press ESC or Ctrl+Q to detach and return to the Nimbus console.

Cannot attach to services in STOPPED or PREPARING state.

Tab completion: Running service names.

`exec`

Execute a command on a service's stdin without attaching to its console.

Syntax: exec <service> <command...>

Nimbus

nimbus » exec Lobby-1 say Restarting in 5 minutes!
✓ Sent to Lobby-1: say Restarting in 5 minutes!

Tab completion: Running service names (first argument).

`logs`

Show recent log output from a service's logs/latest.log file.

Syntax: logs <service> [lines]

Nimbus

nimbus » logs BedWars-1 20
── Logs: BedWars-1 ────────────────────────────────
Last 20 line(s) from services/BedWars-1/logs/latest.log
────────────────────────────────────────────────────────
[14:23:01 INFO]: Player Alex joined the game
[14:23:05 INFO]: Player Steve joined the game
...
────────────────────────────────────────────────────────
20 of 1482 line(s)

Defaults to 50 lines if not specified. If the log file doesn't exist, Nimbus suggests using screen for live output.

Tab completion: Running service names.

`players`

List all connected players across services. Queries each READY service via Server List Ping.

Syntax: players [service]

Nimbus

nimbus » players
── Players ───────────────────────────────────────
PLAYER      SERVICE       SERVER
──────────────────────────────────────────────────
Alex        BedWars-1     BedWars
Notch       Lobby-1       Lobby
Steve       BedWars-1     BedWars
3 player(s) online

Pass a service name to filter: players Lobby-1.

Tab completion: Running service names.

`health`

Show health metrics for running services: TPS, memory usage, health status, restart count, and uptime.

Syntax: health [service|group]

Nimbus

nimbus » health
── Service Health ─────────────────────────────────
NAME            STATE           TPS    MEMORY          HEALTH     RESTARTS  UPTIME
──────────────────────────────────────────────────────────────────────────────────────
Lobby-1         ● READY          19.9   412/1024MB      healthy    0         2h 15m
Lobby-2         ● READY          16.2   890/1024MB      unhealthy  2         1h 42m
BedWars-1       ● READY          20.0   256/1024MB      healthy    0         0h 55m
3 service(s)
! 1 service unhealthy

Pass a service name for a detailed view with memory progress bar and last SDK health report timestamp:

Nimbus

nimbus » health Lobby-1

Also available in-game via /cloud health (permission: nimbus.cloud.health).

Tab completion: Service names and group names.

Group Management

`groups`

List all configured server groups with software, version, and instance counts.

Syntax: groups

Nimbus

nimbus » groups
── Groups ────────────────────────────────────────
NAME        TYPE      SOFTWARE    VERSION    MEMORY  INSTANCES  MIN/MAX
──────────────────────────────────────────────────────────────────────────
Proxy       STATIC    VELOCITY    3.4.0      512M    1          1/1
Lobby       DYNAMIC   PAPER       1.21.4     1G      2          2/4
BedWars     DYNAMIC   PAPER       1.21.4     2G      2          1/8
3 group(s)

`info`

Show detailed configuration and runtime state for a group.

Syntax: info <group>

Nimbus

nimbus » info BedWars
── Group: BedWars ─────────────────────────────────
  Type                  DYNAMIC
  Software              PAPER
  Version               1.21.4
  Template              default
▸ Resources
  Memory                2G
  Max Players           16
▸ Scaling
  Min Instances         1
  Max Instances         8
  Players/Instance      16
  Scale Threshold       80%
  Idle Timeout          300000ms
▸ Lifecycle
  Stop on Empty         yes
  Restart on Crash      yes
  Max Restarts          5
▸ JVM
  Optimize              Aikar's Flags + Config Tuning
▸ Runtime
  Running Instances     2
  Total Players         24

Tab completion: Group names.

`create`

Launch an interactive wizard to create a new server group. Clears the screen and walks through:

Group name
Server software (Paper, Pufferfish, Purpur, Leaf, Folia, Forge, NeoForge, Fabric, Custom, or Modpack import)
Minecraft version (with tab completion from live version lists)
Modloader version (for Forge/NeoForge/Fabric only)
Static vs. dynamic mode
Instance counts and memory
Via plugins (ViaVersion/ViaBackwards/ViaRewind -- Paper/Purpur/Leaf/Folia only)
Automatic JAR download and template setup
Optional immediate instance start

Syntax: create

Example: Paper game server

The most common case -- a Paper backend with Via plugin support.

Nimbus — Create Wizard

Create New Group
Group name: SkyWars
Available server software:
  paper       — Paper (optimized vanilla, plugins)
  pufferfish  — Pufferfish (Paper fork, performance)
  purpur      — Purpur (Paper fork, extra features)
  leaf        — Leaf (Paper fork, performance + stability)
  folia       — Folia (regionized multithreading, 1.19.4+)
  forge       — Forge (mods, auto-installs)
  neoforge    — NeoForge (modern Forge fork)
  fabric      — Fabric (lightweight mods)
  modpack     — Import a Modrinth modpack
  custom      — Custom JAR (bring your own)
Server software [paper]: paper
Fetching available versions... ✓
Stable: 1.21.4  1.21.3  1.21.1  1.20.6  1.20.4  1.20.2  1.20.1  1.19.4  ...
Minecraft version [1.21.4]: 1.21.4
Static services keep their data (world, configs) across restarts.
Dynamic services start fresh from the template every time.
Static service [y/N]: n
Min instances [1]: 1
Max instances [4]: 8
Memory per instance [1G]: 2G
Protocol support:
ViaVersion allows newer clients, ViaBackwards allows older clients.
Install ViaVersion? [y/N]: n
Install ViaBackwards? (older clients can join) [Y/n]: y
Install ViaRewind? (1.7/1.8 clients) [y/N]: n
✓ Via plugins: ViaBackwards
Downloading files...
↓ Paper 1.21.4 ✓
↓ ViaBackwards ✓
✓ config/groups/skywars.toml
✓ Group configs reloaded
Group 'SkyWars' created!
Start an instance now? [Y/n]: y
✓ Service start initiated.

Example: Fabric modded server

For Fabric, Forge, and NeoForge, the wizard adds a modloader version prompt after the Minecraft version. It also auto-downloads the appropriate proxy forwarding mod -- FabricProxy-Lite for Fabric, or a Forge/NeoForge forwarding mod for Forge-based servers. Via plugin prompts are skipped since modded servers don't use them.

Nimbus — Create Wizard

Create New Group
Group name: Survival
Available server software:
  paper       — Paper (optimized vanilla, plugins)
  pufferfish  — Pufferfish (Paper fork, performance)
  purpur      — Purpur (Paper fork, extra features)
  leaf        — Leaf (Paper fork, performance + stability)
  folia       — Folia (regionized multithreading, 1.19.4+)
  forge       — Forge (mods, auto-installs)
  neoforge    — NeoForge (modern Forge fork)
  fabric      — Fabric (lightweight mods)
  modpack     — Import a Modrinth modpack
  custom      — Custom JAR (bring your own)
Server software [paper]: fabric
Fetching available versions... ✓
Stable: 1.21.4  1.21.3  1.21.1  1.20.6  1.20.4  ...
Minecraft version [1.21.4]: 1.21.4
Fetching modloader versions... ✓
Available: 0.16.9  0.16.8  0.16.7  0.16.6  0.16.5  ...
Modloader version [0.16.9]: 0.16.9
Static services keep their data (world, configs) across restarts.
Dynamic services start fresh from the template every time.
Static service [y/N]: y
Min instances [1]: 1
Max instances [1]: 1
Memory per instance [1G]: 4G
Downloading files...
↓ Fabric 0.16.9 for MC 1.21.4 ✓
↓ FabricProxy-Lite ✓
✓ config/groups/survival.toml
✓ Group configs reloaded
Group 'Survival' created!
Start an instance now? [Y/n]: y
✓ Service start initiated.

Press Ctrl+C at any point to cancel the wizard. Selecting modpack as the software type redirects to the import wizard instead.

`import`

Import a modpack as a new server group. Supports Modrinth, CurseForge, and server pack ZIPs. Clears the screen and walks through resolving the modpack, displaying its info, downloading the modloader, mods, configs/overrides, and proxy forwarding mods.

Syntax: import <url|slug|curseforge:slug|path.mrpack|path.zip>

Accepts:

Modrinth URLs: import https://modrinth.com/modpack/adrenaserver
Modrinth slugs: import adrenaserver
CurseForge URLs: import https://curseforge.com/minecraft/modpacks/all-the-mods-10
CurseForge slugs: import curseforge:all-the-mods-10
Server pack ZIPs: import /path/to/ServerFiles-6.6.zip
Local .mrpack files: import /path/to/modpack.mrpack

Nimbus — Import Wizard

nimbus » import adrenaserver
Import Modpack
Resolving modpack... ✓
Adrenaserver v1.2.0
MC 1.21.4 · FABRIC 0.16.9
42 server mods (18 client-only skipped)
Group name [Adrenaserver]: Adrenaserver
Static services keep their data (world, configs) across restarts.
Dynamic services start fresh from the template every time.
Static service [Y/n]: y
Memory per instance [2G]: 4G
Min instances [1]: 1
Max instances [1]: 1
Installing...
↓ FABRIC 0.16.9 ✓
↓ Mods 42/42 lithium-fabric-0.14.3-mc1.21.4.jar
✓ 42 mods downloaded
↓ Configs & overrides ✓
↓ Proxy mods ✓
✓ config/groups/adrenaserver.toml
✓ Group configs reloaded
Modpack 'Adrenaserver' imported as group 'Adrenaserver'!
Start an instance now? [Y/n]: y
✓ Service start initiated.

The wizard automatically handles proxy forwarding -- FabricProxy-Lite for Fabric modpacks, or the appropriate Forge/NeoForge forwarding mod. Client-only mods are detected from the modpack index and skipped during installation.

`update`

Update a group's server software or Minecraft version. Supports both direct and interactive modes. Includes compatibility checks that prevent incompatible switches (e.g., plugin servers to modded, Forge to Fabric).

Syntax: update <group> [version <ver>] [software <sw> [<ver>]]

Update Minecraft version

Nimbus

nimbus » update Lobby version 1.21.5
ℹ Updating Lobby: 1.21.4 -> 1.21.5
Downloading paper 1.21.5... ok
ok Configs reloaded
Updated 'Lobby' to version 1.21.5.

Switch server software

Nimbus

nimbus » update Lobby software purpur
ℹ Updating Lobby: PAPER 1.21.4 -> PURPUR 1.21.4
Downloading purpur 1.21.4... ok
ok Configs reloaded
Updated 'Lobby' to PURPUR 1.21.4.

Switch software and version at once

Nimbus

nimbus » update Lobby software purpur 1.21.5
ℹ Updating Lobby: PAPER 1.21.4 -> PURPUR 1.21.5
Downloading purpur 1.21.5... ok
ok Configs reloaded
Updated 'Lobby' to PURPUR 1.21.5.

Interactive mode

Running update <group> without subcommands opens an interactive wizard:

Nimbus — Update Wizard

nimbus » update Lobby
Update Group: Lobby

Current: PAPER 1.21.4

What to update? [version]: software
Compatible software for PAPER:
  purpur
Fetching available versions... ok
Available: 1.21.4  1.21.3  1.21.1  1.20.6  ...
Minecraft version [1.21.4]: 1.21.4

ℹ Updating Lobby: PAPER 1.21.4 -> PURPUR 1.21.4
Downloading purpur 1.21.4... ok
ok Configs reloaded
Updated 'Lobby' to PURPUR 1.21.4.

Compatibility rules

The update command enforces compatibility between server software families to prevent broken servers:

Switch	Allowed	Reason
Paper ↔ Pufferfish ↔ Purpur ↔ Leaf ↔ Folia	Yes	Same plugin API family (Paper forks). Note: most plugins won't work on Folia.
Forge ↔ NeoForge	Yes (with warning)	Similar but diverging mod ecosystems
Paper/Pufferfish/Purpur/Leaf → Forge/Fabric/NeoForge	No	Plugins and mods are incompatible
Forge/NeoForge → Fabric	No	Completely different mod formats
Fabric → Forge/NeoForge	No	Completely different mod formats
Any ↔ Velocity	No	Proxy vs game server
Any ↔ Custom	No	Cannot auto-resolve custom JARs

Running services are not automatically restarted after an update. Restart them manually to apply the changes.

Tab completion: Group names → version/software → software names (for software subcommand).

`static`

Convert a group or individual service to static mode. Static services preserve their working directory across restarts.

Syntax: static group <name> | static service <name>

Nimbus

nimbus » static group BedWars
✓ Group 'BedWars' is now STATIC.
New services will preserve their working directory across restarts.
⚠ 2 running service(s) are still dynamic. Use 'static service <name>' to convert them individually.

Nimbus

nimbus » static service BedWars-1
ℹ Converting 'BedWars-1' to static (copying working directory)...
✓ Service 'BedWars-1' is now static.
Working directory will be preserved when the service stops.

Tab completion: group/service subcommands, then group or service names.

`dynamic`

Set a group back to dynamic mode. Dynamic services start fresh from the template each time.

Syntax: dynamic <group>

Nimbus

nimbus » dynamic BedWars
✓ Group 'BedWars' is now DYNAMIC.
New services will use temporary directories that are cleaned up on stop.

Tab completion: Group names.

Permission Management

The perms command manages Nimbus's built-in permission system. All subcommands support tab completion.

Syntax: perms <group|user|track|audit|reload> [subcommand] [args]

Group Subcommands

`perms group list`

List all permission groups with their default status, priority, and parent groups.

Nimbus

nimbus » perms group list
── Permission Groups ─────────────────────────────
NAME        DEFAULT    PRIORITY  PREFIX       PERMISSIONS  PARENTS
──────────────────────────────────────────────────────────────────────
Admin       no         100       [Admin]      12           Moderator
Moderator   no         50        [Mod]        5            Default
Default     yes        0         -            3            -
3 group(s)

`perms group info <name>`

Show full details of a permission group including all permissions.

Nimbus

nimbus » perms group info Admin
── Permission Group: Admin ──────────────────────
  Default:   no
  Priority:  100
  Prefix:    [Admin]
  Suffix:    -
  Parents:   Moderator
▸ Permissions (4)
  nimbus.cloud.audit
  nimbus.cloud.*
  nimbus.cloud.start
  -nimbus.cloud.shutdown

Other group subcommands

Command	Description
`perms group create <name>`	Create a new permission group
`perms group delete <name>`	Delete a permission group
`perms group addperm <group> <permission>`	Add a permission to a group
`perms group removeperm <group> <permission>`	Remove a permission from a group
`perms group setdefault <group> [true/false]`	Set whether a group is the default
`perms group addparent <group> <parent>`	Add permission inheritance
`perms group removeparent <group> <parent>`	Remove permission inheritance
`perms group setprefix <group> <prefix...>`	Set display prefix (MiniMessage format)
`perms group setsuffix <group> <suffix...>`	Set display suffix
`perms group setpriority <group> <number>`	Set display priority
`perms group setweight <group> <number>`	Set conflict resolution weight
`perms group meta <set\|remove\|list> <group> [key] [value]`	Manage custom metadata

User Subcommands

Command	Description
`perms user list`	List all players with assigned groups
`perms user info <name\|uuid>`	Show a player's groups, permissions, and display format
`perms user addgroup <name\|uuid> <group>`	Add a player to a group
`perms user removegroup <name\|uuid> <group>`	Remove a player from a group
`perms user check <name\|uuid> <permission>`	Check if a player has a permission (shows resolution chain)
`perms user promote <name\|uuid> <track>`	Promote to next group in a track
`perms user demote <name\|uuid> <track>`	Demote to previous group in a track
`perms user meta <set\|remove\|list> <name\|uuid> [key] [value]`	Manage custom metadata

`perms reload`

Reload permission data from files.

Track Subcommands

Command	Description
`perms track list`	List all permission tracks
`perms track create <name> <group1,group2,...>`	Create a new track with ordered groups
`perms track delete <name>`	Delete a permission track

`perms audit [lines]`

Show the permission audit log with recent changes. Defaults to 20 entries.

Punishments

The Punishments module adds the punish console command (and /cloud punish … in-game via the Bridge) for managing network-wide bans, mutes, kicks, and warnings. See the Punishments guide for the full concept overview.

`punish`

Issue, revoke, list, and inspect punishments.

Permission: nimbus.cloud.punish (console). In-game subcommands honour LuckPerms-style nodes: nimbus.punish.ban, nimbus.punish.tempban, nimbus.punish.ipban, nimbus.punish.mute, nimbus.punish.tempmute, nimbus.punish.kick, nimbus.punish.warn, nimbus.punish.unban, nimbus.punish.unmute, nimbus.punish.history, plus nimbus.punish.bypass to skip mute enforcement.

Subcommand	Syntax
`ban`	`punish ban <player> [--group <g>\|--service <s>] <reason>`
`tempban`	`punish tempban <player> <duration> [--group <g>\|--service <s>] <reason>`
`ipban`	`punish ipban <player> <ip> <reason>`
`mute`	`punish mute <player> [--group <g>\|--service <s>] <reason>`
`tempmute`	`punish tempmute <player> <duration> [--group <g>\|--service <s>] <reason>`
`kick`	`punish kick <player> <reason>`
`warn`	`punish warn <player> <reason>`
`unban`	`punish unban <player> [--group <g>\|--service <s>]`
`unmute`	`punish unmute <player> [--group <g>\|--service <s>]`
`history`	`punish history <player>`
`list`	`punish list [type]`

Player identity: pass a current username, a raw UUID, or a name that has never joined the network. Unknown names are resolved through the Mojang profile API, so you can pre-ban players before their first login. The canonical Mojang casing is used for audit entries.

Scope: without --group or --service, the punishment is network-wide. --group <name> limits enforcement to backends in that group; --service <name> limits it to that single service instance. Players stay on the network and just can't enter the banned backends. A player can carry multiple punishments of different scopes simultaneously (e.g. a BedWars ban plus a network-wide mute).

Durations: 30s, 15m, 2h, 7d, 30d — any combination of s/m/h/d suffixes.

Nimbus

nimbus » punish tempban Griefer 7d --group BedWars hacking
✓ TEMPBAN issued — Griefer until 2026-04-21 (scope=GROUP:BedWars)
nimbus » punish mute Spammer spamming chat
✓ MUTE issued — Spammer (scope=NETWORK)
nimbus » punish history Griefer
── Punishments for Griefer ────────────
#42  TEMPBAN  scope=GROUP:BedWars  exp=7d  reason=hacking
#17  KICK     reason=afk   2026-04-10

Tab completion: player names (online + recent history).

Editable messages

Kick/mute/warn templates live in config/modules/punishments/messages.toml with placeholders {target}, {issuer}, {reason}, {remaining}, {expires}. The templates are hot-reloaded — edits via the dashboard (GET/PUT /api/punishments/messages) or direct file edits followed by a controller restart both take effect immediately.

Resource Packs

`resourcepack`

Manage the network-wide resource pack registry. Packs can be referenced by URL or uploaded directly to Nimbus (stored under data/resourcepacks/<uuid>.zip). Assignments attach packs to GLOBAL, a GROUP, or a single SERVICE with priority ordering.

Permission: nimbus.cloud.resourcepack.

Subcommand	Syntax
`list`	`resourcepack list`
`add`	`resourcepack add <name> <url> [--force] [--prompt <msg>]`
`upload`	`resourcepack upload <name> <path> [--force] [--prompt <msg>]`
`remove`	`resourcepack remove <id>`
`assign`	`resourcepack assign <id> <global\|group <name>\|service <name>> [priority]`
`unassign`	`resourcepack unassign <assignment-id>`
`assignments`	`resourcepack assignments [pack-id]`

add streams the URL once to compute SHA-1 so you don't have to hash by hand. upload streams a local .zip through a 64 KiB transfer buffer into data/resourcepacks/ with SHA-1 hashing and an atomic rename.

Priority stack: when multiple packs apply to the same service, the stack order is GLOBAL < GROUP < SERVICE, with priority ascending within each scope. On Minecraft 1.20.3+ the backend plugin uses the multi-pack UUID API so every pack in the stack is sent; older servers fall back to the single highest-priority pack.

Nimbus

nimbus » resourcepack add MainPack https://cdn.example.com/main.zip --force
ℹ Downloading https://cdn.example.com/main.zip to compute SHA-1…
✓ Registered 'MainPack' (#1) — sha1=b2c3…
nimbus » resourcepack assign 1 global 0
✓ Assigned pack #1 to GLOBAL (priority=0, assignment #1)
nimbus » resourcepack assign 1 group BedWars 10
✓ Assigned pack #1 to GROUP 'BedWars' (priority=10, assignment #2)

See the Resource Packs guide for the backend plugin's behaviour, the public download endpoint, and telemetry.

Plugin Management

`plugins`

Search, install, and manage third-party server plugins from Hangar and Modrinth.

Running plugins with no arguments (or plugins search) opens the interactive live search:

Select a target (global or a specific group)
Type to search — results from Hangar + Modrinth appear live (version-aware)
Use ↑↓ to navigate, Space to select multiple plugins, Enter to confirm
Required dependencies are automatically downloaded

Nimbus

plugins                        # Open interactive search
plugins search global          # Search for plugins targeting all backends
plugins search Lobby WorldEdit # Search "WorldEdit" for Lobby group's MC version
plugins list                   # Show all installed plugins across all targets
plugins list global            # Show plugins in global/plugins/
plugins list Lobby             # Show plugins in Lobby template
plugins remove WorldEdit.jar global  # Remove a specific plugin JAR

Multi-Select

Press Space on multiple search results before pressing Enter — all selected plugins (plus their dependencies) are installed in a single batch.

Dedicated Services

`dedicated`

Manage dedicated services — single-instance services with a fixed port and a persistent managed directory under paths.dedicated/<name>/. Unlike groups, dedicated services have no scaling and are identified by a user-defined name.

Syntax: dedicated <subcommand> [args]

Subcommand	Description
`dedicated list`	List all configured dedicated services with state, port, and uptime
`dedicated create`	Launch an interactive wizard to create a new dedicated service
`dedicated info <name>`	Show detailed configuration and runtime state for a dedicated service
`dedicated start <name>`	Start a dedicated service
`dedicated stop <name>`	Gracefully stop a dedicated service
`dedicated restart <name>`	Stop and restart a dedicated service
`dedicated delete <name>`	Delete a dedicated service and its config (prompts for confirmation)

Nimbus

nimbus » dedicated list
── Dedicated Services ─────────────────────────────
NAME        SOFTWARE    STATE       PORT    UPTIME
───────────────────────────────────────────────────
Survival    FABRIC      ● READY     25566   3d 2h
Creative    PAPER       ● READY     25567   1d 4h
2 service(s)

Tab completion: Subcommand names, then dedicated service names.

See Dedicated Services for full setup documentation.

Network & System

`audit`

Show the audit log of administrative actions (service starts/stops, config changes, scaling decisions, etc.).

Syntax: audit [limit] [--action <type>] [--actor <name>]

Examples:

audit — Show last 20 entries
audit 50 — Show last 50 entries
audit --action SERVICE_STARTING — Filter by action type
audit --actor console — Filter by who triggered the action

Each entry shows: timestamp, actor (console/api/system), action type, target, and details.

`status`

Full cluster overview showing groups, instances, player counts, and capacity.

Syntax: status

Nimbus

nimbus » status
── Network: MyNetwork ────────────────────────────
Services: 5 ready / 5 total    Players: 36
GROUP       TYPE      INSTANCES  MIN/MAX  PLAYERS  STATUS
────────────────────────────────────────────────────────────────
Proxy       STATIC    1          1/2      36       healthy
Lobby       DYNAMIC   2          2/4      12       healthy
BedWars     DYNAMIC   2          1/8      24       healthy
Capacity: ████████░░░░░░░░░░░░░░░░░░░░░░ 5/20 services
Bedrock:  enabled (Geyser + Floodgate, base port 19132)

The Bedrock line only appears when [bedrock] enabled = true is set in nimbus.toml.

`send`

Transfer a player to another service via the Velocity proxy.

Syntax: send <player> <service>

Requires a running Velocity proxy instance.

`broadcast`

Send a message to all ready services (or a specific group) using the server's native broadcast command.

Syntax: broadcast [--group <group>] <message...>

Nimbus

nimbus » broadcast Server restart in 5 minutes!
✓ Broadcast sent to 4/4 services in network.

nimbus » broadcast --group Lobby Please move to BedWars!
✓ Broadcast sent to 2/2 services in group 'Lobby'.

On Velocity proxies the command uses velocity broadcast <message>.
On all other backends it uses say <message>.
Only READY services are targeted.

Tab completion: --group, then group names.

Permission: nimbus.cloud.broadcast

`setstate`

Set or clear a custom state label on a READY service. Custom states are arbitrary strings (e.g. INGAME, WAITING, FULL) used by game plugins and the SDK to signal slot availability.

Syntax: setstate <service> <state|clear>

Nimbus

nimbus » setstate BedWars-1 INGAME
✓ Custom state on 'BedWars-1' set to 'INGAME'.

nimbus » setstate BedWars-1 clear
✓ Cleared custom state on 'BedWars-1'.

Use clear or null to remove a previously set custom state.

Tab completion: Service names.

Permission: nimbus.cloud.setstate

`reload`

Hot-reload all group configuration files and proxy sync settings. Running services are not affected.

Syntax: reload

If a group is removed from config but has running services, they will continue until manually stopped.

`api`

Manage the REST API server.

Syntax: api <start|stop|status|token> [port]

Subcommand	Description
`api` or `api status`	Show API status, endpoint, and auth info
`api start [port]`	Start the API on the configured port or a custom one
`api stop`	Stop the API
`api token`	Show the configured API token (partially masked)

Tab completion: start, stop, status, token.

`nodes`

Show connected cluster nodes. Only available when cluster mode is enabled (cluster.enabled = true).

Syntax: nodes [node-name]

Without arguments, shows a summary table of all nodes. With a node name, shows detailed info including CPU, memory, running services, and agent version.

If no nodes are connected, the command prints a warning. Use this to verify agents are properly connected to the controller.

Tab completion: Node names.

`lb`

Manage the TCP load balancer. This command works independently of cluster mode — you can use a load balancer with multiple local Velocity proxies without enabling cluster mode.

Syntax: lb [status|enable|disable|strategy <name>]

Subcommand	Description
`lb enable`	Enable the load balancer (saves to config, restart required)
`lb disable`	Disable the load balancer
`lb strategy <name>`	Set strategy: `least-players` or `round-robin`

Tab completion: status, enable, disable, strategy → strategy names.

`maintenance`

Toggle maintenance mode for the entire network or individual server groups.

Command	Description
`maintenance`	Show current maintenance status
`maintenance on`	Enable global maintenance (blocks new connections)
`maintenance off`	Disable global maintenance
`maintenance <group> on`	Put a specific group in maintenance
`maintenance <group> off`	Remove maintenance from a group
`maintenance list`	Show whitelisted players
`maintenance add <player>`	Add player to maintenance whitelist
`maintenance remove <player>`	Remove player from maintenance whitelist

Tab completion: on, off, list, add, remove, group names.

`shutdown`

Gracefully shut down all services in order: game servers first, then lobbies, then proxies.

Syntax: shutdown

Shutdown requires confirmation. Run shutdown first, then shutdown confirm within 30 seconds.

`clear`

Clear the terminal screen.

Syntax: clear

`help`

Show all available commands or detailed help for a specific command.

Syntax: help [command]

You can also type ? as a shorthand for help.

`version`

Show the running Nimbus version and immediately check GitHub Releases for a newer version.

Syntax: version

Aliases: ver

Nimbus

nimbus » version
Nimbus v0.8.1
Checking for updates...
✓ Up to date (latest: v0.8.1)

If an update is available the output includes the new version number and a note on whether it will be applied automatically (patch/minor) or requires confirmation (major).

Diagnostics

`doctor`

Run a battery of diagnostic checks against the running controller — configuration sanity, port conflicts, database connectivity, module health, template integrity, agent reachability, disk space, Java versions.

Syntax: doctor [--json]

Nimbus

nimbus » doctor
── Nimbus Doctor ────────────────────────────────
[PASS] controller.bind   127.0.0.1:8080 reachable
[PASS] database          SQLite data/nimbus.db OK (12 tables)
[WARN] templates         Lobby: EULA not accepted yet
[PASS] cluster           TLS enabled, 2/2 nodes online
[FAIL] java              No Java 17 detected for group Hub
3 PASS, 1 WARN, 1 FAIL

Pass --json for machine-readable output (used by the dashboard's Doctor page).

See the Doctor Guide for the full check catalogue and how to extend it.

`modules`

Manage controller modules (perms, display, scaling, players, punishments, resourcepacks, backup, and any third-party JARs dropped into modules/).

Syntax: modules [list|install [id]|uninstall <id>]

Subcommand	Description
`modules list` (default)	List loaded + available modules with version and description
`modules install`	Interactive picker for modules not yet installed
`modules install <id>`	Install a specific module by id (`perms`, `display`, `scaling`, `players`, `punishments`, `resourcepacks`, `backup`)
`modules uninstall <id>`	Unload and delete a module JAR

Installing or uninstalling a module requires a controller restart (shutdown + shutdown confirm) — migrations and embedded plugins are wired at startup.

`stress`

Simulate player load across backend services without real Minecraft clients. Useful for proxy throughput, scaling-rule tuning, and finding the real max_players ceiling of a group.

Syntax: stress [start <players> [group] [--ramp <seconds>] | stop | ramp <players> [--duration <seconds>] | status]

Nimbus

nimbus » stress start 500 Lobby --ramp 30
ℹ Ramping to 500 simulated players on group 'Lobby' over 30s...
nimbus » stress status
── Stress Test ──────────────────────────────────
Active: yes    Target: 500    Current: 280    Group: Lobby
Proxy auto-mirrors total backend player count.

The scaling engine pauses while a stress test is active — simulated players won't trigger real scale-ups. Proxy groups are never simulated; only backends. See Stress Testing.

Modules

These commands are registered by controller modules and are only available when the corresponding module is installed. See modules to install.

`backup`

Manage backup snapshots, schedules, verification, restore, and retention pruning. Registered by the backup module.

Subcommand	Description
`backup now [--type <scope>] [--target <name>]`	Trigger a manual backup (all scopes by default; `--type services/dedicated/templates/controller_config/state_sync/database`; `--target` for a single service)
`backup list [--limit <n>]`	List recent backups with id, status, size, duration
`backup status`	Active jobs, next scheduled runs, last results
`backup verify <id>`	Recompute SHA-256 against the archive's `MANIFEST.sha256` trailer
`backup restore <id> [--target <path>] [--dry-run] [--force]`	Extract an archive back to the original path or a custom one
`backup prune [--retention-class <class>] [--dry-run]`	Apply GFS retention now
`backup schedule list`	Show every configured schedule and its next fire time
`backup schedule reload`	Re-read `backup.toml` without a controller restart
`backup delete <id>`	Delete an archive (manual backups are otherwise immune to pruning)

Full workflows, cron syntax, and the GFS retention model live in the Backup Guide.

`scaling`

Inspect the Smart Scaling module — time-based schedules, predictive warmup, and player-count history. Registered by the scaling module.

Syntax: scaling <status|schedule|history|predict|reload> [group] [args]

Subcommand	Description
`scaling status`	Overview of every group: current/min/max instances, active schedule, next predicted change
`scaling schedule list`	All schedules across groups
`scaling schedule info <group>`	Schedules for a specific group
`scaling history <group> [hours]`	Player-count history (default 24h) used for prediction
`scaling predict <group>`	Next 6h predicted player count + suggested instance count
`scaling reload`	Re-read `config/modules/scaling/*.toml`

See the Scaling Guide.

Cluster & Load Balancer

These commands manage multi-node cluster mode. The cluster command works regardless of whether cluster mode is currently enabled — it's how you enable it. The nodes command is only available when cluster mode is active. The lb command is documented above under Service Management — it's independent of cluster mode.

`cluster`

Manage cluster mode and load balancer settings from the console without editing config files. Changes are saved to nimbus.toml and take effect after restart.

Subcommand	Description
`cluster status`	Show cluster and load balancer status
`cluster enable`	Enable cluster mode (generates auth token if none exists)
`cluster disable`	Disable cluster mode
`cluster token`	Show the current cluster auth token (partially masked)
`cluster token regenerate`	Generate a new cluster token (update all agents!)
`cluster cert`	Show the SHA-256 fingerprint, expiry, and SANs of the current TLS cert
`cluster cert regenerate`	Delete `config/cluster.jks` so a fresh self-signed cert is generated on next restart. All agents will need to re-run `--setup` to re-pin the new fingerprint.
`cluster bootstrap-url`	Print the REST URL and cluster token, formatted for copy-paste into the agent setup wizard

Tab completion: status, enable, disable, token → regenerate, cert → regenerate, bootstrap-url.

See Cluster TLS & Security for the trust-on-first-use flow and cert rotation instructions.

nimbus » sessions active
── Active CLI Sessions ──────────────────────────────
ID   USER@HOST            OS                IP             LOCATION                CONNECTED         DURATION
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────
#3   jonas@DESKTOP-ABC    Windows 11 amd64  85.123.45.67   Berlin, Germany         07.04.2026 14:32  13m 7s
1 active session(s)

`sessions history`

Show recent session history (default: last 20):

Nimbus

nimbus » sessions history --limit 5
── CLI Session History ──────────────────────────────
ID   USER@HOST            IP             LOCATION            CONNECTED         DURATION  CMDS  STATUS
────────────────────────────────────────────────────────────────────────────────────────────────────────
#3   jonas@DESKTOP-ABC    85.123.45.67   Berlin, Germany     07.04.2026 14:32  13m 7s    24    ● online
#2   admin@server-01      10.0.0.5       local               07.04.2026 12:10  1h 23m    67    ○ closed
#1   jonas@DESKTOP-ABC    85.123.45.67   Berlin, Germany     07.04.2026 10:05  45m 12s   31    ○ closed
3 session(s)

Tab completion: active, history.

Console Commands

On this page