Skip to content

CLI.md

Latest commit

 

History

History
451 lines (306 loc) · 10.7 KB

CLI.md

File metadata and controls

451 lines (306 loc) · 10.7 KB
Raw

CLI Reference

Complete reference for RunDock command-line actions, flags, and options.

Global Options

These flags apply to every command:

alter [OPTIONS] <COMMAND>
Flag Env Var Default Description
--host <HOST> ALTER_HOST 127.0.0.1 Daemon host address
--port <PORT> ALTER_PORT 2999 Daemon port
--json — false Output raw JSON (useful for scripting)
--no-color — false Suppress ANSI color codes

Commands

alter start

Start one or more processes. Accepts either a command to run or a path to an ecosystem config file.

alter start <SCRIPT> [OPTIONS] [-- <ARGS>...]

Arguments:

Argument Description
<SCRIPT> Command to run (e.g. python, node, go), or path to .toml / .json ecosystem config
-- <ARGS>... Arguments to pass to the process (everything after --)

Options:

Flag Short Default Description
--name <NAME> -n derived from script Display name for the process
--cwd <PATH> current dir Working directory to run the process in
--env <KEY=VAL> -e — Environment variable (repeatable)
--autorestart true Auto-restart on non-zero exit code
--no-autorestart — Disable auto-restart
--max-restarts <N> 10 Maximum number of restart attempts
--restart-delay-ms <MS> 1000 Base delay before restart (exponential backoff applied)
--watch -w false Enable watch mode (restart on file changes)
--watch-paths <PATHS>... [] Directories to watch (used with --watch)
--cron <EXPR> — Run on a cron schedule; the process sleeps between runs

Examples:

# Basic process
alter start python -- -m http.server 8080

# Named process (all RunDock options must appear before `--`)
alter start node --name api -- server.js

# With working directory and env vars
alter start python --name django --cwd C:\projects\api -e DJANGO_ENV=production -- manage.py runserver

# Enable auto-restart with custom limits
alter start node --name worker --max-restarts 5 --restart-delay-ms 2000 -- worker.js

# Watch mode (restart on source file changes)
alter start go --name backend --watch --watch-paths src/ -- run main.go

# Scheduled process
alter start python --name hourly-report --cron "0 0 * * * *" -- report.py

# Load ecosystem config
alter start alter.config.toml
alter start alter.config.json

Notes:

  • If <SCRIPT> ends in .toml or .json, it is treated as an ecosystem config file and all apps inside are started
  • On Windows, non-.exe scripts are automatically wrapped in cmd /C to resolve .cmd batch files (e.g. npm, yarn, npx)
  • Processes run without a console window — output is captured to log files and streamed to the dashboard

alter stop

Stop a running process.

alter stop <TARGET>
Argument Description
<TARGET> Process name, UUID, or all to stop every process

Examples:

alter stop api
alter stop 3f2a1b4c-...    # by UUID
alter stop all              # stop every running process

alter restart

Stop and immediately restart a process.

alter restart <TARGET>
Argument Description
<TARGET> Process name, UUID, or all

Examples:

alter restart api
alter restart all

alter delete

Stop a process and remove it from the process list entirely.

alter delete <TARGET>
Argument Description
<TARGET> Process name, UUID, or all

Examples:

alter delete old-worker
alter delete all            # removes every process

Note: Log files are NOT deleted. Use alter flush to clear logs.

alter list

Display all managed processes in a table.

alter list
alter ls      # alias
alter ps      # alias

Output columns:

Column Description
ID Short UUID prefix
Name Process display name
Status running, stopped, crashed, errored, watching, starting, stopping
PID System process ID (blank if not running)
Uptime How long the process has been running
Restarts Number of auto-restart attempts
Watch Whether watch mode is enabled
Last Run When the process was last started or stopped

Example:

ID        NAME       STATUS     PID    UPTIME    RESTARTS  WATCH  LAST RUN
a1b2c3d4  api        running    14820  2h 5m     0         no     2h ago
e5f6a7b8  worker     stopped    —      —         3         no     10m ago
c9d0e1f2  frontend   watching   8822   45m       0         yes    45m ago

alter describe

Show detailed information about a specific process.

alter describe <TARGET>

Output includes: name, UUID, status, PID, script, args, cwd, restarts, autorestart setting, max restarts, watch mode, namespace, created time, started time.

Example:

alter describe api

alter logs

View or stream log output for a process.

alter logs <TARGET> [OPTIONS]
Flag Short Default Description
--lines <N> -l 50 Number of lines to display
--follow -f false Stream logs in real time (Ctrl+C to stop)
--err false Show stderr instead of stdout

Examples:

# Last 50 lines of stdout
alter logs api

# Last 200 lines
alter logs api --lines 200

# Stream in real time
alter logs api --follow

# View stderr
alter logs api --err

# Combine
alter logs api --follow --err

alter flush

Delete log files for one or all processes.

alter flush [TARGET]
Argument Description
[TARGET] Process name, UUID, or all (default: all)

Examples:

alter flush api       # delete logs for "api"
alter flush all       # delete logs for every process
alter flush           # same as "all"

This only deletes log files on disk. The process itself is not affected.

alter reset

Reset the restart counter for a process to zero.

alter reset <TARGET>

Examples:

alter reset api

Useful after fixing a crash — prevents the process from hitting max_restarts prematurely.

alter save

Persist the current process list to disk.

alter save

Saves all processes (running and stopped) to %APPDATA%\alter-pm2\state.json (Windows) or ~/.alter-pm2/state.json (Linux/macOS).

The saved state records:

  • Process config (name, script, args, cwd, env, etc.)
  • Restart count
  • Last PID and immutable process-start identity for safe re-adoption
  • Whether a cron scheduler was active

State is also auto-saved after every process change (start, stop, restart, delete, edit).

alter resurrect

Restore the process list from the last saved state.

alter resurrect
  • A still-live PID is re-adopted only when its saved start identity matches
  • Missing or mismatched ordinary processes are registered as stopped and are never guessed-restarted
  • Previously active cron schedules are restored in sleeping/scheduled state

Typical usage (after reboot):

alter daemon start
alter resurrect

alter daemon

Manage the background daemon process.

alter daemon <ACTION>
Action Description
start [--port <P>] Start the daemon in the background
stop Stop the running daemon
status Check if the daemon is running
logs View the daemon's own log output

Examples:

# Start daemon on default port (2999)
alter daemon start

# Start on a custom port
alter daemon start --port 3100

# Check if it's running
alter daemon status

# View daemon internal logs
alter daemon logs

# Stop the daemon (saves state first)
alter daemon stop

How it works:

On Windows, the daemon starts as a completely hidden background process (no taskbar entry, no console window). It binds to 127.0.0.1:2999 and serves both the REST API and the web dashboard.

alter web

Open the web dashboard in the default browser.

alter web

Checks the strict RunDock health contract first. If the port is unused, it starts the daemon and waits up to 10 seconds before navigating to http://127.0.0.1:2999/. If port 2999 belongs to another or incompatible program, the command reports the conflict and never ends that process.

alter auth disable

Disable the web dashboard password without prompting for it. The CLI authenticates with its local master token, then clears the dashboard password, PIN, passkeys, auto-lock setting, and active browser sessions.

alter auth disable

Use passwordless mode only while the daemon remains bound to 127.0.0.1 or another loopback address. A new password can be configured later from Settings → Security.

alter startup

Generate instructions or commands to run the daemon automatically at system startup.

alter startup
alter unstartup

Windows: The installed rundock.exe desktop app enables current-user login startup by default and exposes the toggle in its tray menu. For CLI-only/source installs, alter startup still outputs a PowerShell command for an optional Scheduled Task; run that command in an elevated PowerShell prompt.

Linux: Outputs a systemd unit file template. Copy it to /etc/systemd/system/alter-daemon.service, then run sudo systemctl daemon-reload and sudo systemctl enable --now alter-daemon.service.

macOS: Shows instructions for adding the daemon start command to your shell profile.

alter unstartup removes the registered startup task.

Exit Codes

Code Meaning
0 Success
1 General error (daemon not running, process not found, etc.)

Environment Variables

Variable Default Description
ALTER_HOST 127.0.0.1 Daemon host (overrides --host)
ALTER_PORT 2999 Daemon port (overrides --port)

Tips

Target resolution: Most commands accept a process name, a full UUID, or a UUID prefix (first 8 characters). For bulk operations, use all.

Windows .cmd scripts: Tools like npm, yarn, npx, tsc, and nodemon are batch scripts on Windows. RunDock automatically wraps them in cmd /C, so you can use them directly:

alter start npm --name my-app -- run start
alter start npx --name dev-server -- nodemon index.js

JSON output for scripting:

alter list --json | ConvertFrom-Json
alter logs api --json