Happier Docs
hstack (local stack)

CLI reference (high-signal)

The commands you’ll use most, with the important flags and patterns.

This is a concise reference. For conceptual docs, see:

  • /docs/hstack/development
  • /docs/hstack/stacks
  • /docs/hstack/worktrees-and-forks

Tip: most commands support --help and --json.

Core

  • Setup: hstack setup --profile=dev|selfhost
  • Run: hstack start / hstack dev
  • Interactive runner (preferred): hstack tui <...> (example: hstack tui stack dev dev --mobile)
  • Stop: hstack stop
  • Diagnose: hstack where, hstack doctor, hstack logs
  • Contribute: hstack contrib status|ensure-dev|sync|extract|pr

Common run flags (root commands):

  • --server=happier-server|happier-server-light
  • --restart
  • --no-ui, --no-daemon
  • --no-browser
  • --mobile
  • --expo-tailscale
  • --bind=loopback|lan (aliases: --loopback, --lan)

Stacks

Lifecycle:

  • Create: hstack stack new <name> [--interactive] [--db-provider=pglite|sqlite|postgres|mysql] [--database-url=<url>]
  • Edit: hstack stack edit <name> --interactive
  • List/info: hstack stack list, hstack stack info <name>
  • Run: hstack stack dev <name>, hstack stack start <name>
  • Stop: hstack stack stop <name>
  • Build UI: hstack stack build <name>
  • Diagnose: hstack stack doctor <name>

Pin a stack to a worktree/checkout:

  • hstack stack wt <name> -- use <spec>

Server flavor:

  • hstack stack srv <name> -- use happier-server-light|happier-server

Auth:

  • hstack auth seed (create the dev-auth seed stack)
  • hstack stack auth <name> status|login|copy-from

Stack-scoped app CLI (runs the Happier CLI/daemon in stack context):

  • hstack stack happier <name> -- <args...>

PR stacks:

  • hstack stack pr <name> --repo=<pr-url|number> [--dev|--start] [--server-flavor=light|full] [--db-provider=...] [--database-url=...]

Mobile (iOS)

  • Install the shared dev-client app (USB iPhone): hstack mobile-dev-client --install
  • Install an isolated per-stack app (Release, no Metro): hstack stack mobile:install <stack> [--device=...] [--name=...]
  • Regenerate native projects (Pods, deployment target patches): hstack mobile --prebuild [--clean]

See: /docs/hstack/mobile-ios.

EAS (Expo Application Services)

EAS wrapper (runs EAS CLI from apps/ui, best-effort ensures deps are installed):

  • Cloud build: hstack stack eas <stack> ios|android [--profile production] [--interactive|--non-interactive]
  • Pass-through: hstack stack eas <stack> <eas args...>

Sync stack env → EAS Environment Variables UI (project settings):

  • hstack stack eas <stack> env:sync --environment production [--dry-run] [--hide-values]

See: /docs/hstack/mobile-ios (EAS builds per stack).

Worktrees (wt)

Create worktrees (defaults to an upstream-based local worktree):

  • hstack wt new local/<slug> [--from=upstream|origin] [--base=<ref>] [--use]

PR worktrees:

  • hstack wt pr <pr-url|number> [--use] [--update] [--stash]

Select the active repo checkout:

  • hstack wt use <spec>

Status/list/update:

  • hstack wt status <spec>
  • hstack wt list
  • hstack wt update <spec>
  • hstack wt update-all

Push:

  • hstack wt push <spec|active> --remote=origin

Auth

  • hstack auth seed
  • hstack auth copy-from <seed> --all --except=main,dev-auth
  • hstack auth dev-key --print

See: /docs/hstack/auth.

Providers

List supported provider CLIs and whether auto-install is available on your platform:

  • hstack providers list

Install provider CLIs (best-effort):

  • hstack providers install claude,codex,gemini
  • hstack providers install claude codex gemini

Useful flags:

  • --dry-run / --plan (show what would run)
  • --force / --reinstall (re-run installer even if already installed)
  • --json (scripting)

See also: /docs/providers.

Remote

Provision a remote machine over SSH (install Happier, pair credentials, optionally install/start the daemon service):

  • hstack remote daemon setup --ssh user@host [--channel stable|preview] [--service user|none]

Provision a remote machine over SSH to run the self-hosted server as a managed service:

  • hstack remote server setup --ssh user@host [--channel stable|preview] [--mode user|system] [--env KEY=VALUE]...

See:

  • /docs/hstack/remote-daemon
  • /docs/hstack/remote-server

Self-host runtime (self-host)

Install and manage the self-host runtime (server + optional UI web bundle) as a managed service:

  • Install: hstack self-host install [--channel stable|preview] [--mode user|system]
  • Status: hstack self-host status
  • Manual update: hstack self-host update
  • Roll back: hstack self-host rollback --to <version>

Auto-update scheduling (opt-in):

  • Enable daily window: hstack self-host install --auto-update --auto-update-at=03:15
  • Change schedule after install: hstack self-host config set --auto-update --auto-update-at=03:15

Config inspection / tweaks:

  • View: hstack self-host config view
  • Set (and apply scheduler changes): hstack self-host config set ...
  • Set (write only): hstack self-host config set ... --no-apply

Contributor workflows (contrib)

These commands help you work with a long-lived dev/ checkout while still producing clean PR branches:

  • Ensure dev/ exists: hstack contrib ensure-dev
  • Sync dev/: hstack contrib sync
  • Extract a feature branch: hstack contrib extract <name> --mode=reset|stack [--push] [--open]
  • Print/open PR URL: hstack contrib pr <branch> [--open]

Maintainer tools

hstack includes “maintainer tools” as subcommands (setup-pr, review-pr, import, review, edison):

  • hstack tools --help

Monorepo porting

  • hstack monorepo port --help

See: /docs/hstack/monorepo-port.

Validation (typecheck, lint, test)

Run checks on the active checkout or stack-scoped (recommended).

Debugging (inspect + env knobs)

Where to look when something is “weird”: effective paths, pinned repo, ports, logs, and key env knobs.

On this page

CoreStacksMobile (iOS)EAS (Expo Application Services)Worktrees (wt)AuthProvidersRemoteSelf-host runtime (self-host)Contributor workflows (contrib)Maintainer toolsMonorepo porting