> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiroleague.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Server Operations

> Start, stop, or check Hiro Task Manager Server.

Using either `hirotaskmanager` or `hirotm` CLI commands, you can start, stop or check Hiro Task Manager Server status. While both commands are available, AI Agents are usually encouraged to use `hirotm` for everything.

`server start/stop` only act on **server-role** profiles. Running them against a client-role profile (one with `api_url` pointing at a remote server) errors with `code: invalid_args` — there is no local server to start. `server status` reports reachability for the active profile.

***

## `hirotm server start`

Starts the local API if it is not already healthy on that port. By default, the process detaches and **`hirotm`** prints **JSON** on success. Use **`--foreground`** when you want startup logs to stay attached to the terminal.

| Option               | Type                                         | Required                        | Description                                                                                                                                                                                                                                     |
| -------------------- | -------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-b`, `--background` | <Badge size="sm" color="orange">flag</Badge> | <Icon icon="minus" size={14} /> | Optional alias for the default detached start behavior.                                                                                                                                                                                         |
| `--foreground`       | <Badge size="sm" color="orange">flag</Badge> | <Icon icon="minus" size={14} /> | Keep the server attached to the terminal and show startup logs.                                                                                                                                                                                 |
| `--profile <name>`   | <Badge size="sm" color="blue">string</Badge> | <Icon icon="minus" size={14} /> | Profile for this command (same flag as the global root option; place it after **`server …`** in examples). The API **port** and data paths come from that profile’s **`config.json`** (see [Profiles](/task-manager/hiro-developers/profiles)). |

**CLI Examples**

```bash theme={null}
hirotm server start
hirotm server start --profile work
hirotm server start --foreground --profile work
```

**AI Agent Examples**

<Prompt description="Start Task Manager in the background on a named profile so API commands work." actions={["copy", "cursor"]}>
  Start Task Manager in the background on the profile named work so API commands work.
</Prompt>

<Expandable title="Example responses" defaultOpen={false}>
  <CodeGroup>
    ```json json theme={null}
    {
      "pid": 12345,
      "port": 3001,
      "running": true,
      "runtime": "installed",
      "source": "installed",
      "url": "http://127.0.0.1:3001"
    }
    ```

    ```json error theme={null}
    {
      "error": "Server failed to start",
      "hint": "Try running `hirotm server start --foreground` to inspect logs.",
      "url": "http://127.0.0.1:3001"
    }
    ```
  </CodeGroup>
</Expandable>

**Foreground mode**

With **`--foreground`**, the command waits until the API is healthy, then **keeps running** and forwards **SIGINT** / **SIGTERM** to the server. Use this when you want startup errors and logs in the terminal. If the API is **already** up on that port, the command **returns immediately** without spawning another process (no JSON line in that case).

***

## `hirotm server stop`

Stops a **background** server that **`hirotm server start`** recorded in the CLI **pid file** for this profile. It does **not** stop arbitrary processes on the port; if there is no pid file, the command fails with guidance.

| Option             | Type                                         | Required                        | Description                                                                                                                    |
| ------------------ | -------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `--profile <name>` | <Badge size="sm" color="blue">string</Badge> | <Icon icon="minus" size={14} /> | Profile whose **pid file** and **port** resolution this command uses (see [Profiles](/task-manager/hiro-developers/profiles)). |

**CLI Examples**

```bash theme={null}
hirotm server stop
hirotm server stop --profile work
```

***

## `hirotm server status`

Checks whether the Task Manager API responds for the active **profile**. Prints one flat **JSON** object to stdout.

| Option                 | Type                                         | Required                        | Description                                                                      |
| ---------------------- | -------------------------------------------- | ------------------------------- | -------------------------------------------------------------------------------- |
| `--profile <name>`     | <Badge size="sm" color="blue">string</Badge> | <Icon icon="minus" size={14} /> | Profile for resolving port and config.                                           |
| `--client-name <name>` | <Badge size="sm" color="blue">string</Badge> | <Icon icon="minus" size={14} /> | Optional; included for consistency with other commands (this call is read-only). |

**CLI Examples**

```bash theme={null}
hirotm server status
hirotm server status --profile work
```

**AI Agent Examples**

<Prompt description="Check if Task Manager is running on a named profile." actions={["copy", "cursor"]}>
  Check if Task Manager is running on the profile named work.
</Prompt>

<Expandable title="Example responses" defaultOpen={false}>
  <CodeGroup>
    ```json up (server profile) theme={null}
    {
      "kind": "server_status",
      "profile": "work",
      "role": "server",
      "running": true,
      "reachable": true,
      "api_url": "http://127.0.0.1:3001",
      "server_pid": 12345,
      "server_port": 3001,
      "server_runtime": "installed",
      "server_source": "installed",
      "server_reported_url": "http://127.0.0.1:3001"
    }
    ```

    ```json up (client profile) theme={null}
    {
      "kind": "server_status",
      "profile": "remote",
      "role": "client",
      "running": true,
      "reachable": true,
      "api_url": "https://tasks.example.com",
      "server_pid": 12345,
      "server_port": 3001,
      "server_runtime": "installed",
      "server_source": "installed",
      "server_reported_url": "http://127.0.0.1:3001"
    }
    ```

    ```json down theme={null}
    {
      "kind": "server_status",
      "profile": "remote",
      "role": "client",
      "running": false,
      "reachable": false,
      "api_url": "https://tasks.example.com"
    }
    ```
  </CodeGroup>
</Expandable>

When the server is up, **`server status`** returns a flat CLI status object. Top-level fields describe the active profile connection. Fields prefixed with **`server_`** come from the server health payload.

***

## Learn more

Run **`hirotm help server`**, **`hirotm help server start`**, **`hirotm help server stop`**, or **`hirotm help server status`** for the exact flags your installed CLI exposes.

***

## Installed App Shortcuts

If you specifically want the installed package entry instead of whatever **`hirotm`** resolves to on **`PATH`**, use **`hirotaskmanager`**.

The installed launcher exposes:

```bash theme={null}
hirotaskmanager server start
hirotaskmanager server start --profile work
hirotaskmanager server status
hirotaskmanager server status --profile work
hirotaskmanager server stop
hirotaskmanager server stop --profile work
```

These are installed-runtime launcher commands:

* **`server start`** starts in the background by default and prints concise human progress text.
* **`server stop`** prints concise human progress text such as "Stopping Server" and "Server stopped".
* **`server status`** prints the same flat JSON status shape as **`hirotm server status`**.

`hirotaskmanager server status` returns the same flat status JSON shape as `hirotm server status`.

Example:

```json theme={null}
{
  "kind": "server_status",
  "profile": "work",
  "role": "server",
  "running": true,
  "reachable": true,
  "api_url": "http://127.0.0.1:3001",
  "server_pid": 12345,
  "server_port": 3001,
  "server_runtime": "installed",
  "server_source": "installed",
  "server_reported_url": "http://127.0.0.1:3001"
}
```

Run **`hirotaskmanager help server`**, **`hirotaskmanager help server status`**, or **`hirotaskmanager help server stop`** to see those launcher commands.

***

## Managing CLI API keys

While Server setup usually helps you generate a CLI key, there are some cases where you might need to generate a new key, or revoke an existing key.

This set of `hirotaskmanager` commands help generate, list and revoke CLI API keys. Learn more about CLI API keys in [Concepts](/task-manager/get-started/concepts/) and [Advanced setup](/task-manager/get-started/advanced-setup).

**Notes**

* These commands should run on the server side, not the client side, unless it is a local setup.
* Keys are stored in the server profile's auth directory.
* They do not require the HTTP server to be running.
* They only run against server profiles.

<Warning>
  `api-key generate` prints the **raw key** to stdout exactly once. Copy it immediately — only the hash is stored on the server, so the raw value cannot be recovered later. Lost keys must be revoked and re-issued.
</Warning>

### Key Generation

`hirotaskmanager server api-key generate`

Generates a random 32-byte key, formats it as `tmk-<64 hex chars>`, stores its hash in `cli-api-keys.json`, and prints the raw key.

| Option              | Type                                         | Required                        | Description                                                                                                               |
| ------------------- | -------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `--label <text>`    | <Badge size="sm" color="blue">string</Badge> | <Icon icon="minus" size={14} /> | Free-form label stored alongside the hash (e.g. `"Desktop"`, `"Cursor Agent"`) — shown by `api-key list`.                 |
| `--save-to-profile` | <Badge size="sm" color="orange">flag</Badge> | <Icon icon="minus" size={14} /> | Also writes the new key into the **active server profile's** `api_key` field, so the local CLI authenticates immediately. |
| `--profile <name>`  | <Badge size="sm" color="blue">string</Badge> | <Icon icon="minus" size={14} /> | Server profile whose auth dir to write into (`~/.taskmanager/profiles/<name>/auth/`).                                     |

**Examples**

```bash theme={null}
hirotaskmanager server api-key generate --label "Desktop"
hirotaskmanager server api-key generate --label "Local CLI" --save-to-profile
```

**Sample output (`--format ndjson`)**

```json theme={null}
{ "key": "tmk-a3f8c1...64 hex chars", "id": "tmk-a3f8", "label": "Desktop" }
```

### Key Listing

`hirotaskmanager server api-key list`

Lists all issued keys for the active server profile. Shows `id` (the first \~8 hex chars), `label`, and `createdAt`. Never shows the full key or its hash.

```bash theme={null}
hirotaskmanager server api-key list
```

### Key Revocation

`hirotaskmanager server api-key revoke <id-prefix>`

Removes the matching key entry from `cli-api-keys.json`. Match by the `id` prefix shown by `list`:

```bash theme={null}
hirotaskmanager server api-key revoke tmk-a3f8
```

After revocation, callers using that key receive **401** with `code: auth_invalid_cli_key`.

### Key usage on the client

The raw key is stored in the **client-side profile's** `config.json` as `api_key`:

* For a **client profile** (the typical remote case): paste it during `hirotaskmanager --setup-client`, or edit the file by hand.
* For a **server profile** that has `require_cli_api_key: true` (the hardened single-host case): use `--save-to-profile` on `generate` so the local CLI authenticates without further setup.

For end-to-end setup walkthroughs see [Advanced setup](/task-manager/get-started/advanced-setup).

***

## Hiro Developers Only

When you are developing Task Manager from the repository, use **`--dev`** on **`server start`**, **`server stop`**, and **`server status`**.

What **`--dev`** changes:

* Enables **dev CORS** so the Vite app can talk to the API directly.
* Changes the default port to **3002** instead of **3001**.
* Does not require a built frontend in **`dist/`**.

The **`--dev`** flag and **`--profile`** are independent:

```bash theme={null}
hirotm server start --dev --profile dev --background
hirotm server status --dev --profile dev
hirotm server stop --dev --profile dev
```

If you are running the repo source, prefer **`npm run dev`** for the full development stack.