CLI reference

This page covers the small set of scripts and commands that are part of the public Jarvis operating surface.

`./restart.sh`

Restarts a local Jarvis instance from the repository root.

./restart.sh

What it does:

loads .env if present
resolves worktree-aware port and log paths
restarts the backend through the canonical startup path
waits for the local health endpoint to report success
prints the resolved local URL and log location

Use it when:

you have changed backend Python code
you want to restart a local development instance cleanly
you need Jarvis to rebind its local port and verify health

`scripts/generate_api_key.py`

Creates a new API key and stores only its hash in the database.

python scripts/generate_api_key.py -d "iPhone"
python scripts/generate_api_key.py --db data/jarvis.db --description "Desktop browser"

Key options:

-d, --description: human-readable label for the key
--db: database path, defaults to data/jarvis.db

Behavior:

fails if the database does not exist yet
prints the raw key once
does not allow the key to be retrieved later

`scripts/sync-version.py`

Synchronizes generated version surfaces from the root VERSION file.

python3 scripts/sync-version.py
python3 scripts/sync-version.py --check

Use it when:

preparing a release
updating the repository version number
verifying that generated manifests match VERSION

The root VERSION file is the human-edited source of truth. This script propagates that version into generated package and platform metadata.

`scripts/check-plan-lifecycle.py`

Validates lifecycle rules for files under docs/plans/active/.

python3 scripts/check-plan-lifecycle.py
python3 scripts/check-plan-lifecycle.py --suggest-archive
python3 scripts/check-plan-lifecycle.py --allow-split-doc-warnings

What it checks:

active plans must not already be marked done
active plans must have owner: frontmatter
deprecated or duplicate frontmatter is rejected
split checkpoint-style docs are flagged

This is primarily a maintainer workflow check rather than a runtime command, but it is part of the repository’s public script surface.

Docs-site commands

Run these from services/docs-site/.

`npm run dev`

Starts the Astro Starlight docs site in local development mode.

cd services/docs-site
npm run dev

`npm run build`

Builds the static docs site.

cd services/docs-site
npm run build

This also generates the search index used by the built site.

`npm run preview`

Serves the built static output locally.

cd services/docs-site
npm run preview

`npm run check:search`

Verifies that the built site contains the expected Pagefind search artifacts.

cd services/docs-site
npm run check:search

Practical sequencing

The most common local workflow is:

./restart.sh
python scripts/generate_api_key.py -d "Browser"
cd services/docs-site && npm run build

For release-oriented maintenance:

python3 scripts/sync-version.py --check
python3 scripts/check-plan-lifecycle.py --suggest-archive