How To Use The Pharos CLI

This guide shows the current Pharos CLI shape for local development, shared runtime hosting, and packaged app workflows.

Install and expose the CLI

If you are working inside the Pharos repository:

cd <user_home>/pharos
scripts/pharos_runtime.sh bootstrap install bin
export PATH="$PWD/bin:$PATH"

If you installed Pharos from a package, use the packaged pharos command directly.

Basic command shape

Pharos commands follow this pattern:

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

Common examples:

pharos build app dev_docs --build-dir dist --text
pharos serve app dev_docs --build-dir dist --port 8083 --text
pharos build app dynamic_app_template --build-dir dist --text
pharos serve app ucal --build-dir dist --port 8080 --text
pharos doctor app ucal --build-dir dist --text

Build an app

Use build to materialize an app artifact:

pharos build app dev_docs --build-dir dist --text

Expected artifact layout:

dist/apps/dev_docs/

Pharos now writes built app artifacts under dist/apps/<app_id>/.

Build a package-ready app artifact

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

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

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 normal build mode for ordinary local development:

pharos build app ucal --build-dir dist --text

Use packaging mode when the output will be copied, archived, or deployed:

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

That 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 --text

Open:

http://127.0.0.1:8083/dev_docs/

For a dynamic app example:

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

Then open:

http://127.0.0.1:8080/ucal/

Shared runtime configuration

The shared runtime configuration file usually lives at /etc/pharos/pharos.conf on packaged installs.

A typical first-time setup:

host=127.0.0.1
port=7323
db_backend=sqlite
db_path=/var/lib/pharos/pharos.sqlite3
apps_dir=/srv/pharos/apps
worker_count=8
worker_queue_capacity=256
required_env=SMTP_HOST,SMTP_FROM
secret_env=PHAROS_DB_PASSWORD,SMTP_API_KEY
error_report_path=/var/log/pharos/runtime.error.jsonl
backup_dir=/var/backups/pharos

By default, Pharos resolves worker-pool sizing from the host:

worker_count defaults to the detected online CPU count, clamped to 1..256
worker_queue_capacity defaults to floor(total_physical_memory_bytes / 8 MiB), clamped to 32..8192
if physical memory cannot be detected, worker_queue_capacity falls back to 128

Set worker_count or worker_queue_capacity explicitly in pharos.conf when you want a fixed concurrency or overload budget instead of the host-derived default.

App-local config lives beside the app manifest as <app>/app.conf and typically sets values like:

base_path=/ucal
state_dir=/var/state/pharos
log_path=/var/log/pharos/ucal.log

Database-backed apps

Pharos stores dynamic app data in the configured database backend.

db_backend=sqlite is the default packaged setup
the canonical packaged SQLite path is /var/lib/pharos/<app_id>.sqlite3 when the app owns its own database
PostgreSQL can be configured per app where the app contract allows it
Pharos does not treat JSON scratch exports as the source of truth when a relational backend is active

Database commands

Use these commands to prepare and verify an app database:

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

Validation commands

After building or updating an app, common checks include:

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

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.

Health checks

Pharos exposes these standard probe endpoints:

/health
/ready
/live

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