HigherDEV CLI

Operator controls for HDX workspaces, tickets, agents, and runner hosts.

Install

npm install --global @higherdev/cli

Sign in with a personal key:

hd login --url https://hdx-higher-ops.vercel.app

That opens the browser. Approve the device to store a personal API key. Scripts can still pass a key directly:

hd login --url https://hdx-higher-ops.vercel.app --api-key hdx_... --slug workspace

Workspace keys are for runners. Previous single-workspace and workspace-map config shapes are migrated automatically when they are read.

Commands

| Command | Purpose | | --- | --- | | hd | Open the live TUI when attached to a terminal | | hd --help | Show the HigherDEV banner and usage | | hd status | Show workspace, ticket, run, and decision status | | hd usage [--since 7d] [--until DATE] [--json] | Agent usage for a window: runs, consults, reviews, and chats | | hd backlog [show ID \| approve ID \| decline ID \| set ID \| new] | Review and manage emergent work proposals | | hd ticket list | List tickets | | hd ticket show KEY [--json] | Show one ticket (body, acceptance, timeline, messages, PR, runs, decisions) | | hd ticket new [PATH.md] | Create a ticket from the guided form or a Markdown spec | | hd ticket new --title TITLE [--acceptance TEXT] [options] | Create a ticket non-interactively | | hd ticket queue KEY | Queue a complete ticket now | | hd ticket cancel KEY | Cancel a ticket | | hd ticket set KEY --assignee EMAIL | Assign a ticket to a member | | hd ticket set KEY --host HOST | Address a ticket to a host | | hd ticket set KEY --provider PROVIDER | Move a non-running ticket to another provider | | hd epic new PATH [--title TITLE] [--surface web\|cli\|mobile\|none] [--draft] | Create an approved epic, or keep it as a draft | | hd epic list | List epics and ticket progress | | hd epic show ID | Show one epic, its progress, and measured outcomes | | hd epic approve ID | Open a draft epic for Delivery Manager decomposition | | hd epic rm ID | Remove a draft epic | | hd epic set ID --surface web\|cli\|mobile\|none | Set the user-facing surface; a surfaced epic gets a Designer UX brief | | hd dm | Point to the TUI Delivery Manager conversation | | hd pm | Point to the TUI Product Manager conversation | | hd workspace ls | List every workspace available to the configured key | | hd workspace use SLUG | Switch the current workspace | | hd workspace new --name NAME --repo OWNER/NAME [options] | Preflight GitHub, wire the runner, and create a paused workspace | | hd workspace set [options] | Update settings; chat timeout uses --chat-timeout-minutes N | | hd workspace rotate-key | Rotate the shared API key and save it locally | | hd workspace grant-runner-access [--runner-user USER] | Grant and confirm write-or-better access for the workspace runner | | hd agents | List agents | | hd agents add ROLE --provider P --model M [--fallback-for NAME] [options] | Add an agent or standby | | hd agents rm ROLE\|ID | Remove an unambiguous agent | | hd agents set ROLE\|ID [options] | Rename, configure, enable, or disable an agent | | hd notes [ROLE] | List durable agent notes, optionally for one role | | hd notes add ROLE TEXT | Add an owner-written note | | hd notes set ID TEXT | Edit an owner-written note | | hd notes rm ID | Remove a note | | hd caps [set PROVIDER N] | Show or update provider concurrency caps | | hd env ls | List workspace environment variable names | | hd env set NAME=VALUE [NAME=VALUE...] | Set workspace environment variables | | hd env rm NAME | Remove a workspace environment variable | | hd host ls | List hosts with owner and served workspaces | | hd host enroll HOST_ID | Create a one-hour, single-use host enrollment token | | hd host share --workspace SLUG | Let this host serve another workspace | | hd host unshare --workspace SLUG | Stop serving a workspace | | hd host roll [--host HOST] [--address ADDR] [--checkout DIR] | Pull, install, and restart a runner over SSH, then watch drain | | hd host runner-install | Register the default host as the org's self-hosted, hdx Actions runner | | hd host env ls | List environment variable names on the workspace's default host | | hd host env set NAME=VALUE [NAME=VALUE...] | Set host-only environment variables | | hd host env rm NAME | Remove a host-only environment variable | | hd logs KEY [-f] | Show or follow run events | | hd msg KEY "message" [--interrupt] | Message a builder | | hd attach PATH... --ticket KEY | Attach files or a folder to a ticket message | | hd attach PATH... --to dm\|pm | Attach files or a folder to a role chat | | hd inbox [--all] [--limit N] [--json] | List unread inbox messages, or earlier history with --all | | hd decide | List open decisions, with the recommendation inline | | hd decide ID --answer TEXT | Answer a decision | | hd decide ID --recommended | Accept the recommended option | | hd on / hd off | Turn the workspace on or off | | hd pause / hd resume | Pause or resume the workspace | | hd members ls | List members and pending invitations | | hd members invite EMAIL [--role member\|viewer] | Invite someone by email | | hd members set EMAIL --role ROLE | Change a member's role | | hd members rm EMAIL | Remove a member | | hd login [--url URL] | Open the browser, approve, and store a personal key | | hd login --url URL --api-key KEY [--slug S] | Configure this client with an existing key | | hd init --host HOST [--checkout DIR] [options] | Configure this host and runner service | | hd init --enroll TOKEN [--url URL] [options] | Enroll without receiving the HDX master secret | | hd upgrade --host HOST [--checkout DIR] [options] | Refresh this host configuration | | hd image "PROMPT" --out FILE.png [--size WxH] | Generate raster art, only when the workspace sets IMAGE_API_KEY |

hd init uses ~/hdx as its checkout by default. Pass --checkout DIR when the runner source is elsewhere. Pass --address HOST to store RUNNER_SSH_ADDRESS so hd host roll can SSH to that host. If the runner environment or service unit already exists, inspect the paths it prints and pass --force only when replacing that host configuration is intentional.

For a teammate, an owner runs hd host enroll HOST_ID and sends the printed command. The token is valid once for one hour. Enrollment writes only a revocable per-host key to runner.env; GH_TOKEN is optional, and the runner uses that person's existing gh auth login identity when it is absent.

hd init also provisions the host browser capability: Playwright with Chromium, installed under HDX_BROWSER_ROOT (~/.config/hdx/browser by default, or --browser-root DIR) and recorded in runner.env. The install is best effort and never fails the host; pass --no-browser to skip it. Without the capability the Designer visual review is skipped and reviews continue.

Windows hosts with WSL2

HDX supports Windows runner hosts through WSL2 only. Native Windows services are not supported. Running hd init in PowerShell or Command Prompt prints these setup steps and writes no files.

1. Open PowerShell as Administrator and install Ubuntu with wsl --install -d Ubuntu.

2. In Ubuntu, create or edit /etc/wsl.conf and enable systemd:

   [boot]
   systemd=true

3. Run wsl --shutdown in PowerShell, reopen Ubuntu, then install the CLI and run the provided hd init --enroll TOKEN command inside Ubuntu. HDX detects WSL2 from /proc/version, installs the normal Linux systemd unit, and reports the host platform as wsl2.

4. In Windows Task Scheduler, create a task triggered at logon. Set the program to wsl.exe and the arguments to:

   -d Ubuntu --exec /bin/sh -lc "systemctl --user start hdx-runner.service; exec sleep infinity"

   Configure the task not to stop on idle and not to start a second instance.

5. Keep the laptop plugged in. In Windows power settings, set plugged-in sleep to Never and set closing the lid to Do nothing so the laptop does not sleep while it is acting as a host.

All runner commands, credentials, checkouts, and service management stay inside Ubuntu under WSL2.

hd host roll SSHes to the host address (--address, or RUNNER_SSH_ADDRESS from the host heartbeat), pulls the checkout, installs, and restarts the systemd unit. The runner drains live runs for up to 15 minutes (RUNNER_DRAIN_TIMEOUT_MS) before force-closing leftovers. The systemd unit TimeoutStopSec is one minute above that drain timeout.

hd workspace new uses the operator's authenticated gh, defaults to the repository's real default branch, bootstraps an empty repository unless --no-bootstrap is set, and invites mel-ilotus with push access for user-owned repositories or admin for organization-owned repositories unless --runner-user USER overrides it. On a terminal, missing name or repo flags start a guided wizard. If the repository is missing, approve private creation interactively, use --create to force it, or --no-create to fail. Fully flagged calls remain non-interactive for scripts and Mel.

On a terminal, hd ticket new opens a guided form. It defaults the area from the newest ticket and offers the enabled builder providers. Body and acceptance accept Markdown lines until a blank line, then the form confirms creation and optionally queues the new ticket. hd ticket new PATH.md reads the first # heading as the title, optional area and provider front matter, and a ## Acceptance section as the acceptance criteria. Fully flagged ticket creation skips all prompts.

For workspaces created before runner access was wired automatically, run hd workspace grant-runner-access. It uses the operator's authenticated gh account, defaults to mel-ilotus, grants push on user-owned repositories or admin on organization-owned repositories, and confirms write-or-better access through GitHub's collaborator permission endpoint. The old grant-runner-admin name remains an alias.

hd env set and hd env rm also update GitHub Actions secrets on the current workspace repository. They require the operator's authenticated gh account to have repository admin permission. Secret values are sent to gh through stdin and are never printed.

Use hd host env set SUPABASE_ACCESS_TOKEN=... SUPABASE_ORG_ID=... once to let the runner provision Supabase for workspaces assigned to that host. Host values are never passed to builder processes. Use hd host env set VERCEL_TOKEN=... VERCEL_TEAM_ID=... to let the runner adopt or provision a linked Vercel project. It syncs NEXT_PUBLIC_*, names listed in settings.vercel.env, and existing Vercel-held names to production and preview. Later hd env set changes wake the Delivery Manager to update matching Vercel variables.

Inside the TUI, use /board, /inbox, /inbox more, /ticket, /ticket new [PATH.md], /queue, /cancel, /msg, /logs, /epic new, /epic approve, /epic rm, /epics, /pm, /dm, /decide, /agents add, /agents rm, /notes, /env, /settings, /workspace, /workspace new, /workspace set, /workspace rotate-key, /workspace grant-runner-access, /feed, /on, /off, /refresh, /help, or /exit. The display refreshes from the HDX API every five seconds.

/dm and /pm (the chats hd dm and hd pm point at) open a fixed pane: the messages scroll in every row the window has left, and the composer stays pinned on the last one to three rows, so a long reply and the input are on screen together. The newest message sits on the viewport's last row. With the composer empty, the arrow keys move a line and PageUp and PageDown move a screen; a scrolled back view says (older messages above) and holds its place when a reply lands, until it is scrolled to the bottom again.