CLI Reference

All commands are accessed via jeeves-runner <command>. The CLI is built with createServiceCli(descriptor) from core, which provides standard commands, plus custom commands for job management.

Standard Commands

`start`

Start the runner daemon (foreground).

jeeves-runner start -c <path>

Flag	Description
`-c, --config <path>`	Path to config file

Starts the scheduler, API server, and begins executing jobs on their cron schedules.

`status`

Probe service health and version by querying GET /status.

jeeves-runner status [-p <port>]

Flag	Default	Description
`-p, --port <port>`	`1937`	Service port

`config`

Query or manage service configuration.

jeeves-runner config [jsonpath] [-p <port>]

Queries GET /config on the running instance. Pass a JSONPath expression to filter.

`config validate`

Validate a config file against the Zod schema without starting the runner.

jeeves-runner config validate -c <path>

`config apply`

Apply a config patch to the running service.

jeeves-runner config apply [-p <port>] [-f <path>] [--replace]

Flag	Description
`-p, --port <port>`	Service port (default: 1937)
`-f, --file <path>`	Config patch file (JSON); reads stdin if omitted
`--replace`	Replace entire config instead of merging

`init`

Generate a default config file.

jeeves-runner init [-o <dir>]

Flag	Default	Description
`-o, --output <dir>`	Platform config dir	Output directory for `config.json`

`service`

System service management subcommands.

`service install`

Install as a system service.

jeeves-runner service install [-c <path>] [-n <name>]

`service uninstall`

Uninstall the system service.

jeeves-runner service uninstall [-n <name>]

`service start`

Start the system service.

jeeves-runner service start [-n <name>]

`service stop`

Stop the system service.

jeeves-runner service stop [-n <name>]

`service restart`

Restart the system service.

jeeves-runner service restart [-n <name>]

`service status`

Query system service state.

jeeves-runner service status [-n <name>]

Custom Commands

`add-job`

jeeves-runner add-job \
  -c <config> \
  --id <id> \
  --name <name> \
  --schedule <cron> \
  --script <path> \
  [--type <type>] \
  [--description <desc>] \
  [--timeout <ms>] \
  [--overlap <policy>] \
  [--on-failure <channel>] \
  [--on-success <channel>]

Flag	Required	Default	Description
`-i, --id <id>`	Yes	—	Unique job identifier
`-n, --name <name>`	Yes	—	Human-readable name
`-s, --schedule <schedule>`	Yes	—	Cron expression or RRStack JSON (validated on input)
`--script <path>`	Yes	—	Absolute path to executable script
`-t, --type <type>`	No	`script`	Job type: `script` or `session`
`-d, --description <desc>`	No	—	Job description
`--timeout <ms>`	No	—	Timeout in milliseconds
`--overlap <policy>`	No	`skip`	Overlap policy: `skip` or `allow`
`--on-failure <channel>`	No	—	Slack channel ID for failure alerts
`--on-success <channel>`	No	—	Slack channel ID for success alerts
`-c, --config <path>`	No	—	Config file (for database path)

`list-jobs`

List all registered jobs.

jeeves-runner list-jobs -c <path>

Output shows enabled/disabled status, job ID, schedule, and name.

`trigger`

Manually trigger a job via the API.

jeeves-runner trigger -i <id> -c <path>

Flag	Required	Description
`-i, --id <id>`	Yes	Job ID to trigger
`-c, --config <path>`	No	Config file (for port)

Calls POST /jobs/:id/run and prints the result.

`sync-jobs`

Sync job definitions into the database.

jeeves-runner sync-jobs [--scripts-dir <dir> | --jobs-dir <dir>] [--dry-run] [--reset-enabled] [--prune] [-c <path>]

Flag	Description
`-c, --config <path>`	Config file path
`--scripts-dir <dir>`	jeeves-scripts repo dir (overrides config `scriptsDir`)
`--jobs-dir <dir>`	Legacy JSON jobs dir (deprecated; overrides config `jobsDir`)
`--dry-run`	Report what would change; write nothing
`--reset-enabled`	Overwrite `enabled` on existing jobs with the source value
`--prune`	Disable launcher jobs no longer listed (scripts source only; never deletes)

Source. Flags first (not both), then config scriptsDir, then legacy jobsDir. With the jeeves-scripts source the runner runs node <scriptsDir>/bin/jeeves-scripts.js list --json with its own Node and environment (timeout 120 s; the launcher cold-starts in about 7 s) and registers each runnable that has a manifest: script is the launcher, args are ["run", <id>, ...manifest.args]. A manifest without timeout_seconds (or with null) stores no timeout: a script job then runs unbounded, matching jeeves-scripts, while a session job falls back to the session executor's 5-minute default. An operator-set timeout on an existing job is kept. A failing, unparseable, invalid or duplicate-id list aborts the sync with nothing written. The legacy source prints a deprecation warning.

What a sync changes.

New jobs are added with the source's enabled (default true). A manifest prerequisite is printed and never blocks the add.
On existing jobs, only fields the source specifies are updated; omitted fields stay unchanged.
enabled on existing jobs is never changed unless --reset-enabled is given; disagreements are listed under Enabled drift.
The manifest schedule is applied on every sync, and each schedule it reverts is listed. Schedule changes made through the API or runner_update_job on launcher jobs don't last; change them in jeeves-scripts.json.
Launcher jobs no longer listed are reported as Orphans, and disabled only with --prune. Jobs from other sources are never touched. Paths are compared after normalisation (absolute, separators, case-insensitive on Windows).

Exit codes. 0 when clean; 1 when any entry is skipped for an error or the sync is aborted.