Admin CLI Reference

The galaxy-admin CLI provides command-line access to all server administration functions.

Installation

The CLI is distributed as the galaxy-admin Python package. It requires Python 3.10+.

pip install -e services/admin-cli

Configuration

Environment Variables

Variable	Default	Description
`GALAXY_API_URL`	`https://localhost:30002/api`	API gateway URL (direct port)
`GALAXY_ADMIN_USER`	—	Admin username (skips interactive prompt)
`GALAXY_ADMIN_PASSWORD`	—	Admin password (skips interactive prompt)

Note: The default URL uses port 30002 (local dev direct API access). For staging and Lima, use https://localhost:31002/api. Browser clients access the API through the web client’s reverse proxy (port 30000/31000) and do not need the direct port.

Authentication

The CLI caches JWT tokens at ~/.galaxy/admin-token for 24 hours. Authentication is automatic — the CLI will prompt for credentials when needed.

Authentication priority:

Cached token (if valid and not expired)
Environment variables (GALAXY_ADMIN_USER / GALAXY_ADMIN_PASSWORD)
Interactive prompt

If a cached token expires, the CLI automatically re-authenticates using the next available method.

Commands

`galaxy-admin status`

View server status and metrics.

$ galaxy-admin status
Current Tick:  145230
Tick Rate:     1.0 Hz
Actual Rate:   1.0 Hz
Status:        RUNNING
Ticks Behind:  0

`galaxy-admin pause`

Pause tick processing. All connected clients are notified.

$ galaxy-admin pause
Game paused at tick 145230

`galaxy-admin resume`

Resume tick processing. All connected clients are notified.

$ galaxy-admin resume
Game resumed at tick 145230

`galaxy-admin tick-rate get`

Show the configured and actual tick rates.

$ galaxy-admin tick-rate get
Configured:  1.0 Hz
Actual:      1.0 Hz

`galaxy-admin tick-rate set RATE`

Set the tick rate in Hz.

Argument	Type	Range	Description
`RATE`	float	0.1–100.0	Target tick rate

$ galaxy-admin tick-rate set 2.5
Previous rate: 1.0 Hz
New rate:      2.5 Hz

`galaxy-admin snapshot create`

Create a snapshot of the current game state.

$ galaxy-admin snapshot create
Snapshot created: ID 15 at tick 145230

`galaxy-admin snapshot list`

List available snapshots (most recent 20).

$ galaxy-admin snapshot list
ID    Tick      Created
----  --------  -------------------
15    145230    2026-02-07 14:30:00
14    141600    2026-02-07 13:30:00
13    138000    2026-02-07 12:30:00

Total: 3 snapshots

`galaxy-admin snapshot restore SNAPSHOT_ID`

Restore game state from a snapshot. Current state is lost.

Argument	Type	Description
`SNAPSHOT_ID`	int	Snapshot ID to restore

Option	Description
`--yes, -y`	Skip confirmation prompt

$ galaxy-admin snapshot restore 14
WARNING: Current game state will be lost. Continue? [y/N]: y
Restored to tick 141600

$ galaxy-admin snapshot restore 14 --yes
Restored to tick 141600

`galaxy-admin players list`

List all player accounts.

$ galaxy-admin players list
Username    Status    Ship ID     Created
----------  --------  ----------  ----------
alice       Online    a1b2c3d4    2026-01-15
bob         Offline   e5f6g7h8    2026-01-20

Total: 2 players

`galaxy-admin reset`

Factory reset — delete ALL game data. This cannot be undone.

Option	Description
`--yes, -y`	Skip confirmation prompts

$ galaxy-admin reset
WARNING: This will delete ALL game data including players, ships, and snapshots.
Are you sure? [y/N]: y
Are you REALLY sure? This cannot be undone. [y/N]: y
Game reset complete.

$ galaxy-admin reset --yes
Game reset complete.

`galaxy-admin auth login`

Authenticate and cache credentials for 24 hours.

$ galaxy-admin auth login
Username: admin
Password: ********
Authenticated successfully

# Or with environment variables:
$ GALAXY_ADMIN_USER=admin GALAXY_ADMIN_PASSWORD=secret galaxy-admin auth login
Authenticated successfully

`galaxy-admin auth logout`

Clear cached credentials.

$ galaxy-admin auth logout
Logged out (cached token removed)

Common Workflows

Pre-Maintenance

Before restarting stateful services:

# Save current state
galaxy-admin snapshot create

# Pause the game
galaxy-admin pause

# ... perform maintenance ...

# Resume after maintenance
galaxy-admin resume

Monitoring Server Health

# Quick status check
galaxy-admin status

# Check if server is keeping up
galaxy-admin tick-rate get

Disaster Recovery

# List available snapshots
galaxy-admin snapshot list

# Restore to a known good state
galaxy-admin snapshot restore <id>

Scripted Administration

Use environment variables for non-interactive operation:

export GALAXY_API_URL=https://galaxy.example.com/api
export GALAXY_ADMIN_USER=admin
export GALAXY_ADMIN_PASSWORD=secret

galaxy-admin status
galaxy-admin snapshot create

Error Handling

The CLI displays errors in red and exits with code 1:

Authentication errors: Invalid credentials or expired tokens. Run galaxy-admin auth login to re-authenticate.
API errors: Server unreachable or returned an error. Check the API URL and server status.
Connection errors: Cannot reach the server. Verify GALAXY_API_URL is correct and the server is running.