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

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 --json

Notes:

This orchestrates a claim-gated pairing flow over SSH (remote request → local approve → remote wait).
Add --server ... or --server-url/--webapp-url if you're targeting a self-hosted server.

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.

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

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.

CLI