Server Operations - Hiro League

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	Description
`-b`, `--background`	flag	Optional alias for the default detached start behavior.
`--foreground`	flag	Keep the server attached to the terminal and show startup logs.
`--profile <name>`	string	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).

CLI Examples

hirotm server start
hirotm server start --profile work
hirotm server start --foreground --profile work

AI Agent Examples

Start Task Manager in the background on a named profile so API commands work.

Open in Cursor

Show Example responses

{
  "pid": 12345,
  "port": 3001,
  "running": true,
  "runtime": "installed",
  "source": "installed",
  "url": "http://127.0.0.1:3001"
}

{
  "error": "Server failed to start",
  "hint": "Try running `hirotm server start --foreground` to inspect logs.",
  "url": "http://127.0.0.1:3001"
}

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>`	string		Profile whose pid file and port resolution this command uses (see Profiles).

CLI Examples

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>`	string		Profile for resolving port and config.
`--client-name <name>`	string		Optional; included for consistency with other commands (this call is read-only).

CLI Examples

hirotm server status
hirotm server status --profile work

AI Agent Examples

Check if Task Manager is running on a named profile.

Open in Cursor

Show Example responses

{
  "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"
}

{
  "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"
}

{
  "kind": "server_status",
  "profile": "remote",
  "role": "client",
  "running": false,
  "reachable": false,
  "api_url": "https://tasks.example.com"
}

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:

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:

{
  "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 and 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.

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.

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	Description
`--label <text>`	string	Free-form label stored alongside the hash (e.g. `"Desktop"`, `"Cursor Agent"`) — shown by `api-key list`.
`--save-to-profile`	flag	Also writes the new key into the active server profile’s `api_key` field, so the local CLI authenticates immediately.
`--profile <name>`	string	Server profile whose auth dir to write into (`~/.taskmanager/profiles/<name>/auth/`).

Examples

hirotaskmanager server api-key generate --label "Desktop"
hirotaskmanager server api-key generate --label "Local CLI" --save-to-profile

Sample output (--format ndjson)

{ "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.

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:

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.

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:

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.

​hirotm server start

​hirotm server stop

​hirotm server status

​Learn more

​Installed App Shortcuts

​Managing CLI API keys

​Key Generation

​Key Listing

​Key Revocation

​Key usage on the client

​Hiro Developers Only

`hirotm server start`

`hirotm server stop`

`hirotm server status`

Learn more

Installed App Shortcuts

Managing CLI API keys

Key Generation

Key Listing

Key Revocation

Key usage on the client

Hiro Developers Only