CLI reference

The harmonic command manages the server. After a global install (npm install -g @mintopia/harmonic) it’s on your PATH; without one, prefix any command with npx @mintopia/harmonic. Running harmonic with no command, or with help / --help, prints usage.

harmonic <command> [options]
npx @mintopia/harmonic <command> [options]

Commands

Command	What it does
`serve`	Run the server in the foreground (Ctrl-C to stop). Best for a quick one-off.
`start`	Run the server in the background; logs to `<data-dir>/harmonic.log`. Returns immediately.
`install`	Install Harmonic as an OS service. Run `harmonic install --help` for the available options and platform-specific details.
`status`	Report whether a background server is running, and where. Exits non-zero if it isn’t, usable in scripts.
`stop`	Stop the background server started with `start`.
`help`	Show usage. Also `--help`, or running with no command.

Standalone or installed service

Run Harmonic standalone when you want to manage its lifetime yourself: use harmonic serve to keep it in the foreground, or harmonic start to run its background daemon. Use harmonic install when you want your OS to manage Harmonic as a service instead. For service setup and options, run harmonic install --help.

Only one standalone background server runs per data directory. start launches it, status inspects it, and stop shuts it down. All three read the same --data-dir to find each other, so pass a matching --data-dir to every command when you run off the default.

Options

Option	Commands	Default	Description
`--port <n>`	`serve`, `start`	`4700`	Port to listen on.
`--host <h>`	`serve`, `start`	`0.0.0.0`	Bind address. `0.0.0.0` is reachable from your network; use `127.0.0.1` for local-only.
`--data-dir <dir>`	all	`~/.harmonic`	Where Harmonic keeps its data and background log.
`--password <pw>`	`serve`, `start`	—	Set or update the operator password. Pass an empty value (`--password ''`) to remove it and run ungated.

--data-dir applies to every command, including status and stop, which use it to locate the running server. status and stop accept only --data-dir; passing --port, --host, or --password to them is an error and exits non-zero. Those three flags belong to the commands that start a server (serve, start).

Examples

Run in the foreground on a custom port, local-only:

harmonic serve --host 127.0.0.1 --port 8080

Start a password-protected background server with its own data directory:

harmonic start --password 'correct horse' --data-dir ~/harmonic-work
harmonic status --data-dir ~/harmonic-work
harmonic stop   --data-dir ~/harmonic-work

Remove a previously set password (run ungated again):

harmonic start --password ''

Staying up to date

A global install keeps itself current. Harmonic checks npm once an hour (and once at startup); when a newer release is out, a banner appears in the app. The next time your fleet is idle it installs the new version, swaps to it, and relaunches, so nothing is interrupted mid-flight. Dismiss the banner to hide a version you’re not ready for; the next release brings it back.

Running through npx fetches the latest published version every time, so there’s nothing to update. From a source checkout Harmonic doesn’t self-update; pull and rebuild instead.