HyperTask CLI

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

Installation

npm install -g @hypertask/hypertask_cli

Or use directly without installing:

npx @hypertask/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

Agent management

Create, revoke, and rotate agents with an htmk_ management key or your normal user MCP JWT. Save a management key once, provide it per command, or set it in the environment:

# Save the key in ~/.hypertask/config.json
hypertask token set-management-key <htmk_...>

# Or use HYPERTASK_MANAGEMENT_KEY without saving it
export HYPERTASK_MANAGEMENT_KEY=<htmk_...>

# Create an agent. Repeat --project to add it to multiple boards.
hypertask agents create --name "Release Agent" --project 15 --project 42

# Use a key for one request only
hypertask agents create --name "Release Agent" --management-key <htmk_...>

# Revoke an agent or rotate its bearer token
hypertask agents revoke --id <agent_id>
hypertask agents rotate-token --id <agent_id>

Create and rotate print the bearer token once. Store it securely. Add --json to any command for structured output.

Agent-management auth resolves in this order:

1. --management-key <htmk_...>
2. HYPERTASK_MANAGEMENT_KEY
3. managementKey in ~/.hypertask/config.json
4. The normal CLI JWT chain (--token, HYPERTASKS_JWT_TOKEN, saved token)

Management keys can be created with POST /api/mcp/admin/keys using {"name":"...","scope":"management"} or scope: "full". The API currently has no management-authenticated agent-list endpoint, so the CLI does not expose hypertask agents list.

Projects & Boards

# List accessible projects
hypertask project list

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

# Add a member to board
hypertask project invite <project-id> --user <id|email>

# 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"

Sections

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

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

# Rename a specific section
hypertask section rename --section <id> --project <id> --title "New-title"

# Deleting a section
hypertask section delete --section <id> --project <id>

Custom Fields

# List custom fields defined on a project
hypertask fields list --project <id>

# Create a field (idempotent: re-running with the same name returns the existing field)
hypertask fields create --project <id> --name "ICE" [--type Number|Text|Select|Date]
hypertask fields create --project <id> --name "Priority" --type Select --options '["Low","Medium","High"]'

# Set a field's value on a task (auto-creates the field on that board if --name doesn't exist yet)
hypertask fields set <task-id|ticket-number> --name "ICE" --value 42

# Print a task's custom field values
hypertask fields get <ticket-number>

# Delete a field and all its values
hypertask fields delete --field-id <uuid>
hypertask fields delete --project <id> --name "ICE"

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]

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

# Assign a user to a task (idempotent) / remove a user from assignees
hypertask task assign <task-id|ticket-number> --user <user-id>
hypertask task unassign <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>]

# Show full parent/subtask hierarchy for a task
hypertask task tree --task-id <task-id> [options]

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>

Drafts

# Create a draft
hypertask draft create <ticket> --text <text> [options]

# List all drafts in ticket
hypertask draft list <ticket>

# Update a draft
hypertask draft update <draft-id> --text <text>

# Publish a draft
hypertask draft publish <draft-id>        

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

Inbox

# List inbox items
hypertask inbox:list

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

AI writing

Runs the same AI Task Writer and Write with AI the app uses, including board context, your custom instructions, and skills.

# Draft a ticket from scratch
hypertask ai write "the nightly sync skips archived boards" --project 15

# Rewrite an existing ticket (its title and description become context)
hypertask ai write "tighten this" --task HTPR-4650

# Write the result back: title, priority and size land on the task's fields,
# the prose goes in the description - the same as Accept in the UI
hypertask ai write "tighten this" --task HTPR-4650 --apply

# Draft a comment instead of a description
hypertask ai write "status update on the fix" --task HTPR-4650 --mode write-with-ai --apply

# Invoke a skill by putting its /slug in the prompt, as in AI chat
hypertask ai write "/standup summarise this week" --project 15

Piped output is the raw HTML, so it can be fed straight into another command:

hypertask tasks create --project 15 --title "Sync fix" \
  --description "$(hypertask ai write "the nightly sync skips archived boards" --project 15)"

The model is not a flag: it follows the board's AI settings and your personal per-feature preference, exactly as it does in the app.

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

JWT, optional management key, and API URL are saved in ~/.hypertask/config.json:

{
  "token": "your-jwt-token",
  "managementKey": "htmk_...",
  "apiUrl": "https://api.hypertask.ai/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/hypertask_cli
# or
npx @hypertask/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