The Creature CLI is my Swiss Army knife for working with the Creature Server. It’s a command-line tool built in Swift as part of the same package as the Creature Console, so it shares all the same networking and model code. The code is on GitHub in the Common package.
I use it mostly for debugging and testing, but it’s also handy for quick one-off tasks where I don’t want to open the full console. Need to play an animation, check server metrics, or monitor WebSocket traffic? The CLI is faster than clicking through a GUI.
Commands
The CLI is organized into command groups, each focused on a different part of the system.
animations
List, play, rename, and delete animations on the server. You can also trigger lip sync generation and inspect ad-hoc animations. The play and interrupt commands are great for testing — I can fire off an animation from the terminal without touching the Console.
creatures
List creatures, view their details, and toggle idle loops on and off. The validate command is particularly useful — it reads a creature definition JSON file and checks that all the referenced animations actually exist on the server. Catches broken references before they cause problems at runtime.
sounds
Manage sound files on the server — list them, play them, download them, and generate lip sync data. The generate-lipsync-from-file command can take a local WAV file, upload it, and output the lip sync JSON, which is handy for offline work.
voice
Interface with ElevenLabs through the server. List available voices, check subscription status, and generate speech. The ad-hoc subcommands (play, prepare, trigger) do the same thing as the Console’s ad-hoc animation feature but from the command line — type some text, and a creature says it.
playlists
Start and stop playlists on a universe. Simple but useful when I want to kick off a playlist without opening the Console.
websocket
This is where the debugging really shines. The monitor command connects to the server’s WebSocket and displays all the messages flowing through — sensor data, animation events, status updates, everything. You can filter by message type and output as raw JSON. It’s like tcpdump for the creature network.
There’s also stream-test for sending fake streaming frames to a creature, and inject for pushing test messages into the server. Both are invaluable when I’m working on new features and need to simulate traffic without having a physical creature connected.
metrics
Pulls server performance counters — how many frames have been processed, events scheduled, DMX packets sent, and so on. Quick way to sanity-check that the server is humming along.
network
The sacn-listen command exposes a TCP port that streams sACN frame data, which lets the Console visualize what’s being sent over the network even when it’s not on the same machine as the server. This was really helpful when I was debugging E1.31 issues from my laptop while the server was running on another machine.
debug
Cache invalidation commands for when things get stale — animations, creatures, playlists, and sounds each have their own cache that can be flushed independently. Also has a test command for simulating playlist update messages.
Distribution
The CLI is packaged as a Debian package and distributed to all of my Linux machines, so it’s always available wherever I need it. I also keep the macOS build on my Macs. Having the CLI a quick creature-cli away on every machine in the workshop makes it easy to poke at the server from wherever I happen to be.
Usage
For development, you can build and run it from the Swift package:
cd Common && swift run creature-cliIt connects to the Creature Server over the same RESTful API and WebSocket that the Console uses. You can point it at any server with --host and --port, or use --proxy-host and --proxy-api-key to go through the external proxy.
It also supports bash completions — run ./create_completions.sh to generate them.