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 |
boards | List boards, inspect structure, manage board settings, and handle board trash operations. | Boards |
lists | List, show, create, update, move, delete, restore, and purge lists on a board. | Lists |
tasks | List, show, create, update, move, delete, restore, and purge tasks. | Tasks |
releases | List, show, create, update, delete, and set-default releases on a board. | Releases |
statuses | List global workflow statuses. | Statuses |
query | Run full-text task search with query search. | Search |
trash | Read items currently in Trash. Restore and purge stay under their resource commands. | 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"
--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.
--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
--quietrequires--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.
--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.
- Pipes and redirects already drop color automatically.
--format json(the default) is uncolored.
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.
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.
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.
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 <n> | Return up to n rows |
--offset <n> | 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. |
--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.
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.
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 |
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/.
npm run dev.