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.

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://raw.githubusercontent.com/hypertask-ai/cli/8a9245246cec8ddac4ab1dfccae5c5cba5c39707/scripts/install.sh | 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, download the native executable with PowerShell:

Invoke-WebRequest https://github.com/hypertask-ai/cli/releases/latest/download/hypertask-windows-x86_64.exe -OutFile hypertask.exe
.\hypertask.exe --version

Move hypertask.exe to a directory on your PATH to run it from any terminal.

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.

Migrate from the Node CLI

We’ve shipped the native htz CLI and published an npm shim so you can install it the same way you did before:

npm install -g @hypertask/hypertask_cli@latest

Remove the old npm package before installing so its global shim cannot hide the native binary:

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

Most commands and flags stay the same. The native CLI also accepts direct top-level section commands such as hypertask section create.

Claims and Parity Tests

The Hypertask CLI includes an automated parity test (hypertask parity_test.py) that validates end-to-end behavior against the documented CLI contract.

What the parity test checks

The hypertask parity_test.py harness performs comprehensive comparison against the served Node implementation:

• JSON schema verification — Compares output against 30 read-only JSON schemas for list, create, and detail operations.
• Authentication matrix — Verifies correct response for each supported token flow (API key, session cookie, auth header combination).
• Human-output parity — Includes tests for --human (human-oriented label rendering) and human-oriented tables.
• Negative case coverage — Rejects unauthenticated access for operations that require authentication using the documented error contract.
• Exit-code and finally output — Validates that the installed htz CLI yields documented exit codes and fallback messages compared to the Node CLI.

Running the harness locally

# Quick check for recent merge
npx @hypertask/parity-test-cli@latest

# Custom path to the Node distribution
npx @hypertask/parity-test-cli@latest --node-dist /path/to/cli.tar.gz

The parity test ensures that any change to hypertask list, hypertask get, hypertask create, hypertask update, or any other command does not introduce regressions compared to the published contract.

API and routing parity

The parity harness confirms that hypertask maps to the latest route contract supporting authenticated read-only flows. PR #20 includes six parity tests (cases) and coverage confirms:

• IndexedDB-backed fetch and rendering (no pings to upstream).
• Token-source precedence (API keys versus session cookies).
• 30 previously defined read-only JSON schemas.

These tests validate both positional params and flags against the server contract. All checks pass in local and live runs, confirming CLI behavior aligns with the documented contract.