CLI

Install, authenticate, control sessions, and run the external MCP server from the CLI.

The Happier CLI is the power-user client for:

installing and updating Happier
authenticating to one or more servers
selecting a default server profile or targeting one command
creating, listing, resuming, attaching to, and managing sessions
running the external Happier MCP server
inspecting Happier tools and action-driven workflows

Install

curl -fsSL https://happier.dev/install | bash

Public installer lanes:

stable: curl -fsSL https://happier.dev/install | bash -> happier
preview: curl -fsSL https://happier.dev/install-preview | bash -> hprev
dev: curl -fsSL https://happier.dev/install-dev | bash -> hdev

Windows (PowerShell):

irm https://happier.dev/install.ps1 | iex

npm fallback (power-user / Node workflow):

npm install -g @happier-dev/cli

Important:

npm installs expose the npm dist-tags (@latest and @next).
The rolling dev lane is installer-managed (install-dev / hdev), not a separate npm dist-tag.

Authenticate

happier auth login

happier auth login prints both web and mobile connection options (URLs). By default it prints a single QR code for the mobile deep link, plus the web URL as a fallback. When using self-hosted servers, run login against the correct server profile (see below).

Recommended first-run flow:

Use the mobile app path first (QR/deep link) to sign in/create account and approve terminal connection.
If you already use Happier on another device, sign in with that same account.
If you open a terminal-connect link while logged out, Happier routes you through sign in and then returns you to terminal approval automatically.

Notes:

The CLI never needs your secret key directly. For device-key accounts, restore happens in the app (mobile/web UI).
On enterprise/keyless deployments (mTLS or keyless OAuth), the same happier auth login flow works; the browser/app will use whatever the server advertises via GET /v1/features.
Terminal connect is separate from account restore. In the app, use Scan QR to connect terminal only for terminal/daemon approval. To sign a phone into the same account, use Add your phone on an already-signed-in desktop/web app and Restore account on the phone.
If the mobile QR/deep link does not include a server URL, your current server is probably loopback-only (localhost / 127.0.0.1). Configure the phone to a reachable server URL first, then retry.

Advanced:

To also print optional “configure server” links (rarely needed): happier auth login --print-configure-links
To stop waiting for approval after a fixed time instead of waiting indefinitely: happier auth login --wait-timeout <seconds>. The sign-in request stays approvable — rerun happier auth login to finish it. Guided setup uses this so it can hand the terminal back.

User guide: Features → Device linking & restore

Remote machine pairing (SSH, automated)

If you want to run Happier on a remote machine (VPS, home server, dev box) but approve/authenticate it from a machine where you're already signed in:

happier auth pair-remote --ssh user@host

Notes:

This orchestrates a claim-gated pairing flow over SSH (remote request → local approve → remote wait).
Add --json for machine-readable output.
Add --server ... or --server-url/--webapp-url to choose the local relay profile/account used for approval.
If your selected relay is local-only (localhost / 127.0.0.1), interactive mode offers reachable addresses for this computer (Tailscale Serve, direct Tailscale IP, LAN IP) plus Custom. In scripts, pass the address the remote machine should use to reach this computer's relay: happier auth pair-remote --ssh user@host --server-url-for-remote https://relay.example.com.
--remote-server-url remains available as a legacy alias for --server-url-for-remote.
For remote Windows hosts, make sure the Happier CLI command is available in the SSH session. If the command is not named happier, pass --remote-command hdev or the installed command name.

Pairing (JSON, manual / scripting)

Split the flow when you want full control (automation, custom SSH, etc):

# On the remote host (prints a request + publicKey)
happier auth request --json

# On a local machine that's already authenticated (approves the public key)
happier auth approve --public-key <publicKey> --json

# Back on the remote host (waits, claims, and writes credentials)
happier auth wait --public-key <publicKey> --json

This is terminal/CLI pairing, not the same flow as device restore inside the app.

Guided first run

happier setup

On a fresh interactive install, the installer continues directly into happier setup. Run it yourself when the installer was unattended, you skipped the guided step, or sign-in did not finish. Setup asks where your relay lives, points this computer at it, and runs the sign-in. It leaves an already-finished computer alone only when a relay is selected, the relay still accepts the stored sign-in, and this machine is registered against it. Credentials the relay has since rejected, or credentials with no registered machine behind them, are what setup exists to repair, so they do not count as configured.

Flag	Effect
`--cloud`	Use Happier Cloud without being asked
`--relay <url>`	Use a relay you already run
`--this-computer`	Install a relay on this computer and use it
`--yes`	Ask nothing, do everything that needs no answer, stop at the sign-in
`--non-interactive`	Change nothing, and say what would be needed

--yes and --non-interactive ask for opposite things, so they cannot be combined.

--yes runs the steps that have an answer already: it points this computer at the relay you named and, for --this-computer, installs the relay here. It then stops, because signing in has to be approved on your phone or in a browser and nothing on the command line can approve it for you. Setup names happier auth login and exits non-zero — the binary installed, the guided setup did not finish. It needs one of --cloud, --relay <url> or --this-computer: your account lives on whichever relay is chosen, so setup will not choose one.

--non-interactive writes nothing at all. It is also how setup reads HAPPIER_NONINTERACTIVE=1 and a run with no terminal, which is what installers and CI set for a whole run — a machine that is only passing through does not get an account created on it. Ask for the work explicitly with --yes.

Choosing to host the relay on this computer adds a reachability step, before and after the install: setup says whether Tailscale is running here, installed but stopped, or not installed at all, and what that means for your phone. A relay your phone cannot reach is otherwise only discovered later, and from somewhere else. When Tailscale is absent, setup offers to set it up — opt-in, defaulting to no. On macOS and Windows it opens the download page; on Linux it prints the install docs and moves on.

That install also creates a master secret in the relay's data directory the first time the relay starts, and says so once, there. It encrypts what the relay stores, is saved nowhere else, and cannot be regenerated — keep it with your backup of the relay's database.

When the relay ends up reachable from this computer only — no Tailscale, or a loopback address — setup signs in through this computer's browser rather than offering the app. Terminal links deliberately drop an address no other device can reach, so the phone would be left pointing at whichever relay it already had. Once the relay has an address your phone can reach, happier auth login offers both routes again.

Setup finishes by checking for an installed coding agent. Finding none is a warning, not a failure — you can finish setup and install one afterwards.

Check and repair this machine

happier status reads the whole chain between you and a working session — account, relay registration, automatic startup, CLI channel — and changes nothing. happier doctor repair fixes what it can. Both are covered in Check your setup, along with the happier service commands that manage automatic startup.

Notifications from a script

Send a notification to your own devices from anywhere a shell runs — the end of a long build, a cron job, a deploy:

happier notify -p "Deployment complete!"
happier notify -p "Database connection restored" -t "Alert"

-p is the message and -t an optional title.

Automations

Trigger a saved automation without opening the app:

happier automation run <automation-id> [--idempotency-key <key>] [--json]

Pass --idempotency-key when the caller might retry — a repeated key will not run the automation twice.

Plugins

happier plugins list [--json]

This version of Happier does not support installing plugins; the command exists so that tooling asking about plugins gets a clean, empty answer rather than an unrecognised-command error. It always lists nothing.

Server profiles

Save and switch servers

happier server list
happier server current
happier server add --name company --server-url https://api.company.example --webapp-url https://app.company.example --use
happier server use company

--use (and happier server use ...) sets the default server for future commands, so you can usually omit --server ... once it’s selected.

Target a server for one command

Use per-invocation targeting when you do not want to switch the default:

happier --server company auth login
happier --server personal daemon status

You can also use URL flags:

happier --server-url https://api.company.example --webapp-url https://app.company.example auth login
happier --server-url https://api.company.example --webapp-url https://app.company.example auth pair-remote --ssh user@host --json

happier logout is deprecated and prints a notice saying so. Use happier auth logout.

Daemon (background mode)

For always-on background sessions, remote control, and headless servers, see Daemon.

Attach to an existing session

If a supported session is already running, you can reattach to that same live session from a terminal:

happier attach
happier attach <session-id>

This is the main “start in the app, continue in the terminal” workflow. In a supported TTY, happier attach opens an interactive picker of active sessions:

local attachable sessions are selectable immediately
active but non-attachable sessions stay visible but disabled with a reason
remote-capable provider sessions are marked as remote; press P in the picker to run a reachability check before attaching

If the session is stopped, use happier resume instead.

Important notes:

tmux and other terminal-host attach flows work only for sessions that are still owned by the current machine.
You must target the same Happier account/server profile that owns the session.

Attach strategy depends on the provider:

Some providers use Happier's tmux-backed attach flow.
OpenCode uses a provider-native attach flow for server-backed sessions.

For OpenCode, the supported reattach command is still happier attach <session-id>. Do not rely on a raw vendor opencode attach ... command as your normal Happier workflow.

Supported attach styles include:

tmux-backed sessions on machines where tmux is enabled
Windows Terminal or Console hosted sessions on Windows
provider-native attach for supported provider sessions such as OpenCode

For the full workflow, see Features → Attach to a running session.

Resume an inactive session

If a Happier session is inactive but still vendor-resumable, you can resume it directly from the CLI.

Interactive selector

happier resume

In a supported TTY, Happier shows an interactive picker of resumable inactive sessions.

Resume by id

happier resume <session-id>

You can use a full session id or an unambiguous prefix.

Important behavior:

resume is strict: if the provider resume fails, Happier errors instead of starting a fresh session
archived or already-active sessions cannot be resumed
the command restores the session working directory before launching the provider again

For the full user guide and the meaning of “resumable”, see Features → Resume inactive sessions.

List sessions

Use:

happier session list

The default output is a table that includes session id, agent, recent activity, active state, resume state, title, and path.

Useful variants:

happier session list --resumable
happier session list --plain
happier session list --json

--resumable filters to sessions that can currently be resumed
--plain restores the older one-line output
--json is for scripting

Session control (non-interactive)

The happier session ... command group is the non-interactive surface for creating and controlling sessions.

Deep reference: CLI sessions.

Create a session (scriptable)

happier session create --title "My session" --message "Hello"

Optional targeting:

happier session create --path /path/to/repo --backend <backend-target-key> --tag <tag>

--backend expects a backend target key (not a short name). Common forms:

# Built-in catalog agent
happier session create --backend "agent:<agent-id>"

# ACP backend target (e.g. opencode, gemini, etc)
happier session create --backend "acpBackend:<backend-id>"

Send messages

happier session send <session-id> "ping"

Wait for an agent response (useful for scripts; can time out if the agent is busy/offline):

happier session send <session-id> "ping" --wait --timeout 60

Status, stop, archive

happier session status <session-id>
happier session history <session-id>
happier session wait <session-id> --timeout 60
happier session stop <session-id>
happier session archive <session-id>
happier session unarchive <session-id>

Set title / model / permission mode

happier session set-title <session-id> "New title"
happier session set-model <session-id> <model-id>
happier session set-permission-mode <session-id> <mode>

<mode> accepts common aliases (for example ask, default, yolo). Use --json to script and see the normalized permissionMode value.

Session id prefixes

Commands that accept <session-id-or-prefix> allow an unambiguous prefix of a full session id.

If the prefix matches multiple sessions, the command fails with candidates.

Approvals from CLI commands

Some actions can be configured as approval-gated on the CLI surface.

In that case, the CLI command does not execute immediately; it creates an approval request instead. Use the app’s Inbox to review/approve/deny and see the final execution result:

For advanced automation, approvals can also be decided through the generic action executor:

happier session actions execute <session-id> approval.request.decide --input-json '{"artifactId":"<id>","decision":"approve"}' --json

Action catalog from the CLI

You can inspect and execute Happier actions directly:

happier session actions list
happier session actions describe <action-id>
happier session actions execute <session-id> <action-id> --input-json '<json>'

Execution runs (review / plan / delegate / voice agent)

Execution runs are the structured “run” layer for multi-step flows in a session (for example: start a review run, then send follow-up messages, then stop).

happier session run list <session-id>
happier session run start <session-id> --intent <intent> --backend <backend-target-key>
happier session run send <session-id> <run-id> "message"
happier session run stop <session-id> <run-id>

External MCP control surface

If you want an MCP host (editor/agent) to control Happier sessions and actions, run the external MCP server:

happier mcp serve

happier mcp start is accepted as a compatibility alias, but serve is the canonical command name in the docs and CLI help.

Guide: Happier MCP (external)

Backend profiles

The CLI supports backend profiles for session starts and profile discovery:

happier profiles list
happier claude --profile deepseek
happier codex --profile openai

For the full guide, see Features → Profiles.

Happier tools

The CLI also exposes the unified Happier tools surface directly.

Use it when you want to:

inspect which built-in Happier tools are currently available
inspect which custom MCP tools resolve in the current machine/workspace context
call one of those tools directly from the terminal

List tools

happier tools list

Optional:

happier tools list --directory /path/to/project

This lists:

built-in Happier tools
custom MCP tools that resolve for the selected directory and machine

list does not require a session id.

Call a tool

happier tools call --session-id <session-id> --source happier --tool action_spec_search --args-json '{"query":"plan mode","limit":5}'

Examples:

--source happier --tool review_start
--source happier --tool subagents_plan_start
--source happier --tool action_spec_get
--source happier --tool action_options_resolve
--source playwright --tool browser_navigate

Use the Happier built-in discovery tools when you do not know the exact action id or valid option values yet.

For the broader product model, see Happier tools & actions.

Multi-server reference

For full multi-server and multi-daemon guidance, see Features → Multi-server.