Boards

The hirotm boards commands let you list boards, probe a board’s structure without loading every task (boards describe), create or rename boards, send boards to Trash and bring them back, and change task groups and priorities (boards configure …). Task rows use hirotm tasks list --board (see Tasks). Global options and output modes: hirotm CLI. Turn on the CLI permissions you need in the board or app settings—see CLI access policy. Creating a new board also requires Create board for the CLI in the app settings. For columns on a board, see Lists. For individual work items, see Tasks. For connection options (--profile, --client-name) shared across commands, see hirotm CLI. Access policy Enable the right toggles in Board settings (and app-wide settings for boards add). If the CLI is not allowed to do something, the command fails with an error message.

Board Operations

`boards list`

List boards you can access with the CLI. Sort: boards appear in name order, A→Z, case-insensitive (same order as the API’s GET /api/boards). See Default sort order.

Option	Type	Description
`--limit <n>`	integer	Page size (omit for one full response from the server).
`--offset <n>`	integer	Skip this many boards (default 0).
`--page-all`	flag	Merge all pages (uses `--limit` or 500 per HTTP request).
`--count-only`	flag	Total rows only (Paging); not with `--limit`, `--offset`, `--page-all`, or `--fields`.
`--fields <keys>`	string	Comma-separated API keys per row. Allowed: `boardId`, `slug`, `name`, `emoji`, `description`, `cliPolicy`, `createdAt`. See Field projection.

This command accepts the global -q / --quiet flag (with --format ndjson): one plain-text value per row, default slug then boardId. See Pipe-friendly quiet. Shared connection options (--profile, --client-name) are documented on hirotm CLI. CLI Examples

hirotm boards list
hirotm boards list --count-only
hirotm boards list --limit 50 --offset 0                    # pagination
hirotm boards list --fields boardId,slug,name             # slimmer rows
hirotm boards list --page-all --limit 100                  # merge all pages
hirotm boards list --format human                          # table
hirotm boards list --profile dev                           # non-default profile (optional; same for any command)

AI Agent Examples

List all Task Manager boards I can access with the CLI.

Open in Cursor

Show Example responses

{"boardId":1,"slug":"sprint","name":"Sprint","emoji":null,"description":"","cliPolicy":{"readBoard":true,"createTasks":true,"createLists":true},"createdAt":"2026-04-01T10:00:00.000Z"}

Id    Slug               Name                 Em
----- ------------------ -------------------- ----
1     sprint             Sprint
total 1 · showing 1 · limit 500 · offset 0

{
  "error": "Server not reachable"
}

`boards describe`

Return a compact probe for one board: identity, truncated description, full cliPolicy, and optional sections for lists, groups, priorities, releases, global workflow statuses, and optional aggregate slice stats—without any tasks and without board UI prefs (layout, stats, visible-status prefs, theme). Backed by GET /api/boards/:id/describe (single nested JSON object). CLI stdout: with default --format ndjson, the CLI prints multiple compact JSON lines (same idea as list reads):

kind: "board" — boardId, slug, name, emoji, description, and optional descriptionTruncated (no cliPolicy on this line).
kind: "policy" — same boolean fields as board.cliPolicy, flattened on one object.
Row lines in --entities order: kind: "list", "group", "priority", "release", "status" (only for sections you requested).
If meta appears in --entities, a single kind: "meta" line with lists, groups, priorities, releases, and statuses — each value is { truncated, total, shown } (reflects the 100-row cap per slice).

Omit --entities to request the five row sections in this order: list → group → priority → release → status (no meta). human uses the same block order after board + description + policy table. --format human together with global --quiet exits 2 (same as other commands that render tables). Use this when you need ids and labels for flags like --list, --group, --priority, --release-id, or --status, or to confirm what the CLI may do on the board, without downloading the full task graph. For task rows, use hirotm tasks list --board (add --page-all to merge every page) or hirotm query search. The web app loads the full board document over GET /api/boards/:id; there is no hirotm boards show command. Access: same as other board reads—readBoard must be on for the CLI (see CLI access policy). Limits: each array section returns at most 100 items (board column order for lists, group sort order, priority value, releases by releaseDate descending with null dates last, statuses in workflow order). If more rows exist, the slice includes truncated: true and total. Board description is capped at 4096 UTF-16 code units; when shortened, board.descriptionTruncated is true.

Option	Type	Required	Description
`<id-or-slug>`	string		Board id or slug.
`--entities <csv>`	string		Comma-separated tokens: `list`, `group`, `priority`, `release`, `status`, `meta`. Order controls CLI stdout (and is preserved when you read line-by-line). The HTTP `?entities=` query lists the same tokens (the CLI may sort them for the request; the response includes every requested section). Omit the flag for the default five sections (no `meta`). The JSON `board` object (identity, description, `cliPolicy`) is always in the HTTP body. `board` is not a valid token. Duplicates or unknown names → exit 2 (`invalid_value`).

There is no --fields on this command (use --entities to trim the HTTP response; the CLI still reshapes stdout as above). CLI examples

hirotm boards describe sprint
hirotm boards describe 1 --profile dev                     # non-default profile
hirotm boards describe sprint --entities list,group,priority
hirotm boards describe sprint --entities list,meta

AI agent examples

Describe board sprint: lists, groups, priorities, releases, statuses, and CLI policy, without tasks.

Open in Cursor

Show Example shapes

HTTP (GET /api/boards/:id/describe) — one JSON object. With ?entities=meta (alone or combined), a top-level meta object is included:

{
  "board": {
    "boardId": 1,
    "slug": "sprint",
    "name": "Sprint",
    "emoji": null,
    "description": "",
    "cliPolicy": { "readBoard": true, "createTasks": true, "manageCliCreatedTasks": true, "manageAnyTasks": false, "createLists": true, "manageCliCreatedLists": true, "manageAnyLists": false, "manageStructure": false, "deleteBoard": false, "editBoard": false }
  },
  "lists": { "items": [{ "listId": 10, "name": "Ready" }] },
  "groups": { "items": [{ "groupId": 2, "label": "feature", "default": true }] },
  "meta": {
    "lists": { "truncated": false, "total": 1, "shown": 1 },
    "groups": { "truncated": false, "total": 1, "shown": 1 },
    "priorities": { "truncated": false, "total": 0, "shown": 0 },
    "releases": { "truncated": false, "total": 0, "shown": 0 },
    "statuses": { "truncated": false, "total": 2, "shown": 2 }
  }
}

CLI stdout (--format ndjson) — one JSON object per line (abbreviated; default entities, no meta):

{"kind":"board","boardId":1,"slug":"sprint","name":"Sprint","emoji":null,"description":""}
{"kind":"policy","readBoard":true,"createTasks":true,"manageCliCreatedTasks":true,"manageAnyTasks":false,"createLists":true,"manageCliCreatedLists":true,"manageAnyLists":false,"manageStructure":false,"deleteBoard":false,"editBoard":false}
{"kind":"list","listId":10,"name":"Ready"}
{"kind":"group","groupId":2,"label":"feature","default":true}

CLI validation error (--entities typo, stderr):

{
  "error": "unknown entity: wat"
}

Passing board as a token is rejected (the board header is always returned):

{
  "error": "unknown entity: board (board is always included in the response; omit it)"
}

Filtered task listing

Use hirotm tasks list --board <id-or-slug> with optional filters (list, group, priority, status, release, dates). See Tasks.

`boards add`

Create a board. Needs Create board turned on for the CLI in the app settings (not a per-board switch).

Option	Type	Description
`[name]`	string	Board name; omit to use the app default.
`--emoji <text>`	string	Optional emoji before the name.
`--description <text>`	string	Short description text.
`--description-file <path>`	string	Read description from a text file.
`--description-stdin`	flag	Read description from the terminal until input ends.

CLI Examples

hirotm boards add "Q2 Planning"
hirotm boards add --emoji "📌" "Releases"

AI Agent Examples

Create a board named "Paris Ideas" with the CLI.

Open in Cursor

Show Example responses

{
  "ok": true,
  "boardId": 2,
  "boardSlug": "paris-ideas",
  "boardUpdatedAt": "2026-04-09T16:00:00.000Z",
  "entity": {
    "type": "board",
    "boardId": 2,
    "slug": "paris-ideas",
    "name": "Paris Ideas",
    "emoji": null,
    "createdAt": "2026-04-09T16:00:00.000Z",
    "updatedAt": "2026-04-09T16:00:00.000Z"
  }
}

{
  "error": "CLI board creation is disabled. Ask the owner to enable it in TaskManager CLI settings (web app)."
}

`boards update`

Change board name, emoji, description, or color preset. You must pass at least one change.

Option	Type	Description
`<id-or-slug>`	string	Board id or slug.
`--name <text>`	string	New board name.
`--emoji <text>`	string	Emoji before the name.
`--clear-emoji`	flag	Remove the board emoji.
`--description <text>`	string	Description text.
`--description-file <path>`	string	Description from a text file.
`--description-stdin`	flag	Description from the terminal until input ends.
`--clear-description`	flag	Clear the description (do not use with other description options).
`--board-color <preset>`	string	One of: stone, cyan, azure, indigo, violet, rose, amber, emerald, coral, sage.
`--clear-board-color`	flag	Remove the board color preset.

CLI Examples

hirotm boards update --name "Sprint 42" sprint
hirotm boards update --board-color cyan --clear-emoji sprint

AI Agent Examples

Rename board sprint to "Sprint April".

Open in Cursor

Show Example responses

{
  "ok": true,
  "boardId": 1,
  "boardSlug": "sprint-april",
  "boardUpdatedAt": "2026-04-09T16:05:00.000Z",
  "entity": {
    "type": "board",
    "boardId": 1,
    "slug": "sprint-april",
    "name": "Sprint April",
    "emoji": null,
    "createdAt": "2026-04-01T10:00:00.000Z",
    "updatedAt": "2026-04-09T16:05:00.000Z"
  }
}

{
  "error": "At least one update field is required"
}

`boards delete`

Send a board to Trash. The CLI needs delete board permission on that board.

Option	Type	Description
`<id-or-slug>`	string	Board id or slug.
`--dry-run`	flag	Print a preview JSON only; do not move to Trash. See Dry-run preview.
`-y`, `--yes`	flag	Skip the confirmation prompt.

CLI Examples

hirotm boards delete old-sprint
hirotm boards delete old-sprint --dry-run
hirotm boards delete old-sprint --yes

AI Agent Examples

Move board old-sprint to Trash (non-interactive).

Open in Cursor

Show Example responses

{
  "ok": true,
  "boardId": 1,
  "boardSlug": "old-sprint",
  "boardUpdatedAt": "2026-04-09T16:15:00.000Z",
  "trashed": {
    "type": "board",
    "boardId": 1,
    "slug": "old-sprint",
    "trashed": true
  }
}

{
  "error": "Board not found",
  "board": "old-sprint"
}

`boards restore`

Bring a board back from Trash. Use the numeric id or the slug shown for that board in Trash.

Option	Type	Required	Description
`<id-or-slug>`	string		Trashed board id or slug.
`-y`, `--yes`	flag		Skip the confirmation prompt.

CLI Examples

hirotm boards restore 1
hirotm boards restore old-sprint --yes

AI Agent Examples

Restore trashed board old-sprint (non-interactive).

Open in Cursor

Show Example responses

{
  "ok": true,
  "boardId": 1,
  "boardSlug": "old-sprint",
  "boardUpdatedAt": "2026-04-09T16:20:00.000Z",
  "entity": {
    "type": "board",
    "boardId": 1,
    "slug": "old-sprint",
    "name": "Old sprint",
    "emoji": null,
    "createdAt": "2026-04-01T10:00:00.000Z",
    "updatedAt": "2026-04-09T16:20:00.000Z"
  }
}

{
  "error": "Board not in Trash (no matching slug)",
  "board": "unknown"
}

`boards purge`

Remove a board from Trash forever. This cannot be undone. Needs delete board permission.

Option	Type	Description
`<id-or-slug>`	string	Trashed board id or slug.
`--dry-run`	flag	Print a preview JSON only; do not purge. See Dry-run preview.
`-y`, `--yes`	flag	Skip the confirmation prompt.

CLI Examples

hirotm boards purge 1
hirotm boards purge 1 --dry-run
hirotm boards purge 1 --yes

AI Agent Examples

Permanently delete trashed board 1 from Trash (non-interactive).

Open in Cursor

Show Example responses

{
  "ok": true,
  "purged": {
    "type": "board",
    "boardId": 1
  }
}

{
  "error": "Board not in Trash (no matching slug)",
  "board": "unknown"
}

Board Settings

These commands change structure on a board (task groups and priorities). The CLI needs the matching permission—see CLI access policy (manage structure).

`boards configure groups`

Update task groups from JSON. Give the data with --file, --json, or --stdin (exactly one). The JSON shape is aimed at automation; see the Task Manager repository docs/ai-cli.md for the full format.

Option	Type	Description
`<id-or-slug>`	string	Board id or slug.
`--json <text>`	string	JSON inline.
`--file <path>`	string	JSON from a file.
`--stdin`	flag	JSON from the terminal until input ends.
`--dry-run`	flag	Validate input and print a preview JSON (with current groups); no PATCH. See Dry-run preview.
`-y`, `--yes`	flag	Skip the confirmation prompt.

CLI Examples

hirotm boards configure groups --file groups.json sprint
hirotm boards configure groups --file groups.json sprint --dry-run
hirotm boards configure groups --file groups.json sprint --yes

AI Agent Examples

Update task groups on board sprint from groups.json (non-interactive).

Open in Cursor

Show Example responses

{
  "ok": true,
  "boardId": 1,
  "boardSlug": "sprint",
  "boardUpdatedAt": "2026-04-09T16:10:00.000Z",
  "entity": {
    "type": "board",
    "boardId": 1,
    "slug": "sprint",
    "name": "Sprint",
    "emoji": null,
    "createdAt": "2026-04-01T10:00:00.000Z",
    "updatedAt": "2026-04-09T16:10:00.000Z"
  }
}

{
  "error": "Invalid task groups JSON",
  "details": {}
}

`boards configure priorities`

Replace task priorities from JSON. Use --file, --json, or --stdin (exactly one). The file can be a plain array or an object with a taskPriorities field.

Option	Type	Description
`<id-or-slug>`	string	Board id or slug.
`--json <text>`	string	JSON inline.
`--file <path>`	string	JSON from a file.
`--stdin`	flag	JSON from the terminal until input ends.
`--dry-run`	flag	Validate input and print a preview JSON (with current priorities); no PATCH. See Dry-run preview.
`-y`, `--yes`	flag	Skip the confirmation prompt.

CLI Examples

hirotm boards configure priorities --file priorities.json sprint
hirotm boards configure priorities --file priorities.json sprint --dry-run
hirotm boards configure priorities --file priorities.json sprint --yes

AI Agent Examples

Replace priorities on board sprint from priorities.json (non-interactive).

Open in Cursor

Show Example responses

{
  "ok": true,
  "boardId": 1,
  "boardSlug": "sprint",
  "boardUpdatedAt": "2026-04-09T16:12:00.000Z",
  "entity": {
    "type": "board",
    "boardId": 1,
    "slug": "sprint",
    "name": "Sprint",
    "emoji": null,
    "createdAt": "2026-04-01T10:00:00.000Z",
    "updatedAt": "2026-04-09T16:12:00.000Z"
  }
}

{
  "error": "Board not found",
  "board": "sprint"
}

Learn more

Run hirotm help boards or hirotm help boards <subcommand> for the full help text in your installed CLI.

Get Started

CLI

Hiro Developers

Board Operations

`boards list`

`boards describe`

Filtered task listing

`boards add`

`boards update`

`boards delete`

`boards restore`

`boards purge`

Board Settings

`boards configure groups`

`boards configure priorities`

Learn more

​Board Operations

​boards list

​boards describe

​Filtered task listing

​boards add

​boards update

​boards delete

​boards restore

​boards purge

​Board Settings

​boards configure groups

​boards configure priorities

​Learn more

Board Operations

`boards list`

`boards describe`

Filtered task listing

`boards add`

`boards update`

`boards delete`

`boards restore`

`boards purge`

Board Settings

`boards configure groups`

`boards configure priorities`

Learn more