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.

Flag	Description
`-b`, `--background`, `--bg`	Start in the background (no terminal window needed)

Interactive mode (default) shows a live console you can type into — slash commands, single-key hotkeys, and raw DCC-EX commands (<1> for track power on) all work directly at the prompt, no need to open a second terminal. Type exit or press Ctrl+C to stop.

Background mode (deja start -b) runs the server silently. Use deja status to check on it and deja stop to shut it down.

Interactive Console Commands

Command	Aliases	Does
`/start`		Start the server (if not already running)
`/stop`		Stop the server and exit
`/restart`	`/r`	Restart the server
`/quit`	`/q`, `/exit`	Exit the console (server keeps running)
`/menu`	`/m`	Open the interactive menu
`/settings`		Open the settings panel — also where the remote access tunnel is toggled
`/dcc-ref`	`/dcc`, `/ref`	Show the DCC-EX command quick reference
`/logs`	`/l`	Return to the log view
`/devices`	`/d`, `/io`	Show the device panel and manage connections
`/connect <name>`	`/c`	Connect a device by name
`/disconnect <name>`	`/dc`	Disconnect a device by name
`/deploy`	`/dep`, `/flash`	Launch the firmware deploy wizard
`/help`	`/h`, `/?`	Show all available commands
`/filter`	`/f`	Cycle log filter (all → error → warn)
`/export`	`/e`	Export logs to a file

Every slash command also works as plain text — typing stop does the same as /stop.

When the input line is empty, single-key hotkeys work without pressing Enter: s stop, r restart, m menu, ? help, e export logs, l cycle log filter, Esc clear input or open menu, Tab autocomplete a slash command, Ctrl+C exit. Prefix a raw DCC-EX command with * (e.g. * <1>) to send it straight to the track.

`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 status`

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

Server state — running or stopped, version number, process ID
Account — your User ID and Layout ID
Connections — WebSocket port, MQTT status, Firebase Cloud status, detected serial ports
Remote monitoring — tunnel status and URL (if applicable)
Apps — links to Throttle, Cloud, and Monitor
Log file — path and size of the current log file

`deja logs`

View recent server log output.

Flag	Description
`-f`, `--follow`	Follow logs in real time (like a live feed). Press Ctrl+C to stop.
`-n LINES`, `--lines LINES`	Number of lines to show (default: 50)

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. If the server is running, it will be stopped during the update 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 Cloud account and layout. Run it when setting up a new server or re-linking to a different layout.

Running it opens your browser to a connect page that automatically mints a token bound to your account and layout — no copying or pasting required. Approve it in the browser and the CLI picks up the result.

Once linked, your account ID, layout ID, and secure credentials are written to ~/.deja/config.json. The layout the token is bound to becomes the layout this server serves.

`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), port (default 12090), mDNS service name
MQTT — enable/disable, broker URL, port
DEJA Cloud — enable/disable real-time sync
Cloudflare Tunnel — set your tunnel token (stored in ~/.deja/.env)

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 withrottle.port          # show one value
deja config set withrottle.port 12091    # change one value
deja config set mqtt.enabled true
deja config set tunnel.token <token>

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.

Tunnel Commands

Remote monitoring lets you reach your Monitor dashboard from outside your home network. It requires an Engineer or Conductor plan and the cloudflared tool. See Remote Monitoring for setup details.

`deja tunnel start`

Start a secure Cloudflare tunnel. Once connected, the command prints a URL you can open from anywhere.

`deja tunnel stop`

Stop a running tunnel.

`deja tunnel status`

Check whether the tunnel is running and show the current URL.

`deja tunnel logs`

View recent tunnel log output. Optionally pass a number to show more lines (e.g., deja tunnel logs 100).

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 Cloud device configuration to a connected board and (optionally) flash its firmware. Handles deja-arduino, deja-esp32, deja-esp32-wifi, and deja-mqtt devices. See Deploy to Devices for details.

Understanding Console Output

When the server runs in the foreground (deja start), you'll see a live stream of status messages. Each line follows this format:

[DEJA.JS] > ▶ start      Running [MAIN]

The prefix [DEJA.JS] › appears on every line, followed by an icon, a level name, and the message. Here's what each level means:

Message Types

[DEJA.JS] > ▶ start      A service or process is launching
[DEJA.JS] > ✔ success    Something connected or completed successfully
[DEJA.JS] > ✔ complete   A task finished (port opened, layout loaded)
[DEJA.JS] > ● note       Configuration detail or status update
[DEJA.JS] > ℹ info       Informational — no action needed
[DEJA.JS] > ★ star       A DCC command was sent to the track
[DEJA.JS] > … await      Waiting for something (serial write, reconnect)
[DEJA.JS] > ⚠ warn       Non-critical issue — server keeps running
[DEJA.JS] > ✖ error      Something went wrong
[DEJA.JS] > ✖ fatal      Critical error — server may need a restart

Startup Sequence

When the server starts, you'll see messages like these in order:

[DEJA.JS] > ▶ start      Running [MAIN]
[DEJA.JS] > ✔ success    Subscription valid: trialing (engineer)
[DEJA.JS] > ℹ info       Server config loaded { layoutId: 'my-layout', mqtt: true, ws: true, cloud: true }
[DEJA.JS] > ● note       MQTT ON (mqtt://localhost:1883)
[DEJA.JS] > ● note       WebSocket ON (port 8082)
[DEJA.JS] > ● note       DEJA Cloud ON
[DEJA.JS] > ▶ start      Connecting to DejaCloud my-layout
[DEJA.JS] > ✔ success    [CLEANUP] Cleared stale entries from dccCommands/my-layout
[DEJA.JS] > ▶ start      Throttles listening for loco changes on layout: my-layout
[DEJA.JS] > ▶ start      Load layout my-layout
[DEJA.JS] > ✔ complete   Layout loaded my-layout
[DEJA.JS] > ✔ success    [FIREBASE] RTDB connection established
[DEJA.JS] > ✔ success    Connected to DejaCloud my-layout
[DEJA.JS] > ▶ start      DEJA Cloud connected
[DEJA.JS] > ▶ start      MQTT initialized
[DEJA.JS] > ▶ start      WebSocket server started 8082 DEJA.js 192.168.86.23
[DEJA.JS] > ▶ start      DEJA.js Server is running!

DCC Command Messages

When you control trains, turnouts, or effects, you'll see ★ star messages confirming each command sent to the track:

[DEJA.JS] > ★ star       Throttle  3 50 1        ← Loco 3, speed 50, forward
[DEJA.JS] > ★ star       Turnout   1 1            ← Turnout 1 thrown
[DEJA.JS] > ★ star       Function  3 0 1          ← Loco 3, headlight on
[DEJA.JS] > ★ star       Power     1              ← Track power on
[DEJA.JS] > ★ star       Output    {pin: 5, ...}  ← Output pin toggled

Shutdown Sequence

When you stop the server (Ctrl+C or /stop), you'll see an orderly shutdown:

[DEJA.JS] > ▶ start      [SHUTDOWN] Graceful shutdown initiated...
[DEJA.JS] > ℹ info       [SHUTDOWN] Closing WebSocket server and all client connections...
[DEJA.JS] > ✔ success    [SHUTDOWN] WebSocket server closed
[DEJA.JS] > ℹ info       [SHUTDOWN] Disconnecting from DEJA Cloud (Firebase listeners)...
[DEJA.JS] > ✔ success    [SHUTDOWN] DEJA Cloud disconnected
[DEJA.JS] > ℹ info       [SHUTDOWN] Disconnecting MQTT client...
[DEJA.JS] > ✔ success    [SHUTDOWN] MQTT client disconnected
[DEJA.JS] > ℹ info       [SHUTDOWN] Stopping sound playback...
[DEJA.JS] > ✔ success    [SHUTDOWN] Sound playback stopped
[DEJA.JS] > ℹ info       [SHUTDOWN] Disconnecting all serial ports...
[DEJA.JS] > ✔ success    [SHUTDOWN] Serial ports disconnected
[DEJA.JS] > ✔ success    [SHUTDOWN] DEJA.js Server shutdown complete

Common Error Messages

[DEJA.JS] > ✖ error      Subscription inactive (status: canceled)

Your subscription has expired — visit dejajs.com to renew.

[DEJA.JS] > ✖ error      [WS] Port 8082 is already in use

Another server instance is running — run deja stop first.

[DEJA.JS] > ✖ error      [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.

[DEJA.JS] > ✖ error      [MQTT] Broker not available

MQTT broker isn't running — start Mosquitto, or set ENABLE_MQTT=false in ~/.deja/.env.

[DEJA.JS] > ⚠ warn       Could not reach Firebase for subscription check

Can't connect to the cloud — check your internet connection and credentials in ~/.deja/.env.

For more solutions, see Troubleshooting.