@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 ~/.dbx-tools/bin.

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

| Command | Description | | ------------------- | ----------------------------------------------------- | | install [options] | Install the service for the current user and start it | | start | Start the installed service | | stop | Stop the running service | | restart | Restart the installed service | | status | Print service installation and process state as JSON | | logs [command...] | Print the service log path or append it to a command | | uninstall | Stop and remove the service for the current user |

<cli> service install

Install the service for the current user and start it

<cli> service install [options]

Options

| Option | Description | | -------------------------- | ---------------------------------------------------------------------------------- | | --start | Start the service after installation. (default: true) | | --no-start | Disable start the service after installation. | | --python-project <value> | Local Python project installed instead of the registry package. | | --offline | Install Python packages from the uv cache without network access. (default: false) | | --no-offline | Disable install python packages from the uv cache without network access. |

<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

| Argument | Description | | --------- | -------------------------------------------------------- | | command | Command and arguments to run before the service log path |

<cli> service uninstall

Stop and remove the service for the current user

<cli> service uninstall