Service Manager

The service command manages long-running JSH services through a service controller. It can read service configurations, install or uninstall services, start and stop them, and inspect current runtime state.

Overview

The service command talks to a running service controller over JSON-RPC. It does not directly launch services by itself. Instead, it sends management requests such as:

• Read configuration files
• Apply configuration updates
• Install a service from a JSON file or inline options
• Start and stop a service
• Show service status
• Remove a service registration

Controller Address

The command requires a controller endpoint. You can pass it explicitly with --controller, or provide it through the SERVICE_CONTROLLER environment variable.

When the service command is launched by the machbase-neo runtime, the runtime sets SERVICE_CONTROLLER automatically. In normal JSH service-management workflows, you usually do not need to specify --controller explicitly, so the examples below omit it for readability.

Supported endpoint formats are:

• host:port
• tcp://host:port
• unix://path

Syntax

service [--controller=<host:port|tcp://host:port|unix://path>] <command> [args...]

Common options

• -c, --controller <endpoint> controller address in TCP or Unix socket form
• -t, --timeout <msec> RPC timeout in milliseconds, default 5000
• -h, --help show help

Usage example

/work > service status

Commands

The service command supports these subcommands:

• read
• update
• reload
• install <config.json>
• install --name <name> --executable <path> [--arg <arg> ...] [--working-dir <dir>] [--enable] [--env KEY=VALUE ...]
• uninstall <service_name>
• status [service_name]
• start <service_name>
• stop <service_name>

Service Configuration Format

A service definition is a JSON object.

{
  "name": "alpha",
  "enable": true,
  "working_dir": "/work/app",
  "environment": {
    "APP_MODE": "prod",
    "PORT": "8080"
  },
  "executable": "node",
  "args": ["server.js", "--port", "8080"]
}

Common fields are:

status

Shows either the full service list or one service detail.

Syntax

service status [service_name]

When called without a service name, it prints a table with service name, enabled state, runtime status, PID, and executable.

Usage example: list services

/work > service status
NAME   ENABLED STATUS  PID EXECUTABLE
alpha  yes     running 101 echo
beta   no      stopped -   /bin/date

With a service name, it prints detailed status including working directory, environment, and recent output lines.

Usage example: one service

/work > service status alpha
[alpha] ENABLED
  status: running
  exit_code: 0
  pid: 55
  start: echo [ hello, world ]
  cwd: /work
  environment:
    A=1
    B=2
  output:
    line-6
    ...
    line-25

read

Reads service configuration files from the controller configuration directory and reports changes.

Syntax

service read

The result is grouped into sections such as UNCHANGED, ADDED, UPDATED, REMOVED, and ERRORED.

Usage example

/work > service read
UNCHANGED (1)
  - alpha exec=echo
ADDED (1)
  - beta exec=node
UPDATED (0)
  (none)
REMOVED (1)
  - old exec=sleep
ERRORED (1)
  - broken read_error=invalid json

update and reload

Both commands ask the controller to apply configuration changes.

• update applies current configuration state
• reload rereads configuration files and applies the resulting changes

Syntax

service update
service reload

The output contains two sections:

• ACTIONS, which lists performed actions such as UPDATE stop or UPDATE start
• SERVICES, which shows the resulting service table

install

Installs a service either from a JSON file or from inline options. After a successful install, the controller writes the service definition to /etc/services/<name>.json. The file name is determined by the service name from the JSON file or from the --name option.

Install from JSON file

Syntax

service install <config.json>

Usage example

/work > service install svc.json

If svc.json contains "name": "alpha", the installed configuration is stored as /etc/services/alpha.json.

Install with inline options

Syntax

service install \
  --name <service_name> \
  --executable <path> \
  [--working-dir <dir>] \
  [--enable] \
  [--arg <arg> ...] \
  [--env KEY=VALUE ...]

Inline install options

• -n, --name <name> service name
• -x, --executable <path> executable path or command name
• -w, --working-dir <dir> working directory
• --enable enable the service immediately
• -a, --arg <arg> add one executable argument, repeatable
• -e, --env KEY=VALUE add one environment variable, repeatable

Usage example

/work > service install \
  --name svc-inline \
  --executable node \
  --working-dir /work/app \
  --enable \
  --arg app.js \
  --arg --port \
  --arg 8080 \
  --env APP_MODE=prod \
  --env PORT=8080

This inline form also creates /etc/services/svc-inline.json on the controller side.

The command prints a RESULT table and then a detailed SERVICE section.

start and stop

Starts or stops a named service.

Syntax

service start <service_name>
service stop <service_name>

The output includes the operation result and the current service state.

Usage example

/work > service start alpha
/work > service stop alpha

uninstall

Removes a service registration.

Syntax

service uninstall <service_name>

Usage example

/work > service uninstall alpha
RESULT
uninstall alpha yes removed

Typical Workflow

Create a service JSON file:

{
  "name": "alpha",
  "enable": true,
  "working_dir": "/work",
  "executable": "echo",
  "args": ["hello", "world"]
}

Then manage it with these commands:

/work > service install alpha.json
/work > service status
/work > service stop alpha
/work > service start alpha
/work > service uninstall alpha

Notes

• service requires a reachable controller endpoint.
• status without an argument lists all services; with one argument it shows one service in detail.
• install cannot mix a config file path with inline install options.
• Inline --env values must use KEY=VALUE form.
• Relative config file paths are resolved from the current working directory.