# Command reference

> **A chapter to look things up in.** You do not have to read it in order.

Every command runs **from any folder.**

## At a glance

| Command | What it does |
|---|---|
| `hyperteams` | start attached to this terminal. Ctrl-C to stop |
| `hyperteams start --background` | start so it survives closing the window |
| `hyperteams stop` | bring down everything this install started |
| `hyperteams restart` | stop and bring it back up in the background |
| `hyperteams setup` | set the address and password again |
| `hyperteams upgrade` | move to the latest version |
| `hyperteams upgrade --check` | only check whether a new version exists |
| `hyperteams uninstall` | remove the install folder and the command |

---

## Starting

```bash
hyperteams
```

Runs attached to this terminal. **Close the window and it stops with it.**

```bash
hyperteams start --background
```

It prints the address and returns your prompt. It survives closing the window.

| | Log |
|---|---|
| Current run | `logs/server.log` |
| Previous run | `logs/server.log.prev` (one generation kept) |

**To start automatically at boot**, register this command as a system startup
item — launchd on macOS, systemd on Linux, Task Scheduler on Windows.

---

## Stopping

Normally **Ctrl-C** in the terminal you started it from. If that terminal is gone
(you closed the window, or the connection dropped):

```bash
hyperteams stop
```

**It brings down everything this install started** — the app, the tunnel, and any
open terminals.

> If work is in progress it tells you and asks once, because **restarting does
> not resume that work.**

---

## Restarting

```bash
hyperteams restart
```

Stops and brings it back up **in the background** — it does not hold this window.
If it was already stopped, it simply starts.

To attach it to this window instead:

```bash
hyperteams restart --foreground
```

**When to use it**: after [connecting a tunnel](/guide/ht-remote-access), after
changing settings.

---

## Changing settings

```bash
hyperteams setup
```

Sets the address and password again. Also **what you use when you forgot the
password.**

---

## Upgrading

```bash
hyperteams upgrade
```

Fetches the latest build for this machine and **replaces only the program files
in place.**

Your things are untouched:

```
✓ the database (conversations and usage records)
✓ .env.local (settings)
✓ tunnel credentials
```

**Because they were never in the build to begin with.** If it is running it stops
first, so start it again with `hyperteams` afterwards.

To check without changing anything:

```bash
hyperteams upgrade --check
```

> **Reinstalling is not an upgrade method.** Rerunning the install script makes
> no guarantees about your records and settings.

---

## Running on a different port

```bash
PORT=9000 hyperteams
```

For when the default port is taken. If specifying it every time is tedious,
change the default with `hyperteams setup`.

---

## Uninstalling

```bash
hyperteams uninstall
```

Removes the install folder and the `hyperteams` command together.

> **Stored records are removed with it, so it asks once more before deleting.**

What remains:

```
✓ Claude Code itself
✓ your working directories and the files in them
```

---

## Look-up by situation

| When | This command |
|---|---|
| You want to keep using the terminal | `hyperteams start --background` |
| You closed the window and want to stop it | `hyperteams stop` |
| You changed a setting and need it applied | `hyperteams restart` |
| You forgot the password | `hyperteams setup` |
| You wonder if there is a new version | `hyperteams upgrade --check` |
| The port conflicts | `PORT=9000 hyperteams` |
| `command not found` | open a new terminal window |

---

When something goes wrong → [Troubleshooting](/guide/ht-troubleshooting)