CLI Reference

The Hypertask CLI (hypertask) lets you manage tasks, projects, comments, and notifications directly from your terminal. It is the fastest way to interact with Hypertask programmatically and is the recommended interface for AI agents like Claude Code.

Installation

npm install -g @hypertask/hypertask_cli

Verify the installation:

hypertask --version

Tip

In-app shortcut: Press Ctrl+K in Hypertask and search for CLI to open the CLI install dialog, which shows the install command and walks you through authentication without leaving the app. The dialog also links directly to the MCP token setup if you want to connect an AI agent at the same time.

Caution

The CLI package has moved to @hypertask/hypertask_cli. If you previously installed hypertask_cli (without the scope), uninstall it first: npm uninstall -g hypertask_cli

Authentication

1. Login via browser (recommended):

   hypertask login

   This opens your browser to authenticate and saves the token locally.

2. Login with a token (for CI/headless environments):

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

3. Check your auth status:

   hypertask auth:status

4. Logout:

   hypertask logout

Tip

For legacy setups, hypertask auth:login —token <jwt> also works to save a token directly. You can also pass —api-url to point at a custom API endpoint.

Global Options

These flags can be used with any command:

Flag	Description
--token <jwt>	Override the saved JWT token for this invocation
--api-url <url>	Override the API URL (default: https://app.hypertask.ai/api)
--json	Output raw JSON instead of formatted text
-V, --version	Print the CLI version
-h, --help	Show help for any command

# Get JSON output for scripting
hypertask task list --project 15 --json

# Use a different token for a one-off command
hypertask task list --project 15 --token eyJhbG...

---

Capability Discovery

capabilities / commands

Dump the full CLI command and option tree as machine-readable JSON. This is the fastest way for an agent or script to enumerate every command, flag, and description in one call — no recursive --help grepping needed.

hypertask capabilities --json

commands is an alias for capabilities; both are identical.

Flag	Description
--json	Output as JSON (recommended for programmatic use)

Sample output (abbreviated):

[
  {
    "name": "task create",
    "description": "Create a new task",
    "options": [
      { "flags": "--project <id>",        "description": "Project ID (required)" },
      { "flags": "--title <text>",         "description": "Task title (required)" },
      { "flags": "--attach <path-or-url>", "description": "Attach a local file or URL (repeatable)" }
    ]
  },
  {
    "name": "task update",
    "description": "Update an existing task",
    "options": [
      { "flags": "--attach <path>", "description": "Attach a local file (repeatable)" }
    ]
  },
  {
    "name": "comment add",
    "description": "Add a comment to a task",
    "options": [
      { "flags": "--attach <path-or-url>", "description": "Attach a local file or URL to the comment (repeatable)" }
    ]
  }
]

Tip

For AI agents: hypertask capabilities --json is the recommended starting point for any agent that drives the CLI. All three locations where --attach is supported — task create, task update, and comment add — appear explicitly in the output, so agents do not need to infer capability from subcommand help text.

---

Tasks

task list

List tasks with filters.

hypertask task list --project 15 --section "Doing" --assigned-to me

Flag	Description	Default
--project <id>	Filter by project ID	—
--section <name>	Filter by section name	—
--assigned-to <value>	Filter by assignee: me, unassigned, or a user ID	—
--created-by <id>	Filter by creator user ID (numeric)	—
--priority <list>	Comma-separated priorities: urgent, high, medium, low	—
--sort-by <field>	Sort results by createdAt, updatedAt, or dueDate	—
--sort-order <asc|desc>	Sort direction — use together with --sort-by	—
--limit <n>	Results per page	10
--offset <n>	Pagination offset	0

# High-priority tasks assigned to you
hypertask task list --project 15 --assigned-to me --priority urgent,high

# Most recently updated tasks first
hypertask task list --project 15 --sort-by updatedAt --sort-order desc

# Page through results
hypertask task list --project 15 --limit 20 --offset 20

Note

File attachments are not on task list — use task create --attach or task update --attach to attach files. See the Capability Discovery section or run hypertask capabilities --json to see all commands that support --attach.

task get / task show

Get full details of a single task by its ticket number or numeric task ID. Response includes labels, parent_id for subtasks, and the task URL.

hypertask task get HTPR-2992
hypertask task show HTPR-2992   # alias for task get
hypertask task get 1234

Argument	Description
<ticket>	Ticket identifier (e.g., HTPR-2992) or numeric task ID

Tip

task show is an alias for task get — both commands are identical.

task tree

Show the full parent/subtask hierarchy for a task. Displays the family tree of a task including all parents and children.

hypertask task tree --ticket HTPR-2992

Flag	Description	Default
--ticket <ticket>	Ticket number (e.g., HTPR-2992)	—
--task-id <id>	Numeric task ID	—
--depth <n>	Max levels deep to show	Full tree

# Show subtask tree by ticket number
hypertask task tree --ticket HTPR-2992

# Show subtask tree by task ID, limited to 2 levels deep
hypertask task tree --task-id 1234 --depth 2

task create

Create a new task.

hypertask task create \
  --project 15 \
  --title "Implement dark mode toggle" \
  --description "<p>Add a toggle switch in the settings panel to switch between light and dark themes.</p>" \
  --priority high \
  --labels "frontend,UX" \
  --estimate 3 \
  --due 2026-04-01

Flag	Description
--project <id>	Project ID (required)
--title <text>	Task title (required)
--description <text>	Task description (HTML format; plain text is auto-wrapped in <p> tags)
--priority <p>	Priority: urgent, high, medium, low, none
--estimate <n>	Story points
--labels <list>	Comma-separated label names or IDs (e.g., "CLI,BUG")
--due <date>	Due date in ISO 8601 format (e.g., 2026-04-01)
--parent-task <id>	Parent task ID — creates this task as a subtask
--section <id|name>	Section ID or name (e.g., 4005 or "Doing")
--assignee <list>	Comma-separated user IDs to assign (e.g., "42" or "42,99")
--attach <path-or-url>	Attach a local file or URL (repeatable for multiple attachments)

# Create a subtask under an existing task
hypertask task create \
  --project 15 \
  --title "Design the toggle component" \
  --parent-task 1234 \
  --priority medium

# Create a task with file attachments
hypertask task create \
  --project 15 \
  --title "Review mockups" \
  --attach ./mockup.png \
  --attach https://example.com/spec.pdf

Note

Descriptions use HTML format, not Markdown. Wrap text in <p> tags and use standard HTML elements like <ul>, <ol>, <code>, and <strong>. If you pass plain text without HTML tags, the CLI automatically wraps it in <p>…</p> before sending to the API.

task update

Update an existing task’s properties.

hypertask task update HTPR-2992 --priority urgent --due 2026-03-25

Flag	Description
--title <text>	New title
--description <text>	New description (plain text or HTML; plain text is auto-wrapped in <p> tags)
--priority <p>	New priority
--estimate <n>	New story points
--due <date>	New due date (ISO 8601)
--status <s>	Lifecycle status: Normal, Archive, or Deleted
--section <id|name>	Section (board column): ID or name like "Doing", "Done"
--project <id>	Project ID (required when using --section with a name across projects)
--assignee <list>	Comma-separated user IDs to assign (e.g., "42" or "42,99")
--labels <list>	Comma-separated label names or IDs
--attach <path>	Attach a local file (repeatable)

Note

Status vs. Section: These are two different concepts. Use --status for the task lifecycle (active, archived, or deleted). Use --section to move a task between board columns (e.g., from “Backlog” to “Doing”). The --status flag only accepts Normal, Archive, or Deleted — not section names.

# Move a task to the "Doing" section
hypertask task update HTPR-2992 --section "Doing"

# Archive a completed task
hypertask task update HTPR-2992 --status Archive

# Update labels
hypertask task update HTPR-2992 --labels "CLI,reviewed"

task assign

Assign a user to a task.

hypertask task assign HTPR-2992 --user 42

Flag	Description
--user <id>	User ID to assign

Tip

To find user IDs, use hypertask project members <project-id>.

task move

Move a task to a different section within the same board, or to a different project entirely.

# Move within the same board
hypertask task move HTPR-2992 --section "Done"

# Move to a different project
hypertask task move HTPR-2992 --to 20 --to-section 5010

Flag	Description
--section <name>	Destination section name within the same board (e.g., "Doing", "Done")
--to <id>	Target project ID — move to a different project
--to-section <id>	Target section ID in the destination project (use with --to)

task move-board

Move a task to a different project/board entirely. Alias: task move-project.

hypertask task move-board HTPR-2992 --target-project 20 --target-section 5010

Flag	Description
--target-project <id>	Target project ID
--target-section <id>	Target section ID

---

Projects

project list

List all projects you have access to.

hypertask project list

Flag	Description	Default
--limit <n>	Results per page	10
--offset <n>	Pagination offset	0

project sections

List all sections (columns) in a project.

hypertask project sections 15

Argument	Description
<project-id>	The project ID

project members

List all members of a project.

hypertask project members 15

Argument	Description
<project-id>	The project ID

project invite

Invite a user to a project by email address. The invited user receives an email invitation and gains access once they accept.

hypertask project invite 15 --email teammate@example.com

Argument	Description
<project-id>	The project ID (required)

Flag	Description
--email <address>	Email address of the person to invite (required)

# Invite a new team member to project 15
hypertask project invite 15 --email alice@example.com

# Confirm current members after inviting
hypertask project members 15

Tip

If the invitee already has a Hypertask account, they are added to the project immediately. New users receive an email to complete sign-up before accessing the project.

project labels

List available labels for a project.

hypertask project labels 15

Argument	Description
<project-id>	The project ID

project section create

Create a new section (column) on a board.

hypertask project section create --project 15 --title "In Review" --after 4005

Flag	Description
--project <id>	Project ID (required)
--title <text>	Section title (required)
--after <section-id>	Insert after this existing section (optional)

project label create

Create a new label in a project.

hypertask project label create --project 15 --name "CLI"

Flag	Description
--project <id>	Project ID (required)
--name <text>	Label name (required)

project create-board

Create a whole new board from a JSON manifest — sections, labels, and starter tasks in one call. Uses the same manifest shape as the hypertask_create_board MCP tool.

hypertask project create-board --file board.json

Example board.json:

{
  "team_id": 3,
  "title": "Website Redesign",
  "sections": [
    { "title": "Backlog" },
    { "title": "Doing" },
    { "title": "Done" }
  ],
  "labels": [
    { "name": "Design" },
    { "name": "Frontend" }
  ],
  "tasks": [
    {
      "title": "Wireframe the homepage",
      "section": "Backlog",
      "labels": ["Design"],
      "priority": "high"
    }
  ]
}

Flag	Description
--file <path>	Path to a JSON manifest (required)

Tip

team_id is required. To find yours, run hypertask context —json and look for the teams array.

---

Search

search

Search for tasks by keyword.

hypertask search "dark mode" --project 15 --limit 5

Argument / Flag	Description	Default
<query>	Search query (required)	—
--project <id>	Restrict search to a project	—
--limit <n>	Maximum results	10

---

Comments

comment list

List all comments on a task.

hypertask comment list HTPR-2992

Argument	Description
<ticket>	Ticket identifier

comment add

Add a comment to a task.

hypertask comment add HTPR-2992 --text "<p>Looks good, merging now.</p>"

Flag	Description
--text <text>	Comment text (HTML format)
--attach <path-or-url>	Attach a local file or URL to the comment (repeatable for multiple attachments)

# Attach a file alongside a comment
hypertask comment add HTPR-2992 \
  --text "<p>Screenshot of the issue attached.</p>" \
  --attach ./screenshot.png

# Attach a remote URL
hypertask comment add HTPR-2992 \
  --text "<p>See the Loom recording for full context.</p>" \
  --attach https://www.loom.com/share/abc123

Tip

Plain @Name mentions work. Writing @Alice in your comment text is resolved server-side — Hypertask looks up the matching project member by name and sends them a notification automatically. No need to write span markup by hand.

hypertask comment add HTPR-2992 --text "<p>@Alice this is ready for your review.</p>"

Note: plain @Name resolution applies to comment add only. Comment updates and task descriptions do not yet support server-side mention resolution.

comment update

Update an existing comment.

hypertask comment update 8450 --text "<p>Updated: shipped in v2.1.0</p>"

Argument / Flag	Description
<id>	Comment ID
--text <text>	New comment text (HTML format)

comment delete

Delete a comment.

hypertask comment delete 8450

Argument	Description
<id>	Comment ID

---

Inbox (Notifications)

inbox list

List your unread notifications.

hypertask inbox list

inbox archive

Archive one or more notifications by ID.

hypertask inbox archive 101 102 103

Argument	Description
<ids...>	One or more notification IDs to archive

---

Context

context

Retrieve your user context, including projects and permissions.

hypertask context

This is useful to verify your identity, see which projects you belong to, and check your role/permissions.

---

Utility Commands

Command	Description
hypertask capabilities	Dump the full command + option tree as JSON (alias: commands)
hypertask update	Update the CLI to the latest version
hypertask auth:status	Check current authentication status
hypertask auth:login --token <jwt>	Save a JWT token directly
hypertask auth:logout	Clear saved authentication
hypertask logout	Logout from Hypertask

---

Common Workflows

Pick up a task from your inbox

# 1. Check notifications
hypertask inbox list

# 2. Read the task details
hypertask task get HTPR-2992
# or use the alias
hypertask task show HTPR-2992

# 3. Move it to "Doing"
hypertask task move HTPR-2992 --section "Doing"

# 4. Archive the notification
hypertask inbox archive 101

Create and assign a task

# 1. Find the project and its members
hypertask project list
hypertask project members 15

# 2. Create the task
hypertask task create \
  --project 15 \
  --title "Fix login timeout issue" \
  --description "<p>Users are getting logged out after 5 minutes of inactivity. Expected session length is 24 hours.</p>" \
  --priority urgent \
  --labels "bug,auth"

# 3. Assign it (use the user ID from project members)
hypertask task assign HTPR-3050 --user 42

Invite a team member to a project

# 1. Invite them by email
hypertask project invite 15 --email newmember@example.com

# 2. Confirm they appear in the member list (once they accept)
hypertask project members 15

Triage tasks by priority

# List all urgent and high-priority tasks
hypertask task list --project 15 --priority urgent,high

# Review unassigned tasks
hypertask task list --project 15 --assigned-to unassigned

# Search for something specific
hypertask search "payment" --project 15

Complete a task

# 1. Add a final comment (plain @mention works)
hypertask comment add HTPR-2992 --text "<p>Deployed to production. Verified working. @Alice please close this out.</p>"

# 2. Move to Done
hypertask task move HTPR-2992 --section "Done"

Attach files to a task or comment

# Attach files when creating a task
hypertask task create \
  --project 15 \
  --title "Review design assets" \
  --attach ./wireframe.pdf \
  --attach ./mockup.png

# Attach a file to an existing task
hypertask task update HTPR-2992 --attach ./final-spec.pdf

# Attach a file or URL alongside a comment
hypertask comment add HTPR-2992 \
  --text "<p>Added the updated spec.</p>" \
  --attach ./updated-spec.pdf

Discover all CLI capabilities (for agents)

# Dump the full command + option tree as JSON
hypertask capabilities --json

# Pipe to jq to find every command that supports --attach
hypertask capabilities --json | jq '[.[] | select(.options[]?.flags | contains("--attach"))]'

Use JSON output for scripting

# Pipe task data to jq
hypertask task list --project 15 --json | jq '.[].title'

# Get a task's priority
hypertask task get HTPR-2992 --json | jq '.priority'