Skip to content
machbase-neo
JSH
Service Manager

Service Manager

The servicectl 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 servicectl 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 servicectl 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 controller address formats are:

  • host:port
  • tcp://host:port
  • unix://path
Syntax
servicectl [--controller=<addr>] <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 > servicectl status

Commands

The servicectl 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>
  • details get <service_name> [key] [--format box|json]
  • details set <service_name> <key> <value> [--detail-type <string|number|boolean|bool|object|json>]
  • details delete <service_name> <key>

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": "server.js",
  "args": ["--port", "8080"]
}

Common fields are:

FieldTypeDescription
nameStringService name
enableBooleanWhether the service should be enabled
working_dirStringWorking directory for the service process
environmentObjectEnvironment variables as KEY: VALUE pairs
executableStringExecutable path or command name
argsArray<String>Command-line arguments

status

Shows either the full service list or one service detail.

Syntax
servicectl 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 > servicectl 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 > servicectl 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
servicectl read

The result is rendered as a single table. Each row includes a STATUS column whose value is one of UNCHANGED, ADDED, UPDATED, REMOVED, or ERRORED.

The table is rendered in the same pretty box format used by the servicectl status list output.

Usage example
/work > servicectl read
┌────────┬───────────┬────────────┬──────────────┬─────────────┬────────────┐
│ NAME   │ STATUS    │ EXECUTABLE │ READ_ERROR   │ START_ERROR │ STOP_ERROR │
├────────┼───────────┼────────────┼──────────────┼─────────────┼────────────┤
│ alpha  │ UNCHANGED │ echo       │              │             │            │
│ beta   │ ADDED     │ node       │              │             │            │
│ old    │ REMOVED   │ sleep      │              │             │            │
│ broken │ ERRORED   │            │ invalid json │             │            │
└────────┴───────────┴────────────┴──────────────┴─────────────┴────────────┘

update and reload

Both commands ask the controller to apply configuration changes.

  • update applies only the currently detected configuration changes. Added, removed, and updated services are reconciled, while unrelated services are left as-is.
  • reload rereads configuration files, stops all currently running services first, applies the configuration changes, and then starts only services with enable=true.
Syntax
servicectl update
servicectl reload

The output contains two sections:

  • ACTIONS, which lists performed actions such as UPDATE stop, UPDATE start, RELOAD stop, or RELOAD 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
servicectl install <config.json>
Usage example
/work > servicectl install svc.json

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

Install with inline options

Syntax
servicectl 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 > servicectl 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
servicectl start <service_name>
servicectl stop <service_name>

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

Usage example
/work > servicectl start alpha
/work > servicectl stop alpha

details

Manages runtime detail values exposed by a service. These values are separate from the static service configuration and are intended for runtime metadata such as health status, counters, labels, or custom structured state.

Syntax
servicectl details get <service_name> [key] [--format box|json]
servicectl details set <service_name> <key> <value> [--detail-type <string|number|boolean|bool|object|json>]
servicectl details delete <service_name> <key>
Details options
  • --format <box|json> output format for details get, default box
  • --detail-type <type> value type for details set, default string

Supported detail value types are:

  • string, the default when --detail-type is omitted
  • number
  • boolean or bool
  • object or json

Type handling rules:

  • string stores the input text as-is
  • number parses the input as a JSON number
  • boolean and bool parse the input as JSON true or false
  • object and json parse the input as a JSON object, not an array or scalar

details set uses a single RPC request and behaves as an upsert. If the key already exists, its value is replaced. If it does not exist, the key is created.

When --format json is used:

  • servicectl details get <service_name> prints the full details object
  • servicectl details get <service_name> <key> prints a JSON object containing only that key
Usage example: box output
/work > servicectl details get alpha
DETAILS (3)
┌─────────┬─────────┬────────────────────┐
│ KEY     │ TYPE    │ VALUE              │
├─────────┼─────────┼────────────────────┤
│ enabled │ boolean │ true               │
│ labels  │ object  │ {"tier":"gold"}    │
│ retries │ number  │ 3                  │
└─────────┴─────────┴────────────────────┘
Usage example: JSON output
/work > servicectl details get alpha labels --format json
{
  "labels": {
    "tier": "gold"
  }
}
Usage example: set values
/work > servicectl details set alpha mode warm
/work > servicectl details set alpha retries 3 --detail-type number
/work > servicectl details set alpha enabled true --detail-type bool
/work > servicectl details set alpha labels '{"tier":"gold"}' --detail-type json
Usage example: delete a key
/work > servicectl details delete alpha labels

uninstall

Removes a service registration.

Syntax
servicectl uninstall <service_name>
Usage example
/work > servicectl 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 > servicectl install alpha.json
/work > servicectl status
/work > servicectl stop alpha
/work > servicectl start alpha
/work > servicectl uninstall alpha

Notes

  • servicectl 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.
Last updated on
Command ReferencePackage Manager