Platform Management CLI — Design Document &ZeroWidthSpace;

ADR: 0035

ADO: AB#4328 (Epic), AB#4329–AB#4332 (Stories/Tasks)

Status: Accepted — Implementation pending

Last updated: 2026-06-23

Overview &ZeroWidthSpace;

The hch CLI is a Node.js command-line tool for Heritage Virginia platform administrators. It provides a scriptable interface to member management, platform health, and developer utilities — all via the same REST API that the web app consumes.

Command Structure &ZeroWidthSpace;

hch <command> [subcommand] [options]

Top-level commands &ZeroWidthSpace;

Command	Description
`hch users`	Member account management
`hch health`	Platform health check
`hch seed`	Development data seeding
`hch config`	CLI configuration (token, API URL)

`hch users` &ZeroWidthSpace;

hch users list                    List all members with status
hch users list --status pending   Filter by status
hch users approve <id>            Approve a pending member account
hch users suspend <id>            Suspend an active member account
hch users show <id>               Show full member record

`hch health` &ZeroWidthSpace;

hch health                        Print all service statuses from /health
hch health --json                 Output raw JSON response
hch health --watch                Poll every 30s (Ctrl+C to stop)

`hch seed` &ZeroWidthSpace;

hch seed                          Seed default test data (dev/staging only)
hch seed --reset                  Drop existing seed data then re-seed

`hch config` &ZeroWidthSpace;

hch config set token <token>      Store API token in ~/.hch/config.json
hch config set api-url <url>      Override default API URL
hch config show                   Print current config (token masked)

Authentication Model &ZeroWidthSpace;

Token type &ZeroWidthSpace;

A long-lived API token, distinct from Clerk session JWTs. Properties:

Scoped to the admin role
Generated in the admin portal (UI TBD in AB#4332)
Stored server-side in the ApiToken table (to be designed in a follow-on story)
Sent as Authorization: Bearer <token> on every API request
Revocable from the admin portal at any time
Default expiry: 90 days (configurable per token)

Token storage (client side) &ZeroWidthSpace;

Stored in ~/.hch/config.json with permissions 0600. The CLI warns if the file is world-readable.

json

{
  "apiUrl": "https://api.heritageva.app",
  "token": "<redacted in display>"
}

API-side enforcement &ZeroWidthSpace;

The API validates the token via a requireApiToken middleware (separate from requireAuth which validates Clerk JWTs). Token middleware:

Reads Authorization: Bearer <token> header
Hashes the token and looks it up in the ApiToken table
Checks expiry and revocation status
Attaches user context (same shape as Clerk session) to the request
Writes an audit log entry for every token-authenticated request

Distribution &ZeroWidthSpace;

GitHub Releases &ZeroWidthSpace;

Binary: compiled Node.js bundle via @vercel/ncc or pkg
Platforms: linux-x64, darwin-arm64, darwin-x64, win-x64
URL pattern: https://github.com/Heritage-Virginia/heritage-community-hub/releases/latest
Release asset naming: hch-{platform}-{arch}-v{version}

npm (future) &ZeroWidthSpace;

npm install -g @heritage-virginia/hch

Package would be published to the public npm registry or a private GitHub Packages feed.

Install instructions (surfaced in AdminCliToolsPage) &ZeroWidthSpace;

bash

# macOS / Linux — download latest release
curl -fsSL https://github.com/Heritage-Virginia/heritage-community-hub/releases/latest/download/hch-linux-x64 -o /usr/local/bin/hch
chmod +x /usr/local/bin/hch

# Configure
hch config set token <your-admin-token>

Project Structure &ZeroWidthSpace;

apps/cli/
  src/
    index.ts          # CLI entry point (yargs / commander)
    commands/
      users.ts
      health.ts
      seed.ts
      config.ts
    lib/
      api-client.ts   # thin wrapper around the REST API
      config.ts       # reads/writes ~/.hch/config.json
      output.ts       # table + JSON formatting
  package.json
  tsconfig.json

AdminCliToolsPage &ZeroWidthSpace;

Route: /app/admin/cli-tools — admin-only

The page shows:

Status banner: "Coming Soon — tracked in AB#4328"
Planned command table (command + description)
Install snippet (placeholder until first release)
Link to GitHub Releases page

Implementation: apps/web/src/pages/admin/AdminCliToolsPage.tsx

ADR 0035 — governing decision
ADR 0034 — platform status dashboard (hch health mirrors /health)
ADR 0006 — RBAC (admin token scope)
apps/cli/ — implementation (AB#4328–AB#4332)
apps/api/src/schemas/responses.ts — HealthResponseSchema consumed by hch health