> ## 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.
# CLI commands
> Everything you need to know about the `hirotm` CLI.
This page lists the top-level commands and explains the shared options and common knowledge that all of the commands share. For more info about the concepts behind the CLI, visit [Concepts](/task-manager/get-started/concepts).
## Top-level commands
Each first-level subcommand has its own page with full syntax, flags, and examples.
| Command | Summary | Page |
| -------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------- |
| **`server`** | Start, stop, and check the server status. | [Server Operations](/task-manager/cli/server) |
| **`boards`** | List boards, inspect structure, manage board settings, and handle board trash operations. | [Boards](/task-manager/cli/boards) |
| **`lists`** | List, show, create, update, move, delete, restore, and purge lists on a board. | [Lists](/task-manager/cli/lists) |
| **`tasks`** | List, show, create, update, move, delete, restore, and purge tasks. | [Tasks](/task-manager/cli/tasks) |
| **`releases`** | List, show, create, update, delete, and set-default releases on a board. | [Releases](/task-manager/cli/releases) |
| **`statuses`** | List global workflow statuses. | [Statuses](/task-manager/cli/statuses) |
| **`query`** | Run full-text task search with `query search`. | [Search](/task-manager/cli/search) |
| **`trash`** | Read items currently in Trash. Restore and purge stay under their resource commands. | [Trash](/task-manager/cli/trash) |
## Shared options
### `--client-name`
`--client-name` is how the CLI identifies itself to the server. It is only a label, and not used for authentication. The Web UI shows that label in web notifications and audit logs.
Client name matters more in mutating commands: add, update, move, delete, restore, purge. However it is a good practice for the AI Agent to identify itself. This is especially useful when you have multiple AI Agents working on Hiro Task Manager.
For instance, a Cursor-based agent should identify itself as `--client-name "Cursor Agent"`
```bash theme={null}
hirotm tasks add --board sprint --list 12 --group 3 --title "Fix login redirect" --client-name "Cursor Agent"
hirotm tasks move --to-list 14 88 --client-name "Cursor Agent"
```
### `--profile`
`--profile` selects which **Hiro Task Manager** profile the CLI is addressing.
In standard local setup or server/client setup, where only one profile is used on the client side, this flag is not needed. Also, when multiple profiles are used, but the CLI is addressing the default profile, this flag is not needed.
```bash theme={null}
hirotm boards list --profile dev
hirotm tasks list --board sprint --profile dev
```
### `--quiet`
`--quiet` means "print the simplest possible list output so I can pipe it into another command."
On all list and search commands, it prints one plain-text value per line instead of NDJSON. That is useful for shell pipelines, counts, loops, and quick copy/paste tasks.
**Notes**
* `--quiet` requires `--format ndjson`.
* If you pass `--fields`, use only one field so each output line stays unambiguous.
* Each command chooses a sensible default value for quiet output. The exact default for a command is shown on that command's page.
```bash theme={null}
hirotm boards list --quiet
hirotm tasks list --board sprint --fields taskId --quiet
```
```text theme={null}
sprint
inbox
```
```text theme={null}
88
91
95
```
### `--no-color`
Turns off ANSI styling in human-mode stdout and stderr for **this invocation only**.
Most users never need this. Reach for `--no-color` when:
* You're in a terminal but want plain output for one command.
* You're copying output into a chat, an issue, a code review, or a screenshot.
* Your terminal theme makes the default colors hard to read.
**Notes**
* Pipes and redirects already drop color automatically.
* `--format json` (the default) is uncolored.
```bash theme={null}
hirotm boards list --format human --no-color
```
## Dry-run preview
Dry run is a standard feature to preview the changes that are going to be performed by the cli, before they are actually performed.
In commands such as purge, delete or restore, you can use the dry run option to preview the entities that would be affected by the command.
| Command | What it checks |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `boards delete` | Board exists (read-only). |
| `boards purge` | Trashed board id or slug resolves. |
| `boards configure groups` / `boards configure priorities` | Parses JSON like the real command and compares to current groups/priorities from **`boards describe`**. |
| `tasks delete` | Task exists and its board resolves from the task id. |
| `tasks purge` | Task is in Trash. |
| `lists delete` | List exists and its board resolves from the list id. |
| `lists purge` | List is in Trash. |
## `-V`, `--version`
Shows the **hirotm** or the **hirotaskmanager** version.
```bash theme={null}
hirotaskmanager --version
hirotm --version
hirotaskmanager -V
hirotm -V
```
## Response format
`--format` controls how the CLI prints results.
**`ndjson`**
Since this is an Agent First design, json is the default format. In fact, it is ndjson, so one JSON object per line. JSON lines are also flat, no hierarchies. AI Agents love this format.
* List and search commands print one JSON object per line.
* Most other successful commands print one JSON object.
* Failures print JSON on stderr. Better for inspection.
```bash theme={null}
hirotm boards list
```
```json theme={null}
{"boardId":1,"slug":"sprint","name":"Sprint"}
{"boardId":2,"slug":"inbox","name":"Inbox"}
```
**`human`**
`human` is for people reading the CLI directly. Use --format human for a more human-friendly output.
List and search commands print tables. Other successful commands print labeled text. Failures print plain text on stderr instead of JSON.
```bash theme={null}
hirotm boards list --format human
```
```text theme={null}
Name Slug Board ID
------ ------ --------
Sprint sprint 1
Inbox inbox 2
```
## Paging list results
Many read commands can return a lot of rows. Use paging flags when you want smaller batches, want to resume from a known position, or want to fetch everything in a predictable way.
| Flag | Use it for |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--limit ` | Return up to `n` rows |
| `--offset ` | Skip the first `n` rows |
| `--page-all` | Fetch every page and print the combined result |
| `--count-only` | Total matching rows only (one JSON object `{"count":N}` with default `--format ndjson`; no rows). Not with `--limit`, `--offset`, `--page-all`, or `--fields`. |
This is helpful for people browsing large boards and for agents or scripts that want predictable chunks of data.
Search is the main exception to the "full page by default" behavior: if you omit `--limit`, `hirotm query search` uses a default limit of `20` so search results stay bounded.
With `--quiet` and `--count-only`, stdout is a single line: the number only.
```bash theme={null}
hirotm tasks list --board sprint --limit 25
hirotm tasks list --board sprint --limit 25 --offset 25
hirotm tasks list --board sprint --count-only
hirotm query search "drag" --limit 10
hirotm query search "drag" --count-only
hirotm boards list --page-all
```
## Field projection
`--fields` lets you print only the keys you care about from supported read commands.
Use it to reduce noise in automation output, AI-agent output, or focused terminal checks. `--fields` works only with `--format ndjson`.
Allowed keys are documented on each command page, so this page does not repeat those per-command allowlists. If you also use `--quiet`, pass only one field.
```bash theme={null}
hirotm tasks list --board sprint --fields taskId,title,status
hirotm query search docs --fields taskId,boardSlug,title
```
```json theme={null}
{"taskId":88,"title":"Fix login redirect","status":"open"}
{"taskId":91,"title":"Document CLI flags","status":"closed"}
```
## Default sort order
Paging always walks the command's default order. Today, these orders are fixed and are not configurable with sort flags.
| Command | Default order |
| --------------------------------- | --------------------------------------- |
| `boards list` | Board name, A to Z, case-insensitive |
| `query search` | Relevance score, best matches first |
| `trash list boards\|lists\|tasks` | Newest deleted items first |
| `releases list` | Oldest created release first |
| `lists list` | Board column order |
| `tasks list` | Board-specific task order on the server |
For command-specific detail and examples, see [Boards](/task-manager/cli/boards#boards-list), [Tasks](/task-manager/cli/tasks#tasks-list), [Search](/task-manager/cli/search), [Trash](/task-manager/cli/trash#trash-list-boards), [Releases](/task-manager/cli/releases#releases-list), and [Lists](/task-manager/cli/lists#lists-list).
## Hiro Developers Only
The **`--dev`** flag is meant for Hiro developers working on Task Manager itself. It is independent of **`--profile`** and is supported on **`server start`**, **`server stop`**, and **`server status`**.
What **`--dev`** changes:
* Enables **dev CORS** for the Vite development app.
* Changes the default port to **3002**.
* Does not require a built frontend in **`dist/`**.
Use it together with a profile when you want dev runtime behavior:
```bash theme={null}
hirotm server start --dev --profile dev --background
hirotm server status --dev --profile dev
hirotm server stop --dev --profile dev
```
For full-stack repo development, prefer **`npm run dev`**.