Lighthouse mark for Peisong's Lighthouse Peisong's Lighthouse Somewhere to find inspiration.

LIGHTHOUSE CLI

lighthouse

lighthouse is the deployment and content-materialization CLI for Peisong’s Lighthouse. It pulls configured repositories, discovers tracked .md and .tex documents, rewrites local references into site URLs, generates Jekyll-ready posts, builds the site, deploys timestamped releases, and optionally emails run logs through SMTP and purges Cloudflare cache through the Cloudflare API. It also manages the server-local Harbor dynamic app platform through lighthouse harbor.

Table of Contents

Docs

  • Start here: docs/quickstart.md Install the CLI, lay out the runtime directory, validate config, and run local or deploy builds.
  • Design: docs/design.md Pipeline stages, state model, deployment layout, and content rewrite rules.
  • Configuration: docs/configuration.md Full YAML schema, defaults, validation rules, and command behavior.

Installation

Install into the local Python environment:

python -m pip install .

For development:

python -m pip install -e .

Command Summary

lighthouse --help
lighthouse --version

lighthouse [--run-dir PATH] [--config PATH] [--verbose] [--dry-run] [--email-log] validate [--target TARGET ...] [--config-only] [--no-sync] [--fresh]
lighthouse [--run-dir PATH] [--config PATH] [--verbose] [--dry-run] [--email-log] build [--target TARGET ...] [--no-sync] [--fresh]
lighthouse [--run-dir PATH] [--config PATH] [--verbose] [--dry-run] [--email-log] apply [--target TARGET ...] [--no-sync] [--fresh]
lighthouse [--run-dir PATH] [--config PATH] [--verbose] purge-cache
lighthouse [--run-dir PATH] [--config PATH] [--verbose] [--dry-run] clean [--target TARGET ...]
lighthouse [--run-dir PATH] [--config PATH] [--verbose] check-deps
lighthouse [--run-dir PATH] [--config PATH] [--verbose] status
lighthouse [--run-dir PATH] [--config PATH] [--verbose] list-backups
lighthouse [--run-dir PATH] [--config PATH] [--verbose] [--dry-run] local 4000 [--no-sync] [--fresh]
lighthouse [--run-dir PATH] [--config PATH] [--verbose] [--dry-run] [--email-log] remote build [--no-sync] [--fresh]
lighthouse [--run-dir PATH] [--config PATH] [--verbose] [--dry-run] [--email-log] remote send [--artifact-run-id RUN_ID]
lighthouse [--run-dir PATH] [--config PATH] [--verbose] [--dry-run] [--email-log] remote apply [--artifact-run-id RUN_ID]
lighthouse [--run-dir PATH] [--config PATH] [--verbose] harbor check-deps
lighthouse [--run-dir PATH] [--config PATH] [--verbose] harbor local [--port PORT]
lighthouse [--run-dir PATH] [--config PATH] [--verbose] harbor status
lighthouse [--run-dir PATH] [--config PATH] [--verbose] harbor apps
lighthouse [--run-dir PATH] [--config PATH] [--verbose] harbor ps
lighthouse [--run-dir PATH] [--config PATH] [--verbose] harbor logs
lighthouse [--run-dir PATH] [--config PATH] [--verbose] harbor add-user USERNAME --name NAME --email EMAIL [--subject SUBJECT] [--password PASSWORD] [--permission PERMISSION]
lighthouse [--run-dir PATH] [--config PATH] [--verbose] harbor set-password USERNAME [--password PASSWORD]
lighthouse [--run-dir PATH] [--config PATH] [--verbose] harbor list-permissions [USERNAME]
lighthouse [--run-dir PATH] [--config PATH] [--verbose] harbor list-all-permissions
lighthouse [--run-dir PATH] [--config PATH] [--verbose] harbor add-permissions USERNAME PERMISSION [PERMISSION ...]
lighthouse [--run-dir PATH] [--config PATH] [--verbose] harbor delete-permissions USERNAME PERMISSION [PERMISSION ...]
lighthouse [--run-dir PATH] [--config PATH] [--verbose] harbor delete-user USERNAME
lighthouse [--run-dir PATH] [--config PATH] [--verbose] harbor migrate-db
lighthouse [--run-dir PATH] [--config PATH] [--verbose] harbor maintenance on|off
lighthouse [--run-dir PATH] [--config PATH] [--verbose] email-test you@example.com

Default Runtime Layout

~/.lighthouse/
  config/
    lighthouse.yml
    harbor.yml
  cache/
    repos/
  remote-cache/
    builds/
    artifacts/
  states/
    state-<timestamp>.json
  logs/
    <timestamp>.log
  lock

Examples

Example configuration fragments:

The config directory now supports separate command-specific files:

  • lighthouse.yml or lighthouse.yaml for the static site pipeline under LIGHTHOUSE:
  • harbor.yml or harbor.yaml for the Harbor platform under HARBOR:

GLOBAL is reserved for future shared settings, but the current command loaders do not scan global.yml.

Ratings are optional. When enabled, build, apply, and local assign incremental per-post LLM scores through OpenRouter and write the resulting weighted-random metadata into generated post front matter and runtime state. You can tune the rating request with MAX_RETRIES, MAX_THREADS, HTTP_TIMEOUT_SECONDS, and REASONING_EFFORT.

RSS feed policy is also configurable in the CLI. By default, RSS is enabled and only items with a combined rating above the configured threshold are emitted. Updated posts currently follow the mechanical path when UPDATED_DIFF_RATING_THRESHOLD is <= 0.

The CLI also owns generated resume artifacts for the site repository. If resume.tex is present in the cached lighthouse checkout, build, apply, and local generate:

  • assets/generated/resume/resume.fragment.html
  • assets/generated/resume/resume.pdf

Use lighthouse check-deps to confirm the current environment has the required executables for the configured feature set, including make4ht for .tex materialization and latexmk for resume PDF generation.

Cloudflare cache purging is also optional. When enabled, apply purges the configured zone once at the end of the run after Harbor and Lighthouse deployment attempts complete. lighthouse purge-cache invokes the same purge path directly.

Remote artifact deployment is also supported. Configure a REMOTE block and use:

  • lighthouse remote build to build locally and package a tarball
  • lighthouse remote send to upload that tarball into the remote cache
  • lighthouse remote apply to trigger remote deployment from the already-uploaded tarball

In this mode, the local role owns sync, materialization, ratings, resume artifact generation, and the Jekyll build. The remote role only unpacks the artifact, activates a release, rotates old releases, and optionally purges Cloudflare.

When the local role is configured with a remote lighthouse-cli clone URL and repo path, remote apply will also:

  • clone the remote lighthouse-cli repo if it is missing
  • otherwise pull the existing remote checkout
  • install or upgrade the remote package from that repo path
  • sync a derived remote-role config.yml into the remote run dir
  • sync portable content metadata (content-state.json) so publish dates and ratings can follow the local authority across remotes

If local and remote content metadata differ, remote apply now pauses for an explicit resolve step. Type local or remote to choose which metadata authority should win before deployment continues.

Harbor is server-local in v1. Root lighthouse validate|build|apply now operate on both configured targets by default:

  • Harbor first
  • Lighthouse second

Use --target harbor or --target lighthouse to narrow a run. Harbor apply writes or updates the user service unit and restarts Harbor when the Harbor target changed. Clone-backed Harbor app updates also participate in Harbor change detection, so app-only repo changes no longer get skipped. harbor local still builds Harbor and runs it in the foreground for e2e testing.

clean also supports --target harbor and --target lighthouse. Harbor clean removes the Harbor repo cache under the configured Harbor runtime tree. Lighthouse clean removes the static-site repo cache under the root CLI run dir.

Harbor itself and docked Harbor apps support two explicit source modes:

  • SOURCE_DIR
  • CLONE_URL together with BRANCH

Each Harbor target must choose exactly one source mode. Clone-backed Harbor sources are fetched into the Harbor repo cache before the Harbor build runs, and clone-backed apps are fetched into the same cache before their app builds run.

Each Harbor app may also declare an optional DESCRIPTION field. Harbor uses that on the landing page cards.

Harbor user management is Postgres-backed. HARBOR.DATABASE_URL points Harbor at its own mutable platform store for:

  • users
  • direct permissions
  • user preferences
  • maintenance state

HARBOR.OIDC.EMBEDDED_USERS are bootstrap-only seed users. Run lighthouse harbor migrate-db to create the Harbor schema and import legacy state or embedded users into Postgres. After that, Harbor ignores EMBEDDED_USERS for steady-state auth. Once the Harbor database is initialized, it is safe to remove EMBEDDED_USERS from config. Manage users and direct permissions through the Harbor CLI:

  • lighthouse harbor add-user
  • lighthouse harbor set-password
  • lighthouse harbor list-permissions
  • lighthouse harbor list-all-permissions
  • lighthouse harbor add-permissions
  • lighthouse harbor delete-permissions
  • lighthouse harbor delete-user

Harbor canonical usernames are lowercase and limited to a-z, 0-9, _, and -. Harbor uses the canonical username for identity and route-safe slugs. Display names remain separate and human-facing.

The special admin permission acts as a wildcard and satisfies any app permission check.

Harbor also persists user-facing theme and timezone preferences in the database for authenticated users. Guests use the default Harbor preferences until they sign in.