Auth (dev-auth seeding)

Why auth seeding exists

Most workflows are easier if you authenticate once and then reuse that identity across stacks:

• you don’t need to re-login every time you create a new stack
• PR stacks can be created/reused quickly (hstack stack pr … --seed-auth)

hstack’s recommended pattern is a dedicated seed stack called dev-auth.

Auth seeding is best-effort and intentionally does not copy entire databases between stacks; it focuses on:

• credentials/config files that the UI/CLI expect
• minimal DB rows when needed (so stacks start cleanly)

Create the seed stack (recommended)

hstack auth seed

If you need to re-authenticate an existing seed stack (for example, credentials are stale/incorrect but the CLI says “already authenticated”), run:

hstack auth seed --force

This runs the full guided flow to:

• create the dev-auth stack (as a fresh identity)
• guide you through UI login so the seed is immediately usable
• optionally persist defaults so future stacks can reuse it automatically

If you want a non-interactive run (for scripting), check:

hstack auth seed --help

Make it the default seed (recommended)

If you want new stacks to auto-seed when they look uninitialized, set these in your home overrides:

• HAPPIER_STACK_AUTH_SEED_FROM=dev-auth
• HAPPIER_STACK_AUTO_AUTH_SEED=1

Typically these live in:

• ~/.happier-stack/env.local

See /docs/hstack/paths-and-env for env file precedence.

Use the seed for a specific stack

To seed auth into a stack:

hstack stack auth <stack> copy-from dev-auth

If you prefer to keep the credentials in sync (less isolation, more convenience), you can symlink auth files:

hstack stack auth <stack> copy-from dev-auth --link

Copy vs link:

• copy (default): more isolation, safer for tests
• link: more convenience (keeps credentials in sync), but stacks share auth state

Seed many stacks at once

hstack auth copy-from dev-auth --all --except=main,dev-auth

For full-server stacks (happier-server), seeding may require Docker infra to be running.

Store the UI dev key (optional)

Some UI automation flows need a local “dev key” stored on your machine:

hstack auth dev-key --set "<key>"
hstack auth dev-key --print

Tip: --print is what you want when logging in from the UI or handing a key to an agent.

Help:

hstack auth --help

Login (local-first)

hstack auth login authenticates the current stack (defaults to main).

In a TTY, hstack auth login is local-first:

• it prefers authenticating against your local stack (not the hosted Happier app)
• it guides you through opening the stack’s web UI and connecting your terminal
• if the stack isn’t running, it can start it in the background for you

Basic:

hstack auth login

If you’re working with a non-main stack:

hstack stack auth <stack> login

To force re-authentication:

hstack auth login --force
hstack stack auth <stack> login --force

Web app targeting

Control what UI origin is used for the login browser flow:

hstack auth login --webapp=auto|stack|expo|public|hosted
hstack auth login --webapp-url=http://localhost:8081

Notes:

• auto (default): guided local-first in TTY contexts
• stack: force using your stack’s web UI origin (env override → running Expo → stack server)
• expo: use a running Expo dev server’s web UI (fails if no Expo web app is running)
• public: use the stack’s public/server URL
• hosted: use the happier-cli default web app URL (no stack override)

Starting the stack when needed

If the stack isn’t running, hstack auth login will prompt to start it. To auto-start without prompting:

hstack auth login --start-if-needed