@dbx-tools/cli-service

Add current-user service installation, lifecycle commands, optional uv-managed Python dependencies, and a tray menu to a Commander CLI. The managed command continues after its terminal closes on macOS, Linux, and Windows.

Add service commands

import { buildServiceCommand } from "@dbx-tools/cli-service/cli";
import { defineService } from "@dbx-tools/cli-service/definition";
import { Command } from "commander";

const program = new Command("example");
program.addCommand(
  buildServiceCommand(
    defineService(import.meta.url, {
      command: { arguments: ["serve"] },
      menu: [{ type: "url", label: "Open App", url: "http://127.0.0.1:4400" }],
    }),
  ),
);
await program.parseAsync(process.argv);

defineService uses the owning package's name, version, and default executable. Use command.binName when the package has multiple executable entries. Set command.executable to run an existing external program instead of compiling a package entrypoint. Managed commands default NODE_ENV to production. An explicit command.environment.NODE_ENV overrides it.

Set pythonPackage when the compiled service command needs a Python runtime:

defineService(import.meta.url, {
  pythonPackage: { name: "example-runtime" },
  command: { arguments: ["serve"] },
});

During installation, the service creates an isolated uv environment under its data directory, installs the Python distribution at the service version, and sets PYTHON to that environment's interpreter. pythonPackage.python selects the Python version uv manages and defaults to 3.11. uv must be available on PATH during installation. Uninstalling the service removes the environment with the rest of the service-owned data.

Local-project installations preserve package extras and companion dependencies. Offline installations resolve only from uv's cache and fail immediately when a required artifact is unavailable.

command.options accepts either a concrete option object or a Zod object schema. Objects serialize their current values. Schemas parse {} and serialize their defaults. Boolean values become positive or negated flags, arrays become repeated flags, and undefined values are omitted:

defineService(import.meta.url, {
  command: {
    arguments: ["serve"],
    options: {
      host: "127.0.0.1",
      port: 4400,
      telemetry: false,
    },
  },
});

Install and manage the service

For the example program above:

example service install
example service status
example service logs -- tail -f
example service uninstall

Arguments after -- run as a command with the service log path appended, so logs -- cat prints the log and logs -- tail -f follows it.

The service belongs to the current user. Login startup uses a LaunchAgent on macOS, an XDG autostart entry on Linux, and a Startup command on Windows. Package entrypoints are compiled with Bun into versioned, per-install generations under ~/.dbx-tools/bin; Python environments use the same versioned generation under the service data directory, and each host generation carries its matching tray executable. Installing on macOS unloads any stale LaunchAgent definition, clears any persisted disabled override, and starts the current generation through launchd. Concurrent service installs serialize both service replacement and updates to the shared runtime dependency directory.

Services may provide an authentication preflight that runs before their managed command. The install-time waitForAuth mode defaults to auto: the owning CLI decides whether an applicable auth source exists, true requires a preflight, and false skips it. The host stays responsive to status and stop requests while the preflight waits.

The startup entries do not supervise the host, so the host restarts a preflight or managed command whenever it exits on its own, waiting 1s, 2s, 5s, 10s, 30s, then 60s between consecutive failures. Each restart is recorded in host.log. Quitting from the tray or running stop ends the host without a restart.

restart stops and starts the installed executable. It does not rebuild it. Re-run install after upgrading a consuming package to replace compiled executables and update the saved configuration.

Customize the tray menu

The default tray menu shows the program name and version and offers Quit. Add URL, command, or separator items through the service definition. Custom command items can select a package binary or an external executable in the same way as the main service command.

Use this package when adding service support to another CLI so users get the same installation, lifecycle commands, and tray behavior. The generated reference uses <cli> as a placeholder for the consuming program's name.

Command reference

<cli> service

Install and manage the desktop service

<cli> service [command]

Commands

<cli> service install

Install the service for the current user and start it

<cli> service install [options]

Options

<cli> service start

Start the installed service

<cli> service start

<cli> service stop

Stop the running service

<cli> service stop

<cli> service restart

Restart the installed service

<cli> service restart

<cli> service status

Print service installation and process state as JSON

<cli> service status

<cli> service logs

Print the service log path or append it to a command

<cli> service logs [command...]

Arguments

<cli> service uninstall

Stop and remove the service for the current user

<cli> service uninstall