@health-universe/cli

Command-line interface for the Health Universe platform. Manage applications, deployments, organizations, and projects from your terminal.

Install

npm install -g @health-universe/cli

Quick Start

# Authenticate (opens browser)
hu login

# Check who you're logged in as
hu whoami

# List your applications
hu apps list

# Deploy an app and wait for it to finish
hu apps deploy <app-id> --wait

Authentication

The CLI authenticates via your browser using your existing Health Universe account. Tokens are valid for 24 hours.

# Log in (opens browser for Clerk auth)
hu login

# Log out (clears stored token)
hu logout

Credentials are stored in ~/.hu/credentials with 0600 permissions.

Commands

hu whoami

Show the authenticated user and active organization.

hu whoami
# User:  Jane Smith ([email protected])
# Org:   my-org

hu whoami --json

hu apps

Manage applications in the current organization.

# List all apps
hu apps list
hu apps list --json

# Check deployment status
hu apps status <app-id>

# Deploy an application
hu apps deploy <app-id>
hu apps deploy <app-id> --wait    # Poll until complete

# View logs
hu apps logs <app-id>             # Deployment logs
hu apps logs <app-id> --build     # Build logs

hu orgs

Manage organization context.

# List organizations
hu orgs list

# Switch active organization (by slug, falls back to ID)
hu orgs switch <slug>
hu orgs switch personal

hu projects

Manage projects within the active organization.

hu projects list
hu projects list --json

hu config

View and manage CLI configuration.

# Show current config
hu config show

# Set API URL
hu config set apiUrl https://apps.healthuniverse.com

# Set auth URL (for the browser login flow)
hu config set authUrl https://www.healthuniverse.com

Configuration is stored in ~/.hu/config.json.

Environments

The same CLI works for both production and local development:

# Production (default)
hu login

# Local development
hu login --api-url http://localhost:3002 --auth-url http://localhost:3000

Or set the environment permanently:

hu config set apiUrl http://localhost:3002
hu config set authUrl http://localhost:3000
hu login

JSON Output

All read commands support --json for machine-readable output, useful for scripting:

hu apps list --json | jq '.[].name'
hu apps status <id> --json
hu whoami --json
hu config show --json

Development

# From the monorepo root
cd packages/cli

# Build
yarn build

# Watch mode
yarn dev

# Type check
yarn check:type

# Run locally without installing globally
node dist/index.js --help

Releasing a new version

Releases are driven by changes to this workspace. When you land a CLI change, you're also responsible for the three files that control the release:

1. Your code change in src/
2. Version bump in package.json (version field, semver — see below)
3. CHANGELOG entry in CHANGELOG.md describing what changed

All three should land on main together (same PR or stacked PRs) before cutting the release.

Picking a version bump

The CLI is pre-1.0, so:

| Kind of change | Bump | |---|---| | Renames or removes a command/flag, changes output format that scripts might parse | minor (pre-1.0 breaking) | | New command, new flag, new feature | minor | | Bug fix, internal refactor, dependency bump | patch |

CHANGELOG format

Prepend a new section under the # @health-universe/cli heading, matching the existing style:

## 0.5.0

### Minor Changes

- Added `hu apps domains verify` to check DNS propagation.

### Patch Changes

- Fixed empty output when no apps exist.

Keep bullets terse and user-visible — these become the GitHub Release notes and show up on npm.

Publishing

After your PR merges to main, manually dispatch the Release CLI workflow:

gh workflow run release-cli.yml --ref main

Or via the GitHub UI: Actions → Release CLI → Run workflow.

The workflow:

1. Reads the version from packages/cli/package.json
2. Skips if cli-v<version> is already tagged or on npm (safety net against double-dispatch)
3. Publishes to npm via OIDC trusted publishing (no token needed)
4. Creates the cli-v<version> git tag
5. Creates a GitHub Release, using the matching CHANGELOG section as the body

Do not run npm publish locally or push cli-v* tags manually — the workflow owns both, and a stray tag makes it skip the real publish.