Skip to main content
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/status 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.

​
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.
OptionTypeRequiredDescription
-b, --backgroundflagOptional alias for the default detached start behavior.
--foregroundflagKeep the server attached to the terminal and show startup logs.
--profile <name>stringProfile 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.

CursorOpen in Cursor
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.
OptionTypeRequiredDescription
--profile <name>stringProfile 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 on the configured port (for the active profile). Prints JSON to stdout.
OptionTypeRequiredDescription
--profile <name>stringProfile for resolving port and config.
--client-name <name>stringOptional; 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.

CursorOpen in Cursor
When the server is up, server status mirrors the running payload from /api/health: pid, port, running, runtime, source, and url.

​
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 JSON status shape as hirotm server status.
hirotaskmanager server status returns the same status JSON shape as hirotm server status and /api/health when the server is up. Example: 
{
  "pid": 12345,
  "port": 3001,
  "running": true,
  "runtime": "installed",
  "source": "installed",
  "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.
OptionTypeRequiredDescription
--label <text>stringFree-form label stored alongside the hash (e.g. "Desktop", "Cursor Agent") — shown by api-key list.
--save-to-profileflagAlso writes the new key into the active server profile’s api_key field, so the local CLI authenticates immediately.
--profile <name>stringServer 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.