Hiro Task Manager Cli

• Use hirotm cli command for all operations.
• use --help to get help on any command or sub command boards --help, boards describe --help.
• prefer hirotm --help and subcommand help when you need examples or docs links.
• Run commands from the intended workspace root.
• Inspect current state before making mutations.
• For paginated reads or search, prefer --count-only when you only need cardinality first.
• Use --client-name on mutating commands so changes are attributable.
• Treat delete, purge, and structural changes as sensitive.
• Prefer --dry-run first for delete, purge, and board structure changes, then rerun with --yes only when ready.
• Use --no-color when plain output is easier to inspect for one run.

Identification

Identify yourself in all commands with --client-name <your-name>. Your name should reflect the Agent Name, ex: Cursor Agent, Github Copilot Agent, Claude Code Agent, Open Code Agent. If you are not sure, use a generic name "AI Agent"

Installation

The hirotm binary ships with the @hiroleague/taskmanager npm package (npm, source).

If the command is not found, ask the user to install it and configure it.

Discovery

• use boards list to list all boards.
• use boards describe <id-or-slug> to describe all or some board details.
• use tasks list --board <board-id-or-slug> to list and filter tasks in a board.
• use tasks show <task-id> or lists show <list-id> to print one row by global id when you already know the id.

Finding/Adding/Updating Tasks

• When a user refers to an existing task, use tasks list with filters, tasks show, or query search to find it.
• If convenient, use limit, offset, fields, or quiet options to manage and the output shape.
• When adding a task
  • use any available information such as priority, task group, release, etc...
  • Add proper title (80 characters max) and Emoji if relevant only.
  • use Organized Markdown description if the task body is detailed.
  • use mermaid diagrams if the task includes design diagrams or if the user requests it.
  • If linking to a larger documents in the workspace, make sure to use a proper link from the workspace root.

Access

If you are not allowed to access an entity or perform an operation due to CLI Access Control, explain the situation and suggest the user to give you the necessary permissions. Never attempt to bypass the CLI Access Control.

Errors

• Prefer the machine-readable stderr code over parsing the error text.
• If stderr includes a hint, use it as the next recovery step.
• HTTP/API failures usually include better hint guidance than local argument-validation failures.

Server Operations

• Check Server Status with server status
• Start Server with server start --background
• Stop Server with server stop

References

• Installation Guide
• Server Commands - Start, stop, and check the server status.
• Boards Commands - Create, update, delete, list, describe, and configure boards.
• Lists Commands - List, show, add, update, move, delete, restore, and purge board lists.
• Tasks Commands - List, show, add, update, move, delete, restore, and purge tasks.
• Releases Commands - List, show, add, update, delete, and set-default releases.
• Trash Commands - Inspect trashed boards, lists, and tasks.
• Status Commands - List workflow statuses and their meanings.
• Search Commands - Full-text task search with query search.
• CLI Access Policy - Map commands to cliPolicy requirements and read/write permissions.
• Errors and Exit Codes - Exit codes, stderr fields, and common machine-readable codes.

Safety notes

• Prefer inspect-first workflows.
• Search before create when overlap is likely.
• Do not purge unless intent is clearly explicit.
• Do not bypass the CLI by any other means than the hirotm CLI.
• Respect permission and policy failures instead of working around them unsafely.

References

• Online Documentation