CLI Reference

Reference for serving LightShip, connecting coding agents, validating the access model, and generating password hashes.

The lightship binary provides the HTTP service, local MCP companion, access-model check, and password-hashing utility. Every command exits with a non-zero status on failure. Run Docker Compose examples from the LightShip checkout root.

Command summary

Command	Purpose
lightship serve	Start the LightShip HTTP service after initializing its Postgres state.
lightship mcp	Run the local MCP companion over stdio and keep bulk trace exports out of model context.
lightship check	Compile the access model stored in Postgres and print its status.
lightship hash	Read a password from a hidden terminal prompt or standard input and print its Argon2id hash. No database connection is required.

lightship serve

serve is the command you run in production and in local development. On startup it performs the following actions in order:

1. Connects to Postgres using DATABASE_URL.
2. Runs any pending schema migrations.
3. Creates the admin account if LIGHTSHIP_ADMIN_PASSWORD_HASH is set, or generates a one-time password, prints it to the log, and stores its hash.
4. Loads the access model into memory.
5. Starts the HTTP server on the address given by LIGHTSHIP_ADDR (default :8080).

Example invocation:

Binary

lightship serve

serve requires both DATABASE_URL and CLICKHOUSE_DSN. An invalid or unreachable Postgres connection, or a malformed ClickHouse DSN, prevents startup. If a valid ClickHouse endpoint is temporarily unreachable, LightShip starts but trace queries fail closed until it recovers.

lightship mcp

mcp is launched by a coding agent as a local stdio server. It provides LightShip’s bounded trace tools and lightship_export_traces. The export tool follows REST pagination and writes a complete JSONL artifact under .lightship/exports without returning its rows through MCP.

Variable	Required	Default
LIGHTSHIP_URL	yes	—
LIGHTSHIP_API_KEY	yes	—
LIGHTSHIP_EXPORT_DIR	no	.lightship/exports in the current workspace

Keep the export directory out of version control because it can contain complete trace payloads. See MCP Clients for client configuration.

lightship check

check validates the stored access model without starting a server or altering the database. Use it in CI pipelines or before rolling out a configuration change to confirm that roles and policies compile correctly. It does not verify that your ClickHouse schema matches the bound source.

Example invocation:

Binary

lightship check

A missing source binding produces a warning, not a fatal error, so check can be used on a fresh database before setup is complete.

lightship hash

hash generates an Argon2id hash from a password. Use it to precompute LIGHTSHIP_ADMIN_PASSWORD_HASH or to rotate the admin password securely.

LightShip accepts only this fixed profile: v19, 64 MiB memory, 3 iterations, 4 lanes, a 16-byte salt, and a 32-byte digest, in canonical PHC encoding. Other profiles and malformed encodings are rejected before storage and verification. Replace any previously imported hash that uses another profile with one generated by this command before upgrading.

Example invocation with a hidden terminal prompt:

Binary

lightship hash

Example invocation piping a password from stdin:

Binary

echo -n 'my-password' | lightship hash

lightship hash does not connect to Postgres or ClickHouse, so it can run offline or inside a restricted container.

Next steps

• For recovering the admin account when the password is lost, see Admin Recovery.
• For the full list of environment variables, see Configuration.