Command line

Kiln runs as a single executable with no daemon wrapper or separate process supervisor. It provides four flags and one platform-specific subcommand.

Flags

The full build (kiln) and the Lite build (kiln-lite) share the same flags.

Parsing uses the Go standard library flag package, so a single dash and a double dash are equivalent, as are -config path and -config=path.

kiln -config /etc/kiln/kiln.toml

Unless -version or -healthcheck is given, -config is required. Omitting it prints kiln: -config is required to stderr and exits with status 2.

Exit codes

-version

kiln -version

Prints one space-separated line:

kiln version=1.0.0 commit=dev built_at=unknown variant=full

variant identifies the build: full or lite. The version, commit, and built_at values are injected by linker flags at build time and are placeholders when running straight from source.

A running instance also reports its version without a credential: GET / returns name, version, commit, and the admin console path. See the API reference.

-healthcheck

Issues a single GET with a 3-second timeout. A 2xx response exits 0; anything else writes the error or status line to stderr and exits 1. It reads no config file and starts no server.

kiln -healthcheck http://127.0.0.1:8080/healthz

The flag exists so container images do not have to ship curl or wget. The official image’s HEALTHCHECK instruction is exactly this command.

Windows service

The service subcommand registers Kiln with the Windows Service Control Manager, so no external supervisor is needed.

kiln.exe service install -config C:\kiln\kiln.toml
kiln.exe service start
kiln.exe service status
kiln.exe service stop
kiln.exe service uninstall

-name lets several instances coexist on one host. Every subcommand other than install needs the same name to target the right service.

With no subcommand, or one that is not recognized, usage goes to stderr and the process exits with status 2. Install and uninstall need an elevated terminal.

What each subcommand does

If the service is not installed, the Service Control Manager is unreachable, or the operation fails, the reason goes to stderr and the process exits with status 1.

Runtime behavior under the service manager

The Service Control Manager starts processes in system32, so Kiln resolves -config to an absolute path and then switches the working directory to the folder holding the config. Relative paths such as data_dir = "./data" therefore still resolve against the config file.

Standard output is discarded under the service manager, so Kiln redirects stdout and stderr to kiln.log next to the config. If that file exceeds 16 MB at startup, it is first rotated to kiln.log.1.

The process accepts stop and shutdown controls and runs the same graceful shutdown path as a signal. The service exit code is the process exit code.

Installation records the absolute config path, so moving the binary or the config file means reinstalling the service.

Lite differences

The Lite binary takes the same command line. The differences show up after startup.

• -version reports variant=lite.
• There is no service subcommand, not even on Windows.
• If KILN_DEFAULT_PACKAGER_ENGINE is unset, Lite sets it to native.
• The config is validated before startup. Failing any of the following exits with status 1 and logs lite config rejected:
  • packager.engine must be native;
  • every channel must resolve to the native engine;
  • no [[epg.sources]] entry may carry enabled = true;
  • observe.otlp_endpoint must be empty;
  • debug.pprof.enabled must be false.
• Resource adaptation uses a fixed low-memory profile instead of scaling with host memory.

For route surface differences, see the API reference.

Helper scripts

Three standalone tools live under scripts/. All carry a //go:build ignore tag, run directly with go run, and take no part in building the main binary.

Hash a password

go run scripts/hash-password.go 'your-password'

Prints a single bcrypt hash for auth.users[].password_hash. Passing anything other than exactly one argument prints usage and exits with status 2.

Generate session signing keys

go run scripts/gen-jwt-keys.go ./secrets

Writes the Ed25519 pair ed25519.pem and ed25519.pub.pem into the given directory and prints both paths. Omitting the directory writes to the current one. Point auth.token_private_key_file and auth.token_public_key_file at the results.

Generating keys is optional: on first start the process creates a key pair under {data_dir}/auth/ with the private key at mode 0600. Use the script when keys need to be managed centrally, or when several instances must share one signing key.

Generate romanization data

go run scripts/gen-romanize-data.go
go run scripts/gen-romanize-data.go -unihan ./Unihan.zip -out modules/httpserver/admin/assets/data/romanize.js

Builds the romanization and simplification tables the admin console uses for channel search, from the official Unicode Unihan data set.

The generated module exports the PINYIN, JYUTPING, and SIMPLIFY tables. This is a build-time, one-off step, only needed when tracking an upstream Unicode data update. Rebuild the admin console assets afterwards.

Related reading