CLI Reference

The deja CLI is how you manage your DEJA Server from the terminal. It's installed automatically when you run the installer.

Server Commands

deja start

Start the server. By default, the server runs in the foreground with an interactive display.

Interactive mode (default — just run deja) opens a live console. The server log scrolls by in your terminal like any other output, so your mouse wheel, trackpad, Cmd+F and copy/paste all work. A small status bar sits at the bottom with DejaBot, the prompt and a hint line.

Background mode (deja start -b) runs the server silently. Use deja status to check on it and deja stop to shut it down. The server also runs in the background automatically when stdin isn't a terminal (for example, when started from a script or cron job) — you don't need to pass -b explicitly in that case.

Console commands

There's no menu and no single-key hotkeys — type a command and press ↵. Nothing runs until you press ↵, so you can't trigger anything by accident while typing — and a paste never runs anything either: pasted lines land in the prompt joined by spaces, ready to check before you press ↵.

Commands by group (help lists them in the console too):

Full names and multi-letter aliases work with or without a leading / (status or /status). One-letter aliases need the slash (/r, /q, /d): a bare r + ↵ just asks "did you mean /r?".

Sending DCC-EX commands

Type < to start a DCC-EX command. The prompt suggests the most useful ones (power on, status, throttle, function, emergency stop); keep typing the command letter to narrow the list, and Tab (or ↑/↓ then ↵) fills it in — a command that still needs values is only filled in, never sent half-typed. While you type the values, the hint row shows what comes next, e.g. <t cab ⟨speed⟩ dir> · speed -1–126 …, then ✓ ↵ sends <t 3 50 1> once the command is complete. Command letters are case-sensitive (<t> drives a loco, <T> lists turnouts).

The hint row turns yellow with ⚠ when something looks wrong — a value out of range, a command that isn't in the console's list, or a command that would delete a turnout, output or sensor definition (such as <T 5> with no state); it also follows the suggestion you highlight with ↑/↓, so it always describes what ↵ will do. It never blocks: ↵ always sends exactly what you typed (or the highlighted suggestion) to the EX-CommandStation. Type dcc for the full list, or see the official DCC-EX command reference.

Standby

If no activity reaches the server for standby.timeout minutes (default 30), a 60-second warning appears in the console: "💤 Standby in Ns — press Enter to stay awake". Pressing Enter or Esc dismisses the warning and resets the idle timer.

If the warning runs out, the server goes into standby: it sends an emergency stop and cuts track power to the EX-CommandStation, zeros throttle speeds, pauses DEJA Cloud sync, and slows its status heartbeat to every 10 minutes. Commands that arrive while in standby are dropped.

Wake it back up with resume (or continue) in the console, or deja resume if the server is running in the background (deja start -b) — it wakes within 5 seconds. Track power stays off after resume; turn it on from a throttle when you're ready.

Activity means any loco, turnout, effect, or signal command — from DEJA apps, WiThrottle apps, or throttles connected directly to the EX-CommandStation (its own WiFi, handhelds), which the server sees through the EX-CommandStation's loco updates. Status polls (ping/status requests from apps) don't count, so a polling app can't keep the server awake indefinitely.

See standby.timeout to change the idle timeout, and Troubleshooting if standby triggers unexpectedly from a command loop.

deja stop

Stop a running server. The server shuts down gracefully — it closes connections, disconnects from Firebase, and releases the serial port before exiting.

deja restart

Stop the server and start it again. Accepts the same flags as deja start (e.g., deja restart -b to restart in background mode).

deja resume

☀️ Wake a background server (deja start -b) from standby — wakes within 5s. Track power stays off after resume; turn it back on from a throttle when you're ready.

deja resume

For a foreground server, type resume or continue in the console instead.

deja status

Show the current state of your server and connections. The output includes:

• Server state — running or stopped, version number, process ID
• Standby — while the server is in standby, a line like 💤 Standby <reason> since <time> — run: deja resume
• Account — your User ID and Layout ID
• Connections — WebSocket port, MQTT status, Firebase Cloud status, detected serial ports
• Apps — links to Throttle and its Devices page
• Log file — path and size of the current log file

deja logs

View recent server log output.

Examples:

deja logs           # Show last 50 lines
deja logs -f        # Follow logs in real time
deja logs -n 100    # Show last 100 lines
deja logs -f -n 20  # Follow, starting from last 20 lines

deja update

Check for and install the latest version of the DEJA Server. The new server and CLI are downloaded and checked against the release's SHA-256 checksums first. A download that fails the check is never installed, and your running server is left alone. If the server is running, it is stopped only for the install and restarted automatically afterward.

The update preserves your configuration — your account, layout, and environment settings stay exactly as they were.

deja login

Connect this server to your DEJA account and layout. Run it when setting up a new server or re-linking to a different layout.

The CLI shows a short one-time code (like MKQP-37XR) and opens throttle.dejadcc.com in your browser. Sign in if you aren't already, check that the code on the page matches your terminal, pick the layout to connect, and click Authorize — the CLI finishes on its own. The code works from any device's browser, so this also works on a headless Raspberry Pi over SSH: open the printed link on your phone or laptop.

Once linked, your account ID, layout ID, and secure credentials are written to ~/.deja/config.json, and you stay logged in — the server refreshes its own credentials automatically. The layout you authorize becomes the layout this server serves.

Options:

deja login                 # opens the browser for you
deja login --no-browser    # print the link instead of opening a browser

deja config

Configure the server's subsystems interactively — no hand-editing of dotfiles required. The walkthrough shows every setting with its current value in brackets; press Enter to keep a value or type a new one:

• WebSocket — enable/disable, port (default 8082), server name
• WiThrottle — enable/disable (on by default), mDNS service name (always runs on port 12090, the standard WiThrottle port)
• MQTT — enable/disable, broker URL, port
• DEJA Cloud — enable/disable real-time sync
• Log level — console detail (info, verbose, or debug — the log file always captures everything)
• Standby — minutes of inactivity before standby (default 30, 0 = never idle-standby; loop protection is always on)

Settings are saved to ~/.deja/config.json, and the command offers to restart the server so changes take effect immediately.

For scripting or one-off changes, use the subcommands:

deja config get                          # show all settings
deja config get log.level                # show one value
deja config set log.level verbose        # change one value
deja config set mqtt.enabled true

Account and layout linking are protected — those belong to deja login.

deja --version

Print the installed server version. deja -v works too.

deja help

Show the full list of available commands.

Remote Monitoring

Remote monitoring works through DEJA Cloud — no commands to run. See Remote Monitoring.

Device Commands

These commands manage the IO hardware devices (Arduino, ESP32, Pico W) registered to your layout. See IO Devices for the full workflow.

deja devices

List the devices registered to your layout in DEJA Cloud, along with their type and connection details.

deja deploy

Launch the interactive deploy wizard to push your device configuration to a connected board and (optionally) flash its firmware. Handles deja-arduino, deja-esp32, deja-esp32-wifi, and deja-mqtt devices, plus the EX-CSB1 (as an EX-CommandStation or a booster). See Deploy to Devices for details.

Works on installed copies. The first run asks before downloading Arduino tools into ~/.deja/tools (--yes skips the question). Supported today: Arduino Mega, ESP32 (USB), ESP32 (WiFi), Pico W and EX-CSB1 (EX-CommandStation or booster). A Mega EX-CommandStation uses DCC-EX's EX-Installer. Exit codes: 0 ok, 1 error, 2 cancelled.

Understanding Console Output

When the server runs in the foreground (deja start), the console shows a short startup summary, then one line per event. Each event line follows this format:

HH:MM:SS  TAG        device   glyph  message
14:12:03  DCC        dccex    →  <t 77 50 1>  throttle 77

• Time — when the line was logged.
• Tag — where it came from: DCC (EX-CommandStation traffic), IO (DEJA IO boards), WLED, or a subsystem such as SERIAL, MQTT, WS, WITHROTTLE or SHUTDOWN. Blank when the message has no tag.
• Device — the device ID for device traffic, colour-coded per device; blank otherwise.
• Glyph — only four are used: → a line the server sent to a device, ← a line the device sent back, ⚠ a warning, ✖ an error.
• Message — the text itself. DCC-EX commands get a dim note on what they do (e.g. throttle 77), coloured by kind.

Identical lines that repeat within 30 seconds collapse into one, followed by a dim ×12 in 8s-style count. An error whose cause has already been shown is suppressed, and a summary of suppressed causes prints at shutdown.

Startup

At the default log level (info), startup is a few milestone lines, roughly:

🚂 DEJA Server v1.16.0 — my-layout
✓ Cloud connected
✓ dccex connected /dev/ttyACM0
✓ WiThrottle :12090
✅ DEJA Server running

After that, the console shows device traffic, warnings and errors. Set log.level to verbose (or debug) with deja config to see every status message as well; the log file (~/.deja/logs/server.log) always captures everything.

Device traffic

When you drive trains or throw turnouts, each command the server sends — and each reply — is one line:

14:12:03  DCC        dccex    →  <t 77 50 1>  throttle 77
14:12:20  IO         yard-esp →  {"action":"pin","payload":{"pin":5,"state":true}}

Shutdown

When you stop the server (stop, or Ctrl+C twice — a single Ctrl+C only warns, a second within 2 seconds stops), it shuts down in order — closing the WebSocket and WiThrottle servers, disconnecting from DEJA Cloud and MQTT, and releasing the serial ports. Run at verbose to see each step as a SHUTDOWN line:

14:13:40  SHUTDOWN               Graceful shutdown initiated...
14:13:40  SHUTDOWN               WebSocket server closed

Common Error Messages

14:12:01  CONFIG              ✖  <what's wrong with ~/.deja/config.json>

The server couldn't read its config (missing or corrupt) and exited — run deja login to relink this machine to your layout.

14:12:09  WS                  ✖  Port 8082 is already in use — is another server instance running?

Another server instance is running — run deja stop first.

14:12:11  SERIAL              ✖  Error opening port: Permission denied

Can't access the USB serial port — check the cable, or run sudo usermod -a -G dialout $USER on Linux.

14:12:15  MQTT                ✖  Broker not available. Will retry with exponential backoff.

The server is configured to use an external MQTT broker that isn't reachable — see MQTT Broker Not Available in Troubleshooting, or set ENABLE_MQTT=false in ~/.deja/.env.

For more solutions, see Troubleshooting.