CLI

Developer/operator helper command package.

Responsibilities:

• build release artifacts;
• call PentagonHub Core for release import, deploy, capture, rollback, and status;
• support CI workflows;
• run local Dev push/watch and Live capture workflows through PentagonHub Core;
• print actionable diagnostics for operators.

The CLI must run on a developer machine or in CI. It must not assume it is running inside Home Assistant.

The CLI is the normal entry point when a developer is working in a local project folder. PentagonHub Center remains the admin, approval, audit, and recovery UI.

The developer entry point contract is documented in docs/DEVELOPER_ENTRY_POINTS.md.

Public npm Usage

The intended public package name is pentagonhub. The normal first run from a developer machine is:

npx pentagonhub@latest setup --project HA1004 --token ph_pat_... --core-api-url https://center.pentagonhub.com

Inside this monorepo, use the workspace wrapper instead:

npm run cli -- setup --project HA1004 --token ph_pat_... --core-api-url http://127.0.0.1:3100

Before publishing, verify the package contents:

npm run cli:pack

The publishable package is prepared under tmp/npm-pentagonhub/. It contains only the bundled CLI runtime and README; Core, Center, Worker, tests, snapshots, operator scripts, and local secrets must not be included.

Implemented Commands

Initialize Local Project Repository

npm run cli -- init --project HA1004 --core-api-url http://127.0.0.1:3100
npm run cli -- init --project HA1004 --directory ./HA1004 --core-api-url http://127.0.0.1:3100

The command creates the standard unified customer repository layout:

pentagonhub.json
config/
context/
assistant/
tools/
.gitignore
.env.example
README.md
AGENTS.md
package.json

Defaults:

• deploy root: config/;
• context root: context/;
• captures root: captures/;
• default Live: live;
• default Dev/watch target: dev.

Existing files are skipped by default. Use --force to regenerate them.

Set Up Local Project From Center Token

npm run cli -- setup --project HA1004 --token ph_pat_... --directory ./HA1004 --core-api-url http://127.0.0.1:3100

The command is the normal first step after creating a Project API Token in PentagonHub Center. It:

• validates the token through PentagonHub Core;
• selects the requested Project, or the only Project visible to the token;
• discovers default Dev/Live environments from Core;
• creates the same local repository layout as init;
• writes PENTAGONHUB_CORE_API_URL and PENTAGONHUB_CLI_TOKEN to ignored .env.local.

The raw token is never written to pentagonhub.json, generated docs, or stdout. Existing scaffold files are skipped unless --force is used. Existing .env.local values are updated in place while preserving unrelated variables.

Transfer Managed Files

npm run cli -- transfer --source HA1004/live --target HA1004/dev
npm run cli -- transfer --project HA1004 --source live --target dev-ai
npm run cli -- transfer --source HA1004/dev --target HA1004/live --confirm HA1004/live

The command calls PentagonHub Core and creates the same durable transfer operation that PentagonHub Center uses. It does not connect to Home Assistant, the worker, Docker, Caddy, or SSH directly.

Configuration:

PENTAGONHUB_CORE_API_URL=http://127.0.0.1:3100/api
PENTAGONHUB_CLI_EMAIL=<developer-email>
PENTAGONHUB_CLI_PASSWORD=<developer-password>

During local bootstrap the CLI falls back to DEV_ADMIN_EMAIL and DEV_ADMIN_PASSWORD. Passwords must stay in ignored .env files or the OS environment, not in git.

The Core API URL has no implicit default. Set it with --core-api-url, PENTAGONHUB_CORE_API_URL, or committed pentagonhub.json -> core_url.

Optional committed project config:

{
  "core_url": "https://center.pentagonhub.com/api",
  "project_code": "HA1004",
  "deploy_root": "config",
  "captures_root": "captures",
  "context_root": "context",
  "default_dev": "dev",
  "default_live": "live",
  "default_watch_target": "dev"
}

The CLI discovers pentagonhub.json by walking up from the current directory. Config paths such as deploy_root are resolved relative to the directory that contains pentagonhub.json.

Capture Managed Files

npm run cli -- capture --source HA1004/live
npm run cli -- capture --source HA1004/live --to ./captures/live-20260719
npm run cli -- capture --project HA1004 --source dev --to ./captures/dev

The command creates a Core capture operation, waits for the source HA to export managed files, downloads the resulting artifact through the authenticated Core API, and extracts the files/ payload locally.

Safety rules:

• without --to, output goes to deploy_root, normally config/;
• default deploy_root output requires a git repository and a clean deploy root before writing;
• explicit --to must point to a missing or empty review directory;
• only managed paths from the artifact contract are extracted;
• path traversal and manifest hash mismatches are rejected;
• existing local files are not overwritten in explicit --to review mode.

Push Local Files To Dev

npm run cli -- dev push --target HA1004/dev --from ./config
npm run cli -- dev push --project HA1004 --target dev

The command builds a temporary artifact from the local deploy root, uploads it to PentagonHub Core, and waits for the target Dev HA to apply it through SSE notification and authenticated HTTP command claim.

Safety rules:

• target must be a Dev installation;
• only managed paths are included;
• denied paths such as secrets.yaml, .storage/, databases, logs, and auth data abort the command before upload;
• files outside the managed contract, such as README.md, are ignored.

Watch Local Files To Dev

npm run cli -- dev watch --target HA1004/dev --from ./config
npm run cli -- dev watch --project HA1004 --target dev
npm run cli -- dev watch --target dev --no-initial-sync

The command runs an initial dev push by default, then watches the local deploy root and sends managed file saves as ha.files.apply_delta commands through PentagonHub Core.

Rules:

• target must be a Dev installation;
• only managed paths are sent;
• denied files abort the changed batch;
• non-managed files are ignored;
• Chokidar normalizes atomic saves and waits briefly for chunked writes to settle before the existing debounce window;
• one single-flight queue keeps only the latest observed state for each path;
• a process-local SHA256 cache suppresses repeated content and is bounded to 50,000 applied paths;
• changed files are sent in batches of up to 20 files;
• each inline file must be 128 KB or smaller.

The SHA256 cache contains paths and hashes, not file contents. It is cleared when the watcher stops. A successful initial dev push seeds the cache; --no-initial-sync learns each path after its first successful delta.

Pull HA Context

npm run cli -- context pull --source HA1004/live
npm run cli -- context pull --project HA1004 --source dev

The command asks PentagonHub Core to route ha.context.export to the selected HA integration, downloads the resulting temporary JSON artifact through the authenticated Project operation, verifies its hash, and writes the catalogs locally.

Default output:

context/ha/<environment>/
  entities.current.json
  entity_registry.current.json
  devices.current.json
  areas.current.json

Use --to DIRECTORY to override the output directory. These files are Project context for review and AI; they are not deployable HA config.

Synchronize Dev Runtime

npm run cli -- sandbox preview --source HA1004/live --target HA1004/dev
npm run cli -- sandbox sync --source HA1004/live --target HA1004/dev
npm run cli -- sandbox sync --source live --target dev --reset-state
npm run cli -- sandbox status --target HA1004/dev
npm run cli -- sandbox clear --target HA1004/dev

Preview and sync always use explicit source and Dev target environments through Core. The CLI does not connect to HA, Worker, Docker, MQTT, or SSH. Sync preserves matching mutable sandbox state by default; --reset-state reapplies the source state. Status requires sandbox_read; mutating commands require sandbox_sync.

Build And Deploy Releases

npm run cli -- release build --from ./config
npm run cli -- release deploy --target HA1004/live --confirm HA1004/live --force
npm run cli -- release deploy --target HA1004/live --artifact ./.pentagonhub/releases/VERSION.zip --confirm HA1004/live

When --artifact is omitted, release deploy builds a new local release from the deploy root before importing it into PentagonHub Core. Live deploy requires --confirm PROJECT/environment.

Use --force only when reviewed Live drift or initial unmanaged files may be overwritten. Use --adopt-matching-drift when Live already matches the target release and the drift should become official without a force overwrite.

Roll Back Live

npm run cli -- release rollback --target HA1004/live --to previous --confirm HA1004/live
npm run prod:rollback -- --target HA1004/live --to previous --confirm HA1004/live

The command calls the same PentagonHub Core rollback endpoint used by PentagonHub Center, then waits on the job SSE stream while the target Live HA executes ha.release.rollback through authenticated HTTP command handling.

Safety rules:

• target must be a Live installation;
• rollback requires --confirm PROJECT/environment;
• --to defaults to previous and may also be a stored release version;
• --force is required if rollback would overwrite conflicting Live drift.