NoxAeApi

CLI & Terminal REPL

NoxAe CLI Client & Commands Reference

Interactive terminal REPL and high-speed one-shot command-line tool (@wumx-labs/noxaeapi-cli) for managing Minecraft servers, players, economy, LuckPerms, and Velocity proxy networks directly from your shell.

v2.0.5binary: noxaeSmart Autocompletion & Multi-Profile14 CLI Resources

Key Highlights

Interactive REPL Mode

Type "noxae" to launch a full-featured terminal REPL with live popup suggestions, history navigation, and active profile indicator.

Dynamic Live Suggestions

Intelligently suggests commands, subcommands, player UUIDs, currency names, LuckPerms groups, and world dimensions as you type.

Multi-Profile Management

Easily store and switch between development, production, proxy hub, and local staging servers using /connect and /use <name>.

Velocity Proxy Node Targeting

Send commands to specific backend servers through a central network hub with the "@<nodeId> <resource> <action>" syntax.

Installation

Install the CLI package globally using your preferred package manager, or execute it instantly via npx without installing:

Terminal
# Global install via npm
npm install -g @wumx-labs/noxaeapi-cli

# pnpm
pnpm add -g @wumx-labs/noxaeapi-cli

# bun
bun add -g @wumx-labs/noxaeapi-cli

# Or run instantly without installing
npx @wumx-labs/noxaeapi-cli

Live Interactive Terminal REPL Preview

To launch the interactive session, execute "noxae" with no arguments. On first launch, use /connect to link your Minecraft server URL and API key:

noxae — interactive REPL
v2.0.5
NoxAeAPI CLI·by wumx
profile survival → http://10.0.0.2:4567

type / to browse commands, /exit to quit

/connect add a new profile
/profiles list saved profiles
/use <name> switch active profile
/edit <name> edit a profile
tip: type / for commands, ?name to look up usage · ↑↓ navigate · tab complete · enter run
(survival) noxae > players list
✔players.list(...)745ms
[]
(survival) noxae > /
❯/connect
add a new profile
/profileslist saved profiles
/use <name>switch active profile
/edit <name>edit a profile
/rename <name> <new name>rename a profile
/remove <name>delete a profile
/json <cmd...>force raw JSON output
/clearclear the screen
/aboutabout this CLI
/helpshow all commands
/exitquit
↑↓ navigate · enter select · esc dismiss

Local Profile Storage Location

Server profiles are securely persisted in JSON format at ~/.noxaeapi-cli/config.json. You can edit this file directly or manage profiles with /edit, /rename, and /remove.

Profile Setup & /connect Guide

The "/connect" command runs a multi-step interactive prompt wizard to configure and test a server profile. The CLI supports two connection architectures: Standard Backend Servers (Spigot/Paper) and Velocity Proxy Network Hubs.

1Profile Name

Unique label for your profile (e.g. "survival", "lobby", "proxy-hub"). Enter uses "default".

profile name: survival
2Base URL Host

HTTP endpoint and port of the NoxAeApi plugin (e.g. "http://10.0.0.2:4567").

base URL: http://10.0.0.2:4567
3Secret API Key

Secret API key from server config.yml for header authentication. Blank if disabled in dev.

API key: your-secret-key
4Proxy Hub Mode

Type "y" if connecting to NoxAeApi-Velocity proxy hub, or "n" for standalone backend server.

is Velocity hub? (y/N): n

Mode 1: Standalone Backend Server (hub: false)

Used for standalone game servers (Paper, Spigot, Fabric). The CLI uses NoxAeApiClient and performs an automatic ping latency check upon saving:

(noxae) ❯ /connect
profile name: survival
base URL: http://10.0.0.2:4567
API key: my-secret-key
is this a NoxAeApi-Velocity network hub? (y/N): n
✔ pinging server... connected — profile "survival" saved and active (42ms)
14 Resources DirectPing Verified

Mode 2: Velocity Proxy Network Hub (hub: true)

Used when connecting to a NoxAeApi-Velocity proxy hub endpoint. Enables network-wide aggregation and backend node targeting syntax via "@<nodeId>":

(noxae) ❯ /connect
profile name: velocity-hub
base URL: http://10.0.0.2:9090
API key: proxy-hub-key
is this a NoxAeApi-Velocity network hub? (y/N): y
✔ hub profile "velocity-hub" saved and active
@<nodeId> TargetingProxy Aggregation

Slash Commands Reference (/...)

Inside the interactive REPL prompt, internal management commands start with a slash (/). Type "/" at any time to trigger the live popup dropdown:

CommandFunction & REPL Behavior
/connectInteractive Wizard
Launches the 4-step interactive wizard to add a new server connection profile and verifies it with a ping check.
/profilesList Storage
Lists all saved connection profiles in config.json with active indicator (●), host URL, and [hub] badge.
/use <name>Live Autocomplete
Instantly switches active profile. Typing "/use " triggers live dropdown autocomplete for saved profile names.
/edit <name>Edit Wizard
Edits an existing profile’s connection parameters while keeping current values as defaults.
/rename <old> <new>Rename Profile
Renames a saved connection profile without losing its stored connection credentials.
/remove <name>Delete Storage
Deletes a saved profile from local storage and falls back to the next available profile if active.
/json <cmd...>Raw JSON Stream
Executes any resource command and forces raw JSON output in the REPL (e.g. "/json players list").
/clearScreen Utility
Clears the terminal viewport buffer for a fresh workspace.
/updateNPM Version Check
Queries the npm registry in real-time to check for newer CLI releases and renders update commands.
/aboutMetadata Info
Displays CLI version, active profile host, author details, and connection status.
/helpHelp Catalog
Renders the comprehensive help breakdown with all 14 resources, actions, syntax tips, and active node IDs.
/exitSession Control
Exits and terminates the interactive REPL session (alias: /quit).

CLI Resources & Commands Catalog (14)

The NoxAe CLI exposes 14 comprehensive resources covering all server subsystems. Every command can be run either inside the interactive REPL or directly as a one-shot terminal command:

noxae players list → OnlinePlayer[]
REST Spec

Get a formatted table or list of all currently online players with ping, health, and location.

REPL: players list
eg: noxae players list
noxae players listAll [--page<num>][--limit<num>]→ OfflinePlayer[]
REST Spec

Get paginated list of all offline and online players who have ever connected to the server.

REPL: players listAll [--page <num>] [--limit <num>]
eg: noxae players listAll --limit 50
noxae players get <uuid>→ OnlinePlayer
REST Spec

Get in-depth attributes and real-time state for a specific online player by UUID.

REPL: players get <uuid>
eg: noxae players get 069a79f4-44e9-4726-a5be-fca90e38aaf5
noxae players getInventory <uuid>[worldUuid]→ InventorySlot[]
REST Spec

Inspect full armor, hotbar, offhand, and storage inventory slots in a world.

REPL: players getInventory <uuid> [worldUuid]
eg: noxae players getInventory 069a79f4-44e9-4726-a5be-fca90e38aaf5
noxae players teleport <uuid><x><y><z><world>→ void
REST Spec

Teleport player to coordinates (x, y, z) with optional yaw and pitch angles.

REPL: players teleport <uuid> <x> <y> <z> <world>
eg: noxae players teleport 069a79f4-44e9-4726-a5be-fca90e38aaf5 100 64 -200 world
noxae players setGamemode <uuid><SURVIVAL|CREATIVE|ADVENTURE|SPECTATOR>Admin Required→ void
REST Spec

Change player game mode (SURVIVAL, CREATIVE, ADVENTURE, SPECTATOR).

REPL: players setGamemode <uuid> <SURVIVAL|CREATIVE|ADVENTURE|SPECTATOR>
eg: noxae players setGamemode 069a79f4-44e9-4726-a5be-fca90e38aaf5 SURVIVAL
noxae players kick <uuid>[reason]Admin Required→ void
REST Spec

Disconnect an online player with an optional kick reason message.

REPL: players kick <uuid> [reason]
eg: noxae players kick 069a79f4-44e9-4726-a5be-fca90e38aaf5 "Server maintenance"
noxae players ban <uuid>[reason][expiry]Admin Required→ void
REST Spec

Ban a player UUID from the server with an optional reason message.

REPL: players ban <uuid> [reason] [expiry]
eg: noxae players ban 069a79f4-44e9-4726-a5be-fca90e38aaf5 "Hacking violation" 2026-12-31T23:59:59Z
noxae players unban <uuid>Admin Required→ void
REST Spec

Remove an active ban for a player by their exact username.

REPL: players unban <uuid>
eg: noxae players unban 069a79f4-44e9-4726-a5be-fca90e38aaf5
noxae players getStats <uuid>→ PlayerStats
REST Spec

Fetch gameplay statistics (kills, deaths, play time, distance walked).

REPL: players getStats <uuid>
eg: noxae players getStats 069a79f4-44e9-4726-a5be-fca90e38aaf5
noxae players resolve <name>→ PlayerResolveResult
REST Spec

Resolve a player username to their local UUID using the server local player cache.

REPL: players resolve <name>
eg: noxae players resolve NoxlyDev
players-examples.sh
# List online players
noxae players list

# Teleport player to hub
noxae players teleport 069a79f4-44e9-4726-a5be-fca90e38aaf5 0 80 0 world

# Resolve player UUID
noxae players resolve Steve
noxae economy info → { defaultCurrency: string, currencies: string[] }
REST Spec

Get economy plugin information, default currency, and registered currency providers.

REPL: economy info
eg: noxae economy info
noxae economy getBalance <uuid>→ { uuid: string, balance: number }
REST Spec

Get standard Vault balance for a player UUID.

REPL: economy getBalance <uuid>
eg: noxae economy getBalance 069a79f4-44e9-4726-a5be-fca90e38aaf5
noxae economy pay <uuid><amount>[reason]→ { success: boolean, newBalance: number }
REST Spec

Transfer balance between players (alias for deposit to target).

REPL: economy pay <uuid> <amount> [reason]
eg: noxae economy pay 069a79f4-44e9-4726-a5be-fca90e38aaf5 500 "Quest reward"
noxae economy debit <uuid><amount>[reason]Admin Required→ { success: boolean, newBalance: number }
REST Spec

Debit / deduct funds from a player default Vault balance.

REPL: economy debit <uuid> <amount> [reason]
eg: noxae economy debit 069a79f4-44e9-4726-a5be-fca90e38aaf5 250 "Shop purchase"
noxae economy getTopBalance [limit]→ LeaderboardEntry[]
REST Spec

Fetch top richest players on the server for default currency (default 10, max 100).

REPL: economy getTopBalance [limit]
eg: noxae economy getTopBalance 10
noxae economy listCurrencies → string[]
REST Spec

List all supported multi-currencies (CoinsEngine/ExcellentEconomy).

REPL: economy listCurrencies
eg: noxae economy listCurrencies
noxae economy getCurrencyBalance <currency><uuid>→ { uuid: string, balance: number }
REST Spec

Get balance for a specific custom currency name.

REPL: economy getCurrencyBalance <currency> <uuid>
eg: noxae economy getCurrencyBalance coins 069a79f4-44e9-4726-a5be-fca90e38aaf5
noxae economy payCurrency <currency><uuid><amount>[reason]→ { success: boolean, newBalance: number }
REST Spec

Credit / deposit an amount of specific currency into a player balance.

REPL: economy payCurrency <currency> <uuid> <amount> [reason]
eg: noxae economy payCurrency gems 069a79f4-44e9-4726-a5be-fca90e38aaf5 100 "Store top-up"
noxae economy debitCurrency <currency><uuid><amount>[reason]Admin Required→ { success: boolean, newBalance: number }
REST Spec

Debit funds of specific currency from a player balance.

REPL: economy debitCurrency <currency> <uuid> <amount> [reason]
eg: noxae economy debitCurrency gems 069a79f4-44e9-4726-a5be-fca90e38aaf5 50
noxae economy setCurrencyBalance <currency><uuid><amount>[reason]Admin Required→ { success: boolean, newBalance: number }
REST Spec

Set exact balance for a specific custom currency.

REPL: economy setCurrencyBalance <currency> <uuid> <amount> [reason]
eg: noxae economy setCurrencyBalance tokens 069a79f4-44e9-4726-a5be-fca90e38aaf5 1000
noxae economy getCurrencyTop <currency>[limit]→ LeaderboardEntry[]
REST Spec

Fetch top richest players for a specific multi-currency.

REPL: economy getCurrencyTop <currency> [limit]
eg: noxae economy getCurrencyTop gems 10
economy-examples.sh
# Query default Vault balance
noxae economy getBalance 069a79f4-44e9-4726-a5be-fca90e38aaf5

# Deposit $1,000 Vault currency
noxae economy pay 069a79f4-44e9-4726-a5be-fca90e38aaf5 1000 "Web store top-up"

# Multi-currency operations
noxae economy listCurrencies
noxae economy getCurrencyBalance gems 069a79f4-44e9-4726-a5be-fca90e38aaf5
noxae http ping → { status: string, latencyMs: number }

Test HTTP latency and connectivity to the active server base URL.

REPL: http ping
eg: noxae http ping
noxae http get <endpoint>[queryParams]→ unknown

Perform arbitrary HTTP GET against the NoxAeApi REST server.

REPL: http get <endpoint> [queryParams]
eg: noxae http get /v1/server
noxae http post <endpoint>[bodyJson]→ unknown

Perform arbitrary HTTP POST with JSON body.

REPL: http post <endpoint> [bodyJson]
eg: noxae http post /v1/server/exec '{"command":"list"}'
noxae http put <endpoint>[bodyJson]→ unknown

Perform arbitrary HTTP PUT with JSON body.

REPL: http put <endpoint> [bodyJson]
eg: noxae http put /v1/players/gamemode '{"uuid":"...","gamemode":"CREATIVE"}'
noxae http delete <endpoint>→ unknown

Perform arbitrary HTTP DELETE request.

REPL: http delete <endpoint>
eg: noxae http delete /v1/server/whitelist?uuid=069a79f4-44e9-4726-a5be-fca90e38aaf5
http-examples.sh
# Ping connection
noxae http ping

# Raw GET request
noxae http get /v1/server

# Raw POST execution
noxae http post /v1/chat/broadcast '{"message":"Hello from raw HTTP!"}'

One-Shot Execution

You can execute any SDK method directly from your terminal or bash script using the "noxae <resource> <action> [...args]" syntax:

Terminal
# 1. List online players
noxae players list

# 2. Deterministic cross-server identity & local join status
noxae identity get NoxlyDev

# 3. Global chat broadcast with Minecraft formatting codes
noxae server broadcast "&a[Server] Welcome to NoxAeApi!"

# 4. Execute console command
noxae server exec "whitelist add NoxlyDev"

# 5. Vault & Multi-Currency economy operations
noxae economy getBalance 069a79f4-44e9-4726-a5be-fca90e38aaf5
noxae economy pay 069a79f4-44e9-4726-a5be-fca90e38aaf5 500 "Quest reward"
noxae economy getCurrencyBalance gems 069a79f4-44e9-4726-a5be-fca90e38aaf5

# 6. LuckPerms RBAC permissions management
noxae luckperms setPlayerGroup 069a79f4-44e9-4726-a5be-fca90e38aaf5 vip
noxae luckperms checkPlayerPermission 069a79f4-44e9-4726-a5be-fca90e38aaf5 essentials.fly

# 7. Leaderboards & Player RPG skills (mcMMO / AuraSkills)
noxae leaderboards getTop mcmmo-power 10
noxae skills getMcmmoSkills 069a79f4-44e9-4726-a5be-fca90e38aaf5

# 8. World time, weather & backups
noxae worlds setTime 3fa85f64-5717-4562-b3fc-2c963f66afa6 1000
noxae worlds setWeather 3fa85f64-5717-4562-b3fc-2c963f66afa6 CLEAR
noxae worlds download 3fa85f64-5717-4562-b3fc-2c963f66afa6 --out backup.zip

# 9. Raw REST HTTP client
noxae http get /v1/server
noxae http post /v1/chat/broadcast '{"message":"Broadcast from raw CLI"}'

Proxy Node Targeting

When connected to a NoxAeApi-Velocity network hub profile (flagged as a hub during /connect), you can prefix commands with "@<nodeId>" to dispatch directly to that backend server:

Proxy Commands
# 1. Target proxy-wide network hub data
noxae network statusAll
noxae network players
noxae network findPlayer 069a79f4-44e9-4726-a5be-fca90e38aaf5
noxae network broadcast "Proxy-wide maintenance in 10 minutes."

# 2. Target a specific backend server through the Velocity proxy hub (@<nodeId>)
noxae @survival server exec "say Hello survivalists!"
noxae @survival players list
noxae @skyblock economy pay 069a79f4-44e9-4726-a5be-fca90e38aaf5 1000

JSON Output & Scripting

Pass the "--json" flag to bypass formatted terminal tables and output raw JSON, perfect for CI/CD pipelines, cron jobs, or piping to "jq":

Scripting & jq
# Force raw JSON output using the --json flag
noxae --json players list

# Pipe directly into jq for bash scripting and automation
noxae --json players list | jq -r '.[].name'

# Check server TPS and memory metrics via jq
noxae --json server info | jq '{tps: .tps, freeMemory: .freeMemory}'

# Inside the interactive REPL, prefix any command with /json:
# (noxae) > /json players list

Updating CLI & Versioning

The NoxAe CLI includes an automated version checker that runs in the background and provides an in-REPL command to verify the latest npm releases on demand.

Automatic Background Check

Checks the npm registry every 6 hours (cached in ~/.noxaeapi-cli/update-cache.json) and displays a terminal startup banner when an update is available.

In-REPL /update Command

Type "/update" inside the REPL prompt to force a real-time registry check and print upgrade commands.

Verify Current Version

Run "noxae --version" from shell or type "/about" inside REPL to inspect active version and connection info.

Global Upgrade Commands:

Upgrade CLI
# Upgrade via npm
npm install -g @wumx-labs/noxaeapi-cli@latest

# Upgrade via pnpm
pnpm add -g @wumx-labs/noxaeapi-cli@latest

# Upgrade via bun
bun add -g @wumx-labs/noxaeapi-cli@latest

Config Storage & Multi-Profiles

All server profiles are persisted locally in a single JSON configuration file. You can manage them via CLI commands (/edit, /rename, /remove) or edit the file directly:

Configuration File Path:
  • Windows: %USERPROFILE%\.noxaeapi-cli\config.json
  • Linux / macOS: ~/.noxaeapi-cli/config.json
~/.noxaeapi-cli/config.json
{
  "current": "survival",
  "profiles": {
    "survival": {
      "baseUrl": "http://10.0.0.2:4567",
      "apiKey": "my-secret-key",
      "hub": false
    },
    "velocity-hub": {
      "baseUrl": "http://10.0.0.2:9090",
      "apiKey": "proxy-hub-key",
      "hub": true
    }
  }
}

Environment Variables

If no active profile is stored in config.json, the CLI falls back to the following environment variables:

.env
# Backend Server connection (Dummy Example)
export NOXAEAPI_BASE_URL="http://10.0.0.2:4567"
export NOXAEAPI_KEY="your-secret-api-key"

# Standalone Velocity Hub connection (optional)
export NOXAEAPI_HUB_BASE_URL="http://10.0.0.2:9090"
export NOXAEAPI_HUB_KEY="your-hub-api-key"