CLI Reference

The Hypertask CLI (htz) lets you manage tasks, projects, comments, and notifications directly from your terminal. At v0.2.0, htz is the only official Hypertask CLI; the legacy Node CLI (@hypertask/hypertask_cli) has been retired and is no longer maintained.

Migrate from legacy CLI

If you’re currently using the Node CLI (hypertask or @hypertask/hypertask_cli), follow these steps to switch to htz:

Node CLI command	htz command	Notes
`hypertask task create`	`htz task create`	Flags map 1:1
`hypertask task list`	`htz task list`	Add filters with flags
`hypertask task get`	`htz task show`	`task show` is an alias for `task get`
`hypertask project list`	`htz project list`	Same behavior
`hypertask capabilities`	`htz capabilities`	Lists all available commands
`hypertask login`	`htz login`	Same authentication flow

Most commands and flags work the same way. The main difference is that htz avoids the --json requirement for human-readable tables and prints a clean card-style output by default.

Example migration

Before:

hypertask task create \
  --project 15 \
  --title "Implement dark mode toggle"

After (same flags, different binary):

htz task create \
  --project 15 \
  --title "Implement dark mode toggle"

Remove the Node CLI

Once you’ve verified htz works for your workflows, uninstall the Node package:

npm uninstall -g @hypertask/hypertask_cli

If you still have the legacy binary source locally, you can safely archive or delete it.

Authentication

Login via browser (recommended):
Terminal window
```
htz login
```
This opens your browser to authenticate and saves the token locally. After the api.hypertask.ai cutover, htz always routes login requests through the new API endpoint to avoid 404s and ensure reliable authentication.
Login with a token (for CI/headless environments):
Terminal window
```
htz login --token <your-jwt-token>
```
Check your auth status:
Terminal window
```
htz status
```
Logout:
Terminal window
```
htz logout
```

JWT expiry and auto-refresh ([HTPR-5797])

Behavior change The installed CLI now auto-refreshes saved JWTs before they expire and shows the exact UTC expiry date for older, non-rotating tokens. This prevents unexpected command failures due to expired credentials.

Auto-refresh behavior

Refresh-capable tokens (signed with a refresh-key and with sufficient leeway) are renewed automatically before they near their expiry edge.
For tokens that cannot rotate, the CLI displays the exact UTC expiry (e.g., Expires: 2026-09-05T00:00:00.000Z) so login is expected prior to expiration.
The refresh logic triggers during login when expiring, and whenever htz login discovers an expiring saved token; it does not rely on fixed timer intervals.

What happens when tokens expire

Refresh-capable: htz calls the refresh endpoint, updates the saved token, and succeeds.
Non-rotating: htz abandons the cookie/credential approach and instead expects you to run htz login to obtain a fresh token.

No additional flags are needed; the CLI decides per-token behavior silently, only surfacing the expiry date for non-rotating tokens.

Example output

$ htz status
Logged in via stored cookie; cookie valid for 7 days
$ htz login
Refreshing saved token… updated

For non-rotating tokens, login will replace the expiring credential with a fresh JWT and log the replacement retention window.

Exit Codes and Error Behavior

The CLI uses exit codes so scripts and CI pipelines can reliably detect failures. All subcommands that encounter an error exit non-zero with an accompanying message.

Exit Codes

Code	Meaning
`0`	Success
`1`	General runtime or API error (non-auth)
`4`	Authentication or authorization failure
`2`	Invalid usage — unknown or misspelled subcommand / missing required argument

Transient Failures

Bot-challenge 403s, rate limits, and certain gateway errors are retried automatically with exponential backoff instead of failing immediately. Starting from CLI 1.8.0:

Retried cases: 403 (bot challenge), 408 (Request Timeout), 429 (Rate Limit), 500 (Internal Server Error), 502 (Bad Gateway), 503 (Service Unavailable), 504 (Gateway Timeout)
Backoff sequence: retry attempts are spaced approximately 2 seconds, 10 seconds, and 30 seconds, then fail with a clear message

Not retried: 500 and bare network errors are intentionally not retried to avoid re-processing a write that has already succeeded, which could cause duplicates or unexpected side effects.

Non-fatal Errors

Starting from CLI 1.10.0, commands that encounter missing resources exit with a non-zero code and a clear error message instead of succeeding silently.

CLI Configuration Persistence

Environment variables HT_TOKEN, HYPERTASKS_JWT_TOKEN, and HYPERTASKS_API_URL can override your saved CLI configuration. Empty values in these variables now leave the saved settings intact, preserving your existing authentication and server URL for agent shells that run with empty exports. This prevents accidental config wipes and keeps long-running agent sessions properly authenticated.

# Agent shell with empty environment overrides retains CLI settings
EMPTY_TOKEN="" EMPTY_JWT_TOKEN="" EMPTY_API_URL="" ht agent start

# Previously, this would reset your settings to defaults

CLI API Routing

htz connects to the Hypertask API using a dedicated endpoint that is exempt from the Vercel bot challenge:

Default endpoint: https://api.hypertask.ai
Routing: CLI traffic is routed through api.hypertask.ai, not app.hypertask.ai/v1 or other public-facing endpoints
Benefit: Direct API access works reliably from VPS environments without intermittent 403s caused by bot-challenge checks

# htz automatically connects to the exempt API endpoint
htz task get HTPR-2992
htz status