CLI Reference

The native Hypertask CLI lets you manage tasks, projects, comments, and notifications from your terminal. The executable is named hypertask. The CLI ships as a native Zig binary (htz) and can also be installed via npm.

Connecting an agent token? See Connect a new agent.

Install

Via npm (recommended)

npm install -g @hypertask/hypertask_cli@latest

This installs a lightweight npm shim that fetches and runs the official htz binary for your platform, ensuring you always have the latest version.

Via curl (Linux / macOS)

On Linux or macOS, run:

curl -fsSL https://hypertask.ai/install | sh
hypertask --version

The installer detects x64 or ARM64, downloads the matching binary from the latest GitHub release, and verifies its SHA-256 checksum. It installs to ~/.local/bin by default. Set HYPERTASK_INSTALL_DIR to choose another directory.

Via PowerShell (Windows x64)

On Windows x64, run in PowerShell:

irm https://hypertask.ai/install.ps1 | iex
hypertask --version

The installer downloads the native executable from the latest GitHub release, verifies its SHA-256 checksum, installs it to %LOCALAPPDATA%\Programs\Hypertask and adds that folder to your user PATH. Open a new terminal afterwards to run hypertask from anywhere. Set HYPERTASK_INSTALL_DIR to choose another directory.

Fleet auto-install behavior

When you merge a commit into the hypertask-ai/cli repository, the VPS fleet runs an automated install workflow:

• The trusted runner builds the htz binary in ReleaseFast mode.
• It preserves any existing symlinks under ~/.local/bin.
• It only considers the install successful after verifying the installed binary matches the freshly built commit.
• Previous verifications and log metadata are retained to detect drift or mismatches.

If an install does not succeed, the CI/CD pipeline fails and prevents the commit from being considered merged.

Inside the Hypertask App

When you choose to install Hypertask from the web app, the in-app installer (CLI install dialog) uses the npm shim to fetch the htz binary for you. This keeps the command identical across all install channels.

General behaviour

Unknown flags

The CLI fails out loud for unrecognized flags and options. An unknown flag results in an error message and an exit code of 2 (non-zero), indicating a configuration or usage error.

hypertask task get HYFA-70 --zzznotaflag 9
# unknown option: --zzznotaflag
# exit code: 2

Error reports

From v0.2.18, when a command fails unexpectedly (a server error, a network problem, a response the CLI cannot read, or an internal error), the CLI sends Hypertask one short report so the failure becomes a bug ticket. The report holds only the command name (like task create), the error type, the HTTP status, the CLI version and your operating system. It never includes task content, ids, arguments or your token.

Your own mistakes (an unknown flag, a missing task, no permission) are never reported. Reporting never changes the error message or exit code, and gives up after about 1.5 seconds.

To turn it off, set HYPERTASK_NO_ERROR_REPORTS=1, or add "error_reports": false to ~/.hypertask/config.json.

v0.2.16 CLI Release (2026-10-12)

This release fixes a crash when running AI reviews on large pull requests. The CLI now passes PR text to the review program through standard input instead of a command-line argument, preventing shell argument limits:

• No crash on large PRs: AI review commands now work on arbitrarily large pull requests without hitting shell argument limits.
• Internal program path consistency: The review program running on the server matches the code stored in the repository, verified in QA.

To upgrade to v0.2.16:

npm install -g @hypertask/hypertask_cli@latest
hypertask --version

v0.2.15 CLI Release (2026-10-11)

This release fixes a bug in agent emoji handling for CLI inbox operations. The CLI now correctly distinguishes between agent and human reactions:

• Agent emoji reactions are no longer counted as human reactions in the CLI inbox.
• Human reactions are no longer dropped when loading or processing inbox data.

Previously, the CLI would treat an agent's emoji as if it came from a person, potentially causing selection or counting errors in inbox actions like bulk archive. This fix ensures accurate reaction tracking for agents monitoring tasks (HTPR-7128).

To upgrade to v0.2.15:

npm install -g @hypertask/hypertask_cli@latest
hypertask --version

v0.2.19 CLI Release (2026-10-15)

CLI 0.2.19 improves error reporting when network problems occur during command execution.

• Read retries and clearer errors: If the server does not respond while the CLI waits, it now retries once and surfaces the actual error instead of a bare "ReadFailed" message. Use --help or the full command list (hypertask capabilities --json) to see available updates. (Read more: HTPR-7261, HTPR-7262)

This change applies to all commands that involve waiting for a server response, including task listing, task details, and other read operations.

---

Task listing with label filters

hypertask tasks list

List tasks with optional filtering.

hypertask tasks list [options]

Options:

Option	Description
--query <text>	Free-text search. Same flag on every list command.
--filter <key=value>	Repeatable structured filter. Keys: priority, section, label, assignee, status, updated_since, has_pr.
--sort <field[:dir]>	Sort, for example updatedAt:desc.
--fields <a,b>	Return only these columns, for example title,url.
--labels <label1,label2,...>	Filter tasks by one or more labels.
--limit <num>	Max rows.
--cursor <token>	Next page from the previous response.
--offset <num>	Start listing from the Nth item (for paginated results).

Behaviour:

• Returns a paginated list of tasks matching the specified filters.
• Prefer --query, --filter, --fields, and --limit so one call stays small.
• Use --offset or --cursor to walk large collections.

hypertask tasks list --project 15 --filter section=AI Review --filter has_pr=red --fields title,url --limit 20
hypertask tasks list --labels cli,urgent

Note

The tasks list --labels flag was previously a no-op. It now correctly filters tasks by the provided labels (HTPR-6475).

Note

The --filter priority option now accepts both priority names (urgent, high, medium, low, none) and numeric values (0–4), matching the web UI and API. none matches tasks without an assigned priority (HTPR-6799).

Task move

hypertask tasks move

Move a task from one section to another. This works within a board or across boards.

hypertask tasks move <ticket> --section <section-name>
hypertask tasks move <ticket> --to <board-id>
hypertask tasks move <ticket> --to <board-id> --to-section <section-id>

Options:

Option	Description
--section <section-name>	Move the task to this section within the same board.
--to <board-id>	Move the task to this board. Use --to-section to specify the target section in the new board.
--to-section <section-id>	Specify the target section in the board given by --to. If omitted, the section defaults to "Backlog".
--assignee <user>	Change the task's assignee instead of moving it.

Behaviour:

• If the task is archived, the command fails with:

  "Archived tasks cannot move sections or change assignees"

• Use --to <board-id> to move a task to a different board, optionally with --to-section to specify a target section in the new board.
• Use --assignee <user> to change the task's assignee without moving boards.

# Move a task to another board (defaults to Backlog in the target board)
hypertask tasks move INFRA-123 --to 15

# Move a task to another board and specific section
hypertask tasks move INFRA-123 --to 15 --to-section 4060

# Move a task to a different section in the same board
hypertask tasks move PRODUCT-456 --section "In Review"

# Move a task and change its assignee
hypertask tasks move PRODUCT-456 --assignee @valentin

Note

The comments add --improve flag now correctly accepts a bare flag without a value and defaults to readability improvement (HTPR-6574).

Project management errors are informative

Bug fix Task creation now reports project membership failures with clear guidance instead of showing an internal server error or generic failure when the token lacks access.

Previously, using a non-member token to create a task resulted in a generic "hypertask: the server could not complete the command" exit code 4. After this fix (HTPR-6486), the same command returns:

# Using a token without project 5156 access
hypertask task create --project 5156 --section Backlog
# error: you are not a project member. Sign in with a valid account or use a token that has access to project 5156.
# exit code: 4

This makes CLI errors actionable for debugging out-of-scope work and bot configurations.

---

Project management

hypertask project update

Update a project (board) by ID. To rename a board, use the --title flag:

hypertask project update <id> --title "<new title>"

Options:

Option	Description
--title <title>	New board title. The title will be trimmed to non-empty and max 200 characters.
--description <description>	Optional board description (HTML).

Behaviour:

• Board members with write access can rename the board; non-members are blocked with a clear error.
• Empty or overly long titles are rejected locally with a helpful message.
• Only board members are allowed to update the board: an unknown board ID returns "not found", while a non-member receives "Not allowed to rename this board".

# Rename a board by ID
hypertask project update 4060 --title "Agents & Infra"

# Update the description as well
hypertask project update 4060 --title "Agents & Infra" --description "<p>Infrastructure-related tasks and boards.</p>"

Behavior change Renaming a board from the app previously did not check board membership; agents and users could rename boards they were not members of. Board updates now require write access to the board. Only board members are allowed to update the board. (HTPR-6846)

---

You can also manage board columns and saved views with:

• hypertask view create — Create a saved view.
• hypertask view list — List saved views for a project.
• hypertask view switch <view-id> — Switch to a saved view.

For more options, run hypertask project --help, hypertask view --help, or hypertask tasks --help.

Delete a board from the CLI

Only the board owner or a board admin can delete a board. Sign in to the CLI with an account or token that has that permission.

Caution

Deletion removes the board and all its tasks. It cannot be undone through the CLI. Check the board ID before continuing. To keep the board for later, archive it instead.

First, check the board you want to delete:

hypertask project show <board-id>

Then delete it with explicit confirmation:

hypertask project delete <board-id> --yes

Replace <board-id> with the board's numeric ID. Without --yes, the CLI refuses to delete it. Ordinary board membership is not enough.

The board must be active. If it is archived, ask its owner to restore it before deleting:

hypertask project archive <board-id> --restore

For a reversible alternative, the board owner can archive it:

hypertask project archive <board-id>