The hv command-line tool runs HyperView automation from a terminal, a script or an AI agent. This page covers signing in, sessions, every command and the capability it needs, and output you can safely parse.
The hv binary wraps the automation API in ready-made commands. It handles authentication and session bookkeeping for you and shells out cleanly from scripts in any language. Every command carries its own --help.
Authenticating
Credentials are an account UUID and an API key, which hv exchanges for a short-lived token. It looks for them in three places, and each piece falls through independently. The API key can come from the environment while the account UUID comes from the config file:
The
--account-uuidand--api-keyflagsThe
HV_ACCOUNT_UUIDandHV_API_KEYenvironment variables~/.config/hv/config.yaml
There is no separate logged-in state. If the environment variables are set, every command works without hv auth login ever being run. login exists to write the config file and cache a token for interactive use.
hv auth login # validate credentials and cache a token hv auth status # verify credentials, and report which source they came from hv auth logout # remove cached credentials
For an unattended runner, the environment variables are the better route: nothing is written to disk and there is no login step to fail. For which permissions the key needs, see API keys and their permissions.
Flags every command takes
Flag | What it does |
| Credentials, overriding the environment and the config file |
| Which console to talk to, overriding |
| Machine-readable output |
| Pins the |
| On a write command, prints the request it would send and exits without making a call |
| Request logging. Credentials are always redacted |
| Suppress non-essential output; disable ANSI color |
NOTE: check --console-url before the first run. A binary can carry a default pointing somewhere other than your console.
Sessions and the current session
Everything that touches a system runs inside an automation session.
hv session start <system-uuid-or-name> # create or reuse a session hv session use <session-uuid> # pin it as the current session hv session list # this API key's open sessions hv session get <session-uuid> hv session end <session-uuid>
Commands that act on a system take --session, which accepts a session UUID or the word current. With no flag and no pinned session they fail rather than guessing. hv session use is the one to know: it removes the need to pass a UUID to everything that follows.
The command set
Grouped by what they touch, with the capability each needs.
Command | What it does | Capability |
|
| None |
|
| None |
|
| None |
|
| None |
| Read-only discovery of one system: OS and version, displays, foreground window, logged-in user, resolved capabilities. Creates a temporary session if you do not give it one |
|
| The same ground truth inside an existing session, including |
|
| Capture a display or a window |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Run a command and wait for it |
|
| Start a process without waiting, for long-running or graphical processes |
|
| Wire the CLI into an AI client. See Install the HyperView skill for your agent | None |
| Learn the CLI, and identify the binary | None |
Running commands on the system
hv exec has three modes, and choosing the wrong one is a common source of quoting problems:
Command mode, the default. The arguments are joined into one line and a remote shell parses it. Convenient, but the remote shell re-parses your quotes.
Program mode,
--program. Runs the named binary with the arguments exactly as given, with no shell in the way. Use it whenever the payload is precisely quoted.Script mode,
--languagewith--scriptor--script-file. An interpreter runs a multi-statement body, with--argfor positional arguments.
Remote stdout and stderr are written to local stdout and stderr, and hv exec exits with the remote process's exit code, so a script can test it the way it would test a local command. Use hv spawn instead when the process should outlive the call.
Output for scripts and agents
--json prints a structured envelope instead of human text, and --output-schema pins its version so an upgrade does not silently change the shape your parser expects. hv version reports the binary's version and the schema version it emits.
--dry-run is the safe way to inspect what a write command would do: it prints the planned request and exits without sending anything.
hv screenshot writes to a temporary file and prints the path, or to --output <path>, or to stdout with --output - for piping. The format follows the file extension unless --format says otherwise. Exactly one of --display or --window is required. There is no implicit display, and hv system-info lists the ids.
Learning the CLI
Two commands exist for an agent reading its way in, and they work for people too:
hv guide: a curated overview, with topics for authentication, sessions, capabilities, workflows, output and MCP.--jsonreturns it as structured sections.hv examples: runnable example invocations, either the high-value set or the ones for a single command.
Checking session state first
hv system-info reports session_state, which is one of logged_in, locked, logged_out, screensaver, switching_user or unknown.
Check it before doing anything that needs a desktop. A screenshot of a logged-out machine is a login screen, and keyboard input goes nowhere useful.
A complete flow
# Authenticate the CLI (interactive; credentials are cached; check with `hv auth status`) hv auth login# Find an online system whose name matches, then open a session on it hv systems list --name "<system-name>" --online-only hv session start "<system-name>" # prints the session uuid hv session use <session-uuid> # make it the default for the commands below# Check whether a user is logged in; log in if not hv system-info # reports session_state hv desktop login --username "<system-username>" --password-stdin# Capture a screenshot, then close the session hv screenshot --output screenshot.png hv session end <session-uuid>
Capabilities apply here too
Every command maps to a capability, as in the table above. hv desktop login needs system.auth, which is risky by default. If a command fails with a permission error, check Automation capabilities before assuming the CLI is broken. hv capabilities check answers it directly for the session you are in.
Troubleshooting
A command fails with no session. Commands that act on a system need
--sessionor a pinned current session. Runhv session use, or pass--session current.Credentials are not being picked up.
hv auth statusreports which of the three sources they came from, which is faster than guessing.Quoting is being mangled by the remote shell. Use
hv exec --program, which does not involve a shell.A screenshot fails or is blank.
--displayor--windowis required, and the ids come fromhv system-info. A blank or login-screen image usually meanssession_stateis notlogged_in.
Commands worth knowing about
Command | What it is for |
| Put one line on the remote system's narration bar, so the person watching knows what you are doing. The bar holds one message; a new one replaces it. |
| Wait until something is true on screen (a window appears, text disappears), let it settle, and return an observation without acting |
|
|
| Install the HyperView skill into an AI client. See Install the HyperView skill for your agent |
| The embedded MCP server, for clients that prefer MCP to shelling out |
| An AI-optimised overview, and curated example invocations |
Exit codes worth handling
Exit 9 means a capability is gated behind a human decision. The command did not fail, it is waiting on a person. Exit 3 is an outright denial, exit 2 means no credentials, and exit 5 means the system or session UUID did not resolve. An agent that treats every non-zero exit as failure will stop on approvals it could simply request.