Skip to main content
DEV MODE
Running from branch dev
isomorphiq
Register

Documentation

Browse system documentation and architecture references.

Commands

supervisor/commands.md

Supervisor Commands

All commands below run through:

yarn ctl <command> [args]

You can also run the compatibility form directly:

yarn workspace @isomorphiq/supervisor control <command> [args]

Optional separator style also works:

yarn ctl -- <command> [args]

Global Behavior

  • Control API default URL: http://127.0.0.1:3014
  • Override with SUPERVISOR_CONTROL_URL
  • Or set SUPERVISOR_CONTROL_HOST and SUPERVISOR_CONTROL_PORT
  • JSON responses are printed to stdout for API-style commands.
  • Exit code is non-zero on command failure.

Target Syntax

  • Service target: <process-id> (example: gateway)
  • Worker target: worker@<worker-id> (example: worker@worker-1)

Aliases accepted by the CLI:

  • web -> appshell
  • ui -> appshell

Command List

health

Check supervisor control API health.

yarn ctl health

ps / list

List all supervised processes.

yarn ctl ps

Equivalent:

yarn ctl list

status [target]

Show full process list, or a single process snapshot if a target is provided.

yarn ctl status
yarn ctl status gateway
yarn ctl status worker@worker-1

start <target>

Start one process.

yarn ctl start gateway
yarn ctl start worker@worker-1

Options:

  • --wait=true|false (default: true)
  • --timeout=<ms> (default: 20000)

Example:

yarn ctl start gateway --wait=true --timeout=30000

stop <target>

Stop one process.

yarn ctl stop gateway
yarn ctl stop worker@worker-1

Options:

  • --signal=<SIGNAL> (example: SIGTERM, SIGINT, SIGKILL)

Example:

yarn ctl stop worker@worker-1 --signal=SIGTERM

restart <target>

Restart one process.

yarn ctl restart gateway
yarn ctl restart worker@worker-1

Options:

  • --wait=true|false (default: true)
  • --timeout=<ms> (default: 20000)

Example:

yarn ctl restart worker-manager --timeout=30000

logs

Read diagnostics events from the diagnostics JetStream stream.

yarn ctl logs

Behavior:

  • Reads recent events from JetStream rather than tailing repository log files
  • Default mode is follow (streaming)
  • Accepts an optional process target and filters diagnostics events by service/task/correlation payload fields

Options:

  • --follow=true|false (default: true)
  • --lines=<N> (default: 200, min: 1, max: 20000)

Examples:

yarn ctl logs
yarn ctl logs --lines=500
yarn ctl logs --follow=false --lines=50

dynamic

List loaded dynamic services.

yarn ctl dynamic

load <module-path>

Load a dynamic service module.

yarn ctl load ./path/to/dynamic-service.ts

Options:

  • --watch=true|false (default: true)
  • --start=true|false (default: true)

Example:

yarn ctl load ./services/dynamic/example.ts --watch=true --start=true

unload <service-id-or-module-path>

Unload a dynamic service.

yarn ctl unload dynamic-service-id

Options:

  • --signal=<SIGNAL>

Example:

yarn ctl unload dynamic-service-id --signal=SIGTERM

reload <service-id-or-module-path>

Reload a dynamic service.

yarn ctl reload dynamic-service-id

Common Operations

Restart supervisor-managed services in order:

yarn ctl restart gateway
yarn ctl restart worker-manager
yarn ctl restart worker@worker-1

Get quick diagnostics:

yarn ctl health
yarn ctl ps
yarn ctl logs --follow=false --lines=100