CLI reference

Every runwisp command, its arguments, and its flags. Each command also prints its own --help. Output is plain text when it isn’t a terminal or when NO_COLOR is set.

Global options

These work on every command. A flag beats its environment variable.

Flag	Default	Description
-c, --config	./runwisp.toml	Config file. Env: RUNWISP_CONFIG.
--data	./.runwisp	State directory: SQLite database, run logs, socket. Env: RUNWISP_DATA.
--socket	<data>/runwisp.sock	Control socket path. Env: RUNWISP_SOCKET.
--host	127.0.0.1	HTTP bind address; 0.0.0.0 for every interface. Env: RUNWISP_HOST.
-p, --port	9477	HTTP port for the Web UI and REST API. Env: RUNWISP_PORT.
--log-level	info	debug, info, warn, error. Env: RUNWISP_LOG_LEVEL.
--log-format	auto	auto, text, json. See Daemon log. Env: RUNWISP_LOG_FORMAT.
-v, --version		Print the RunWisp version and exit.

As root, --config defaults to /etc/runwisp/runwisp.toml and --data to /var/lib/runwisp, so sudo runwisp reload finds a daemon that root started.

To move the data directory, stop the daemon and move the directory.

Environment variables

Besides the RUNWISP_* twins of the global options above:

Variable	Description
RUNWISP_PASSWORD	The Web UI and REST API password, kept in memory only. Unset: a new one every boot. See Authentication.
RUNWISP_AUTH	off disables authentication. Can’t be combined with RUNWISP_PASSWORD. See Authentication.
RUNWISP_URL	Remote daemon URL for run, logs, start, stop, restart, and tui, same as --url.
RUNWISP_TLS	Overrides [daemon] tls (auto or off).
RUNWISP_TRUSTED_PROXIES	Comma-separated CIDRs. Overrides [daemon] trusted_proxies.
RUNWISP_STATION_TOKEN	Token for runwisp station.
RUNWISP_STATION_URL	Control-plane URL for runwisp station.
RUNWISP_DEBUG_ADDR	Loopback address (like 127.0.0.1:6060) for Go pprof profiles. Non-loopback addresses are refused.

Control socket

The daemon listens on a Unix socket, <data>/runwisp.sock by default. The CLI and TUI use it without a password; access is limited by file permissions (0700 data directory, 0600 socket) and a peer-credential check.

Move it with --socket when the data directory is on a mount that rejects chmod (Docker Desktop, some network filesystems). The daemon and CLI must use the same path.

Starting and attaching

runwisp

runwisp

Opens the TUI against the daemon that owns the data directory. If none is running, it starts one in the background first. With no runwisp.toml, it offers to create a starter file.

If another RunWisp daemon already holds the port, it offers to connect to that one or to stop it and start here.

runwisp daemon

runwisp daemon

Starts the daemon in the foreground with no TUI. Use it under Docker, systemd, or any init system. Exits non-zero if the config is missing, instead of prompting.

runwisp tui

runwisp tui
runwisp tui --url https://runwisp.example.com

Attaches a TUI to a running daemon.

Flag	Description
--url	Connect over HTTP instead of the local socket. Reads the password from RUNWISP_PASSWORD or prompts once, then caches the session.

Inspecting

runwisp validate

runwisp validate
runwisp validate --json

Loads and checks runwisp.toml exactly like daemon startup, then prints a summary (task and service counts, the timezone) and any warnings. Starts nothing. Exits non-zero on an invalid config.

Flag	Description
--json	Print one JSON document instead of the summary.

Parse errors in JSON carry the exact location:

{
    "schemaVersion": 1,
    "valid": false,
    "configPath": "runwisp.toml",
    "tasks": 0,
    "services": 0,
    "warnings": [],
    "errors": [
        {
            "message": "unknown key \"schedule\" at line 4:1",
            "key": "tasks.backup.schedule",
            "line": 4,
            "column": 1
        }
    ]
}

runwisp list

runwisp list
runwisp list --json

Prints every configured task and service with its schedule. Reads only runwisp.toml; no daemon needed.

Flag	Description
--json	Print one JSON document instead of the table.

In JSON, a task not defined in your own file carries "source": "staged" (from import --write) or "cron" (from include_cron), plus "sourceFile".

runwisp status

runwisp status
runwisp status --json

Checks that the daemon is up, prints a short summary, and warns when runwisp.toml changed since the daemon loaded it. Exits non-zero if the daemon isn’t running.

Flag	Description
--json	Print daemon health plus every task and its last run (exit code, timing, failed, missed).

For “will the daemon start on boot?”, use service status.

JSON output

validate, list, status, and run accept --json. Every document has a schemaVersion; within one version, fields are only ever added. A failure still exits non-zero and still prints JSON, with an error or errors field.

logs --json streams instead: one JSON object per line, each with a type.

Running tasks

runwisp run

runwisp run <task>
runwisp run backup --param source=/data --param dest=/mnt/backup
runwisp run deploy --url https://runwisp.example.com

Runs a task, streams its output, and exits with its exit code. If the run fails but the process exited 0 (for example a failures pattern matched, or a timeout), the exit code is 1.

Without --url, it sends the run to the local daemon if one is running, otherwise it runs the task inside the CLI process.

Flag	Description
--param k=v	Set a parameter. Repeatable. Unset parameters use their default.
--daemon	Require a running daemon.
--standalone	Require no daemon; run in-process.
--json	Print the outcome as one JSON document on stdout; log lines go to stderr.
--url	Run on a remote daemon at this URL. Env: RUNWISP_URL. See Remote triggers.
--password	Password for --url. Env: RUNWISP_PASSWORD.
--detach	With --url, print the run ID and exit without following the output.

{
    "schemaVersion": 1,
    "task": "backup",
    "runId": "01JZZBACKUP0000000000000000",
    "status": "ended",
    "endReason": "succeeded",
    "exitCode": 0,
    "triggeredBy": "api",
    "startedAt": "2026-07-15T03:00:00Z",
    "endedAt": "2026-07-15T03:00:00.812Z",
    "durationMs": 812,
    "failed": false
}

runwisp logs

runwisp logs backup
runwisp logs backup -n 50 | grep -i error
runwisp logs -f web worker
runwisp logs -f '*'
runwisp logs 01J8Z3K9QK6VN8XG2R5F7T1C4M -n +20

Prints the output of tasks, services, and runs, then exits. Needs a running daemon.

A target is a task or service name, a run ID, or a quoted glob ('web*', or '*' for everything). A name shows its active runs, or its most recent finished run when none is active. A glob also matches tasks with manual_trigger = false.

Each run’s full log is printed. What the task wrote to stderr goes to stderr, so add 2>&1 to grep both. When the output mixes several tasks, or several instances of one service, each line starts with its source (web#2 | ...). How each finished run ended is printed to stderr.

The exit code says whether the logs could be shown. Use runwisp run to exit with a task’s exit code.

Flag	Description
-n, --lines	N prints the last N lines of each run, +N the first N. Default: all lines, or 10 with -f.
-f, --follow	Keep printing new output. With a name or glob, also follow new runs of the matching tasks until Ctrl+C. With run IDs, exit when they end.
--json	Print one JSON object per line on stdout, including stderr lines.
--url	Read from a remote daemon at this URL. Env: RUNWISP_URL.
--password	Password for --url. Env: RUNWISP_PASSWORD.

With --json, each log line is a line record, and a run that ends adds an end record with the same fields as run --json. ts is the line’s Unix time in milliseconds. A line too long to store in one piece is split, and every piece after the first has "continued":true.

{"type":"line","task":"backup","runId":"01JZZBACKUP0000000000000000","n":0,"ts":1767225600000,"stream":"stdout","text":"copying files"}
{"type":"end","schemaVersion":1,"task":"backup","runId":"01JZZBACKUP0000000000000000","status":"ended","endReason":"failed","exitCode":3,"triggeredBy":"cron","failed":true}

Controlling the daemon

runwisp reload

runwisp reload

Re-reads runwisp.toml and applies task and service changes without a restart. Same as SIGHUP. See Reload & restart.

runwisp start

runwisp start <target...>
runwisp start web worker
runwisp start 'batch-*'
runwisp start --attach web

Starts one or more tasks or services on a running daemon. A target is a task name, a service name, or a quoted shell glob matched against both ('*' for everything). For a service, this un-parks it (clearing a runwisp stop or a give-up) and fills empty instance slots; already-running instances are left alone. For a task, this triggers a run — unless one is already active or queued, in which case it’s a no-op. It never prints a run ID; use runwisp run --detach when you need one.

Flag	Description
--attach	Then follow the logs of the targets it acted on, like runwisp logs -f. Each run it starts is shown from its first line.
--url	Act on a remote daemon at this URL. Env: RUNWISP_URL.
--password	Password for --url. Env: RUNWISP_PASSWORD.

runwisp restart

runwisp restart
runwisp restart <target...>
runwisp restart web 'batch-*'
runwisp restart --attach 'web*'

With no argument, restarts the daemon. Needed for settings a reload can’t apply (see Reload & restart). Installed as a service, the restart goes through systemd or launchd.

With one or more targets (task names, service names, or quoted globs matched against both), restarts just those without touching the daemon. For a service, every instance is bounced — starting one that was stopped. For a task, the active run is cancelled, RunWisp waits for it to actually end, then triggers exactly one fresh run. A glob silently skips a target locked with manual_trigger = false; naming one directly is rejected.

Flag	Description
--local	Use the per-user unit when both a system and a per-user unit exist.
--attach	With targets, then follow the logs of the ones it acted on, like runwisp logs -f. Each run it starts is shown from its first line.
--url	Act on a remote daemon at this URL. Env: RUNWISP_URL.
--password	Password for --url. Env: RUNWISP_PASSWORD.

runwisp stop

runwisp stop
runwisp stop <target...>
runwisp stop web '*'
runwisp stop 01J8Z3K9QK6VN8XG2R5F7T1C4M

With no argument, stops the daemon. Running tasks get shutdown_timeout to finish. Installed as a service, the stop goes through systemd or launchd; the unit stays enabled.

With one or more targets — task names, service names, quoted globs matched against both, or a run ID — stops just those; the daemon keeps running. For a service, every live instance is cancelled and its slots stop refilling until a runwisp start/restart or a daemon restart. For a task, the active run is cancelled and anything queued is dropped, but its cron schedule keeps firing (use runwisp pause to skip it). A run ID stops just that run, wherever it came from.

Flag	Description
--local	Use the per-user unit when both a system and a per-user unit exist.
--attach	With targets, then follow the logs of the ones it acted on, like runwisp logs -f. Each run it starts is shown from its first line.
--url	Act on a remote daemon at this URL. Env: RUNWISP_URL.
--password	Password for --url. Env: RUNWISP_PASSWORD.

runwisp pause

runwisp pause <task...>
runwisp pause nightly-backup 'report-*'

Pauses the cron schedule of one or more tasks; runwisp resume lifts it. See Pausing a schedule. A glob skips services, tasks without cron, and tasks that are locked or held; naming one directly is rejected. An active run is left alone.

Flag	Description
--url	Act on a remote daemon at this URL. Env: RUNWISP_URL.
--password	Password for --url. Env: RUNWISP_PASSWORD.

runwisp resume

runwisp resume <task...>
runwisp resume '*'

Resumes paused schedules. Each task fires again from its next scheduled time; skipped ones are not caught up. A glob matches only paused tasks. Takes the same flags as pause.

Migrating

runwisp import

crontab -l | runwisp import cron
runwisp import cron /etc/crontab --write
runwisp import supervisord /etc/supervisor/conf.d/*.conf -o runwisp.toml
runwisp import systemd /etc/systemd/system/myapp.service

Converts existing config into RunWisp TOML and prints it to stdout. Reads files or stdin. Anything that doesn’t map cleanly becomes a # TODO comment. Import never disables the source, so turn the old job off before starting RunWisp or it runs twice.

Subcommand	Converts
cron [FILE]	A crontab. /etc/crontab and /etc/cron.d/* user columns are detected.
supervisord [FILE…]	[program:*] sections, following [include].
systemd [UNIT…]	.service units. Restart= → service, Type=oneshot → task.

Flag	Description
-o, --output	Write to this file instead of stdout.
--write	Stage into runwisp.d/imported.toml and include it from --config. See Staging and promoting.
--force	Overwrite the target file without asking.
--dry-run	Print the summary and the files that would change; write nothing.
--quiet	Show only the jobs that need attention.
--system	(cron only) Force system-crontab parsing; --system=false forces per-user.

The summary marks each job: ✓ mapped, ~ changed, ! needs a fix, - skipped because it already exists.

runwisp promote

runwisp promote backup
runwisp promote --all --reload

Moves an imported task (staged by import --write, or read from a crontab via include_cron) into your own runwisp.toml. See Staging and promoting.

Flag	Description
--all	Promote every staged and crontab-sourced task.
--reload	Reload the daemon afterwards.
--dry-run	Print what would move; write nothing.

runwisp takeover

sudo runwisp takeover

Replaces the system cron in one step: writes a config that reads your crontabs, installs RunWisp as a system service, masks cron, and starts RunWisp. Needs root and systemd. See From cron.

Flag	Description
--dry-run	Print the plan and exit. Exits non-zero if it would fail.
-y, --yes	Don’t ask for confirmation.
--allow-skipped-cron-jobs	Continue even if some cron jobs couldn’t be read.
--force	Overwrite a hand-edited unit.
--binary	Binary path to put in the unit (default: this binary).

Autostart

runwisp service install

sudo runwisp service install
runwisp service install --local

Installs a unit so the daemon starts on boot. See Autostart.

Flag	Description
--local	Per-user unit (systemd user unit, or LaunchAgent on macOS) instead of the system service. Required on macOS.
--print	Print the unit to stdout and exit.
--dry-run	Print the plan and exit.
-y, --yes	Don’t ask for confirmation.
--force	Overwrite a hand-edited unit.
--binary	Binary path to put in the unit (default: this binary).

Re-running is safe: an identical unit is left alone, a changed one asks before overwriting.

runwisp service uninstall

sudo runwisp service uninstall

Stops the daemon, disables autostart, and removes the unit. Keeps the data directory. If takeover retired cron, this gives cron back.

Flag	Description
--purge	Also delete the data directory. Asks you to type delete, even with --yes.
--local	Use the per-user unit when both exist.
-y, --yes	Don’t ask for confirmation.
--force	Also remove a hand-edited unit.

runwisp service status

runwisp service status

Shows whether the unit is installed, enabled, and running, and whether the unit or binary changed since install.

Exit code	Meaning
0	Installed, enabled, running, unchanged.
1	Installed, but disabled, stopped, or changed.
2	Not installed.

Flag	Description
--local	Use the per-user unit when both exist.

Other commands

runwisp password

runwisp password | wl-copy

Prints the generated Web UI password.

Exit code	Meaning
0	Printed.
1	Refused: the daemon uses RUNWISP_PASSWORD.
2	The daemon isn’t reachable.
5	Authentication is off; there’s no password.
3, 4	Unexpected error.

runwisp schema

Prints the JSON Schema for runwisp.toml. See Editor support.

runwisp openapi

Prints the REST API’s OpenAPI 3.1 spec, the same one a daemon serves at /openapi.json.

runwisp demo

runwisp demo

Starts a throwaway instance with a sample config and hundreds of past runs. It lives in a temp directory that’s deleted when the daemon stops.

Flag	Description
--no-tui	Leave the daemon running, print its password and data directory, and exit.
--seed-only	Write the demo config to --config, seed --data, and exit without starting anything.

runwisp station

Starts the daemon connected to a RunWisp Station control plane instead of scheduling locally. Needs RUNWISP_STATION_TOKEN. Flags: --token, --url, --env-file (default .env), --no-tui. runwisp demo --station takes the same flags.

runwisp completion

runwisp completion bash > /etc/bash_completion.d/runwisp

Prints a shell completion script for bash, zsh, fish, or powershell.