How to use the CLI

The Pharos CLI is used to build, serve, and manage Pharos apps and runtimes.

Command shape

Many Pharos commands follow one of these patterns:

pharos <command-family> <target-kind> <target-id> [options]
pharos <command-family> <subcommand> <target-kind> <target-id> [options]

Common examples:

sudo systemctl start pharos
pharos serve runtime shared --conf /etc/pharos/pharos.conf
pharos build app todo_list --app-dir ./todo_list --build-dir /srv/pharos
pharos migrate apply app todo_list --app-dir ./todo_list --backend sqlite
pharos build app commerce_spa --app-dir ./commerce_spa --build-dir /srv/pharos
pharos migrate apply app commerce_spa --app-dir ./commerce_spa --backend sqlite
pharos build app ucal --app-dir ./ucal --build-dir /srv/pharos
pharos migrate apply app ucal --app-dir ./ucal --backend sqlite
pharos seed app ucal --app-dir ./ucal --backend sqlite
sudo systemctl restart pharos
pharos build app dev_docs --build-dir dist
pharos serve app dev_docs --build-dir dist --port 8083
pharos build app dynamic_app --build-dir dist
pharos doctor app ucal --build-dir dist

Use pharos --help to see the full command matrix.

Run the installed apps or build an editable copy

On Debian or Ubuntu, the package-installed apps are already built:

sudo systemctl start pharos

That shared runtime serves the installed apps under /srv/pharos/apps/.

If you want a writable example app for local edits, start from a packaged example source:

cp -R /usr/share/pharos/examples/todo_list ./todo_list
sudo pharos build app todo_list --app-dir ./todo_list --build-dir /srv/pharos
pharos migrate apply app todo_list --app-dir ./todo_list --backend sqlite
sudo systemctl restart pharos

On macOS, copy from /usr/local/share/pharos/examples/todo_list instead.

App structure overview

A Pharos app is a directory of files. You define the structure and content. The runtime reads those files and serves the app.

In a typical app, you create:

• pharos.app.yml — the canonical app manifest source
• pharos.app.json — the built artifact manifest emitted from the source manifest
• templates/ — HTML templates and page fragments, plus supported declarative YAML page sources where applicable
• fixtures/ and data/ — YAML or JSON route, surface, workflow, and app data declarations
• static/ and media/ — CSS, images, and media assets
• app.conf — app-local overrides for base path, state paths, logging, database settings, and other runtime-resolved config

YAML is the only supported source-manifest format. JSON manifests are generated build artifacts, not source inputs.

Build an app

Pharos writes built app artifacts under <build-dir>/apps/<app_id>/. Use build to create an app artifact:

pharos build app dev_docs --build-dir dist

Expected artifact layout:

dist/apps/dev_docs/

dist/ is the normal CLI-facing build root. Rust compiler caches remain under target/; do not point routine app build output at target/.

Build a package-ready app artifact

Use --packaging when you are preparing an app artifact for archiving or deployment, especially for database-backed apps like ucal.

pharos build app ucal --build-dir dist --packaging

Packaging mode keeps build-time sqlite, runtime-state, and log output isolated under the local build tree instead of using the app's live runtime defaults such as /var/lib/pharos/... or /var/state/pharos/....

Use build mode without packaging for local development:

pharos build app ucal --build-dir dist

The packaging flow still emits the finalized artifact at:

dist/apps/ucal/

The temporary isolated build-time runtime data lives under:

dist/deploy-build/ucal/

Serve an app locally

Use serve to run an app locally:

pharos serve app dev_docs --build-dir dist --port 8083

Open:

http://127.0.0.1:8083/dev_docs/

For a dynamic app example:

pharos build app ucal --build-dir dist
pharos serve app ucal --build-dir dist --port 8080

Then open:

http://127.0.0.1:8080/ucal/

App hosting profiles

Pharos supports two app profiles:

• dynamic-app — a runtime-served app with YAML or JSON declarative inputs, native request handling, generated surfaces, and database-backed state
• static-pages — a fully materialized static site with app-local content and no runtime database requirement

SQLite, PostgreSQL, MySQL, and MongoDB are supported database backends. Redis is available as an optional runtime cache layer. The default sqlite posture for a database-backed app is /var/lib/pharos/<app_id>.sqlite3. See the configuration guide for backend-specific settings.

Database commands

Use these commands to prepare and verify an app database:

pharos migrate plan app ucal --backend sqlite
pharos migrate status app ucal --backend sqlite
pharos migrate verify app ucal --backend sqlite
pharos migrate apply app ucal --backend sqlite
pharos db seed app ucal --backend sqlite

pharos migrate seed app <target-id> ... is also available when you want the seed flow under the migrate family.

Validation commands

After building or updating an app, common checks include:

pharos doctor app ucal --build-dir dist
pharos deploy check app ucal --build-dir dist
pharos drift check app ucal --build-dir dist

These commands report resolved runtime settings, artifact paths, writable log locations, and deploy-time drift signals.

Shared runtime

To start the shared runtime:

pharos serve runtime shared --conf /etc/pharos/pharos.conf

The shared runtime serves app bundles from apps_dir and applies each app's local config and database settings at runtime.

For Debian installs, the packaged runtime serves the built apps already placed under /srv/pharos/apps/, so the usual local edit cycle is:

sudo pharos build app <app_id> --app-dir ./<app_id> --build-dir /srv/pharos
pharos migrate apply app <app_id> --app-dir ./<app_id> --backend sqlite
sudo systemctl restart pharos

Health checks

Pharos exposes these standard framework probe endpoints:

/health
/ready
/live
/version

Use /ready to confirm the configured database and runtime are ready before sending traffic.