HyperTask CLI

A command-line interface for managing HyperTasks from your terminal. Built with TypeScript and Commander.js.

Installation

npm install -g hypertask_cli

Or use directly without installing:

npx hypertask_cli <command>

Quick Start

1. Authenticate

Log in to your HyperTask account via the browser:

hypertask login

If you are on a headless server without a browser, you can paste your token directly:

hypertask login --token <your-jwt-token>

2. Check Status

hypertask auth:status

3. Get Your Context

hypertask context
# Shows: user info, accessible boards, permissions

Commands

Authentication

# Interactive browser login
hypertask login

# Headless/CI login (skip browser)
hypertask login --token <jwt> [--api-url <url>]

# Check authentication status
hypertask auth:status

# Logout (clear saved session)
hypertask logout

# Update CLI to latest version
hypertask update

Projects & Boards

# List accessible projects
hypertask project list

# List sections/columns in a board
hypertask project sections <project-id>

# Create a new section/column
hypertask project section create --project <id> --title "In Review" [--after <section-id>]

# List team members
hypertask project members <project-id>

# List labels in a project
hypertask project labels <project-id>

# Create a new label in a project
hypertask project label create --project <id> --name "Label"

Tasks

# List tasks in a project
hypertask task list [options]

# Get details for a specific task (includes labels, task URL)
hypertask task get <task-id|ticket-number>

# Create a new task (outputs task URL)
hypertask task create --project <id> --title "Task title" [options]

# List available labels for a project (to find names/IDs)
hypertask project labels <project-id>

# Update a task (--title, --description, --labels, etc.; outputs task URL)
hypertask task update <task-id|ticket-number> [options]

# Assign a user to a task
hypertask task assign <task-id|ticket-number> --user <user-id>

# Move a task between sections (e.g. from To Do to Doing)
hypertask task move <task-id|ticket-number> --section "Doing"

# Move a task to a different project
hypertask task move <task-id|ticket-number> --to <project-id> [--to-section <section-id>]

# Move a task between projects/boards (alias: move-project)
hypertask task move-board <task-id|ticket-number> --target-project <project-id> [--target-section <section-id>]

Search & Comments

# Search for tasks
hypertask search "query" [options]

# List comments on a task
hypertask comment list <task-id|ticket-number>

# Add a comment
hypertask comment add <task-id|ticket-number> --text "Your comment"

# Update a comment
hypertask comment update <comment-id> --text "Updated text"

# Delete a comment
hypertask comment delete <comment-id>

Inbox

# List inbox items
hypertask inbox:list

# Archive inbox items
hypertask inbox:archive <notification-id> [--all]

Global Options

# Override saved JWT token
hypertask <command> --token <jwt>

# Override API URL
hypertask <command> --api-url <url>

# Output as JSON (for scripting)
hypertask <command> --json

# Show help
hypertask --help
hypertask <command> --help

Configuration

Token and API URL are saved in ~/.hypertask/config.json:

{
  "token": "your-jwt-token",
  "apiUrl": "https://api.hypertasks.com/api"
}

You can manually edit this file or use auth:login to update it.

JSON Output

All commands support --json for programmatic use:

hypertask project list --json | jq '.projects[] | .title'

Examples

Search and assign

# Search for tasks
hypertask search "authentication" --json

# Assign task to user
hypertask task assign HTPR-3644 --user 42

Create and comment

# Create a task
hypertask task create --project 1 --title "New feature" \
  --description "Implementation details" \
  --priority High

# Add a comment
hypertask comment add HTPR-3644 --text "Working on this now"

Bulk operations

# List all tasks in JSON, filter with jq
hypertask task list --project 1 --json | \
  jq '.tasks[] | select(.status == "Open") | .id'

Update Notifications

The CLI automatically checks for updates once per day. Note: update-notifier uses a two-run cycle:

• First run: Checks for updates in the background (no notification shown)
• Second run: Shows notification if an update was found on the first run

This is by design to avoid blocking your CLI commands. If you want to check for updates immediately, use:

# Check for updates and install automatically (immediate check)
hypertask update

# Check for updates (JSON output)
hypertask update --json

The hypertask update command checks npm registry directly and shows results immediately, regardless of the two-run cycle.

Update notifications are automatically suppressed when using --json flag to avoid polluting JSON output.

Troubleshooting

"No authentication token found"

# Login via browser
hypertask login

# Or use the environment variable
export HYPERTASKS_JWT_TOKEN=your-token
hypertask <command>

"Cannot find module"

Make sure the package is properly installed:

npm install -g hypertask_cli
# or
npx hypertask_cli <command>

Token expired

Log in again to get a new token:

hypertask login

Development

See HYPERTASK.md for detailed CLI command reference and development guide.

See CLI_READY.md for implementation status and roadmap.

License

MIT