> For the complete documentation index, see [llms.txt](https://docs.healthuniverse.com/overview/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.healthuniverse.com/overview/command-line-interface/cli.md).

# Overview

The Health Universe CLI (`hu`) lets you manage applications, deployments, workspaces, and projects directly from your terminal. Everything you can do in the web dashboard — deploying apps, managing collaborators, switching workspaces — you can do from the command line.

## Prerequisites

* **Node.js 18** or later
* **npm** 9 or later (included with Node.js)
* A [Health Universe account](https://www.healthuniverse.com)

## Installation

```bash
npm install -g @health-universe/cli
```

After installation, the `hu` command is available globally.

To **upgrade** to the latest version:

```bash
npm install -g @health-universe/cli@latest
```

To **uninstall**:

```bash
npm uninstall -g @health-universe/cli
```

> Uninstalling removes the CLI but leaves your config and credentials in `~/.hu/`. To remove those as well, delete the directory: `rm -rf ~/.hu`

## Quick Start

```bash
# 1. Log in (opens your browser)
hu login

# 2. Check your identity and active workspace
hu whoami

# 3. List your apps
hu apps list

# 4. Deploy an app and wait for it to finish
hu apps deploy <app-id> --wait

# 5. Check deployment status
hu apps status <app-id>
```

The CLI authenticates through your browser — `hu login` opens a sign-in page and no passwords are entered in the terminal. Tokens are valid for **24 hours** and refresh automatically. Credentials are stored in `~/.hu/credentials`.

All read commands support `--json` for machine-readable output:

```bash
hu apps list --json | jq '.[].name'
```

## Usage Modes

The CLI works in two modes:

* **Single-command mode** — run any command directly from your shell. Great for scripts and automation.

  ```bash
  hu apps list --json | jq '.[].name'
  ```
* **Interactive REPL mode** — run `hu` with no arguments to enter an interactive session. The REPL displays your authentication status and active workspace, and supports tab completion for all commands.

  ```
  $ hu

    ╦ ╦╔═╗╔═╗╦ ╔╦╗╦ ╦  ╦ ╦╔╗╔╦╦  ╦╔═╗╦═╗╔═╗╔═╗
    ╠═╣║╣ ╠═╣║  ║ ╠═╣  ║ ║║║║║╚╗╔╝║╣ ╠╦╝╚═╗║╣
    ╩ ╩╚═╝╩ ╩╩═╝╩ ╩ ╩  ╚═╝╝╚╝╩ ╚╝ ╚═╝╩╚═╚═╝╚═╝

    Version:    0.2.0
    Status:     AUTHENTICATED
    Workspace:  my-org

  hu> apps list
  hu> apps deploy abc123 --wait
  ```

  REPL-only commands:

  | Command         | Description                 |
  | --------------- | --------------------------- |
  | `help`          | Show all available commands |
  | `clear`         | Clear the screen            |
  | `exit` / `quit` | Exit the REPL               |

## What's Next

* [Command Reference](/overview/command-line-interface/command-reference.md) — full list of all available commands
* [Troubleshooting](/overview/command-line-interface/troubleshooting.md) — common errors and how to fix them


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.healthuniverse.com/overview/command-line-interface/cli.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.