# 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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.