> ## Documentation Index
> Fetch the complete documentation index at: https://lightship.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<CodeGroup>
  ```bash Binary theme={null}
  lightship serve
  ```

  ```bash Docker Compose theme={null}
  docker compose up control-plane
  ```
</CodeGroup>

<Warning>
  `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.
</Warning>

## 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](/use/mcp) 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:

<CodeGroup>
  ```bash Binary theme={null}
  lightship check
  ```

  ```bash Docker Compose theme={null}
  docker compose run --rm control-plane check
  ```
</CodeGroup>

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

## 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:

<CodeGroup>
  ```bash Binary theme={null}
  lightship hash
  ```

  ```bash Docker Compose theme={null}
  docker compose run --rm control-plane hash
  ```
</CodeGroup>

Example invocation piping a password from stdin:

<CodeGroup>
  ```bash Binary theme={null}
  echo -n 'my-password' | lightship hash
  ```

  ```bash Docker Compose theme={null}
  echo -n 'my-password' | docker compose run --rm -T control-plane hash
  ```
</CodeGroup>

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

## Next steps

* For recovering the admin account when the password is lost, see [Admin Recovery](/operate/admin-recovery).
* For the full list of environment variables, see [Configuration](/operate/configuration).