# Command Reference

Complete reference for all `hu` CLI commands.

***

## Authentication

### `hu login`

Open your browser to authenticate with Health Universe.

```bash
hu login
hu login --api-url http://localhost:3002 --auth-url http://localhost:3000
```

| Option       | Description                                                    |
| ------------ | -------------------------------------------------------------- |
| `--api-url`  | Override the API endpoint for this login                       |
| `--auth-url` | Override the URL of the browser sign-in page (the NextJS host) |

### `hu logout`

Clear the stored authentication token.

```bash
hu logout
```

### `hu whoami`

Display the currently authenticated user and active workspace.

```bash
hu whoami
hu whoami --json
```

***

## Apps

Manage applications in the current workspace.

### `hu apps list`

List all applications in the active workspace.

```bash
hu apps list
hu apps list --json
```

### `hu apps create`

Create a new application.

```bash
hu apps create --name "My App" --repo owner/repo --sdk FA --main-file main.py
```

| Option          | Description                                                  |
| --------------- | ------------------------------------------------------------ |
| `--name`        | Application name                                             |
| `--repo`        | GitHub repository in `owner/repo` format                     |
| `--sdk`         | App runtime: `FA` (FastAPI), `A2A` (Agent), `SL` (Streamlit) |
| `--category`    | Research area category                                       |
| `--description` | App description                                              |
| `--main-file`   | Entry point file (e.g. `main.py`)                            |
| `--private`     | Make the app private                                         |
| `--json`        | Output as JSON                                               |

### `hu apps delete`

Delete an application.

```bash
hu apps delete <app-id>
```

### `hu apps open`

Open an application in your browser.

```bash
hu apps open <app-id>
```

### `hu apps status`

Check the deployment status of an application.

```bash
hu apps status <app-id>
hu apps status <app-id> --json
```

### `hu apps deploy`

Trigger a deployment for an application.

```bash
hu apps deploy <app-id>
hu apps deploy <app-id> --wait     # Poll until deployment completes
hu apps deploy <app-id> --json
```

| Option   | Description                                                           |
| -------- | --------------------------------------------------------------------- |
| `--wait` | Poll every 5 seconds until the deployment finishes (up to 10 minutes) |
| `--json` | Output as JSON                                                        |

> With `--wait`, the CLI polls the deployment status every 5 seconds for up to **10 minutes**. If the deployment hasn't completed by then, the command exits — the deployment itself continues on the server. Check progress with `hu apps status <app-id>`.

### `hu apps logs`

View logs for an application deployment.

```bash
hu apps logs <app-id>              # Deployment/runtime logs
hu apps logs <app-id> --build      # Build logs
hu apps logs <app-id> --json
```

| Option    | Description                             |
| --------- | --------------------------------------- |
| `--build` | Show build logs instead of runtime logs |
| `--json`  | Output as JSON                          |

### `hu apps health`

Trigger a health check for an application.

```bash
hu apps health <app-id>
hu apps health <app-id> --json
```

### `hu apps archive`

Archive an application. This shuts down the running instance to save resources while keeping all configuration, metadata, and deployment history intact. The app will no longer be accessible to users until it is unarchived.

```bash
hu apps archive <app-id>
```

### `hu apps unarchive`

Restore an archived application and bring it back online.

```bash
hu apps unarchive <app-id>
```

***

## App Collaborators

### `hu apps collaborators list`

List collaborators for an application.

```bash
hu apps collaborators list <app-id>
hu apps collaborators list <app-id> --json
```

### `hu apps collaborators add`

Add collaborators to an application by email. Pass multiple emails as a comma-separated string.

```bash
hu apps collaborators add <app-id> "user1@example.com,user2@example.com"
```

> If some emails don't match existing Health Universe accounts, those will be skipped and the CLI will tell you which ones weren't found. The remaining valid emails are still added.

### `hu apps collaborators remove`

Remove a collaborator from an application.

```bash
hu apps collaborators remove <app-id> <collaborator-id>
```

***

## App Domains

Setting up a custom domain is a multi-step process:

1. **Add** the domain to your app
2. **Configure DNS** — add the CNAME or A record shown in the output to your DNS provider
3. **Verify** — confirm that DNS is configured correctly
4. **Activate** — switch live traffic to the custom domain

### `hu apps domains list`

List custom domains for an application.

```bash
hu apps domains list <app-id>
hu apps domains list <app-id> --json
```

### `hu apps domains add`

Add a custom domain to an application. The output will include DNS records you need to configure with your domain provider before verification.

```bash
hu apps domains add <app-id> app.example.com
```

### `hu apps domains verify`

Verify that DNS records are configured correctly for the domain. Run this after you've added the required DNS records at your domain provider.

```bash
hu apps domains verify <app-id> <domain-id>
hu apps domains verify <app-id> <domain-id> --json
```

### `hu apps domains activate`

Activate a verified custom domain so it starts serving traffic.

```bash
hu apps domains activate <app-id> <domain-id>
```

### `hu apps domains remove`

Remove a custom domain from an application.

```bash
hu apps domains remove <app-id> <domain-id>
```

***

## Orgs

The `orgs` command group manages your active workspace (organization). Workspaces are identified by their **slug** — a short, human-readable identifier shown everywhere in CLI output (banner, `whoami`, `orgs list`, `config show`).

### `hu orgs list`

List all workspaces you have access to.

```bash
hu orgs list
hu orgs list --json
```

### `hu orgs switch`

Switch the active workspace. All subsequent commands will operate in the selected workspace.

```bash
hu orgs switch <slug>          # Preferred — switch by slug
hu orgs switch <workspace-id>  # ID fallback
hu orgs switch personal        # Switch to your personal workspace
```

### `hu orgs members`

List members of the active workspace.

```bash
hu orgs members
hu orgs members --json
```

***

## Projects

### `hu projects list`

List projects in the active workspace.

```bash
hu projects list
hu projects list --json
```

### `hu projects create`

Create a new project in the active workspace.

```bash
hu projects create "My Project"
hu projects create "My Project" --json
```

### `hu projects delete`

Delete a project.

```bash
hu projects delete <project-id>
```

### `hu projects collaborators list`

List collaborators on a project.

```bash
hu projects collaborators list <project-id>
```

### `hu projects collaborators add`

Add a collaborator to a project.

```bash
hu projects collaborators add <project-id> <user-id> --role admin
```

| Option   | Description                         |
| -------- | ----------------------------------- |
| `--role` | Role to assign: `admin` or `member` |

### `hu projects collaborators remove`

Remove a collaborator from a project.

```bash
hu projects collaborators remove <project-id> <user-id>
```

***

## Threads

### `hu threads list`

List threads in the active workspace.

```bash
hu threads list
hu threads list --search "diabetes"
hu threads list --project <project-id> --limit 10
hu threads list --json
```

| Option      | Description                   |
| ----------- | ----------------------------- |
| `--search`  | Filter threads by search term |
| `--project` | Filter by project ID          |
| `--limit`   | Maximum number of results     |
| `--json`    | Output as JSON                |

### `hu threads delete`

Delete a thread.

```bash
hu threads delete <thread-id>
```

***

## Config

### `hu config show`

Display the current CLI configuration, including token status.

```bash
hu config show
hu config show --json
```

### `hu config set`

Update a configuration value.

```bash
hu config set apiUrl https://apps.healthuniverse.com
hu config set authUrl https://www.healthuniverse.com
```

| Key       | Description                                       | Default                           |
| --------- | ------------------------------------------------- | --------------------------------- |
| `apiUrl`  | NestJS API base URL                               | `https://apps.healthuniverse.com` |
| `authUrl` | URL of the browser sign-in page (the NextJS host) | `https://www.healthuniverse.com`  |

### `hu config unset`

Clear a single configuration key.

```bash
hu config unset apiUrl
hu config unset orgId    # Also clears orgSlug — they're paired
```

### `hu config reset`

Wipe the entire configuration (and credentials by default). Useful for starting clean without removing `~/.hu/` manually.

```bash
hu config reset                 # Clears config + token
hu config reset --keep-token    # Clears config but preserves the auth token
```

| Option         | Description                                                             |
| -------------- | ----------------------------------------------------------------------- |
| `--keep-token` | Preserve the stored auth token; only reset URLs and workspace selection |

***

## Admin

> These commands are only available to platform administrators.

### `hu admin stats`

Show platform-wide statistics (threads, users) across 24h, 7d, 30d, and all-time.

```bash
hu admin stats
hu admin stats --json
```

### `hu admin users`

List recently active users.

```bash
hu admin users
hu admin users --limit 20 --json
```

### `hu admin orgs`

List all workspaces on the platform.

```bash
hu admin orgs
hu admin orgs --json
```

***

## Common Workflows

### Deploy an app and monitor it

```bash
hu apps deploy <app-id> --wait
hu apps logs <app-id>
hu apps status <app-id>
```

### Set up a new app from scratch

```bash
hu login
hu orgs switch my-org
hu apps create --name "Patient Risk Model" --repo myorg/risk-model --sdk FA --main-file main.py
hu apps deploy <app-id> --wait
hu apps open <app-id>
```

### Add collaborators to an app

```bash
hu apps collaborators add <app-id> "alice@example.com,bob@example.com"
hu apps collaborators list <app-id>
```

### Set up a custom domain

```bash
hu apps domains add <app-id> risk-model.example.com
# Configure DNS records as instructed, then:
hu apps domains verify <app-id> <domain-id>
hu apps domains activate <app-id> <domain-id>
```

### Switch between environments

```bash
# Use local dev environment
hu config set apiUrl http://localhost:3002
hu config set authUrl http://localhost:3000
hu login

# Switch back to production
hu config set apiUrl https://apps.healthuniverse.com
hu config set authUrl https://www.healthuniverse.com
hu login
```


---

# 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/command-reference.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.