npm package: @hypertask/hypertask_cli
Description: Production CLI tool for HyperTask task management system
Latest version: 0.0.63

# HyperTask CLI

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

## Installation

```bash
npm install -g @hypertask/hypertask_cli
```

Or use directly without installing:

```bash
npx @hypertask/hypertask_cli <command>
```

## Quick Start

### 1. Authenticate

Log in to your HyperTask account via the browser:

```bash
hypertask login
```

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

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

### 2. Check Status

```bash
hypertask auth:status
```

### 3. Get Your Context

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

## Commands

### Authentication

```bash
# 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

```bash
# 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

```bash
# 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
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>]

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

### Search & Comments

```bash
# 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

```bash
# List inbox items
hypertask inbox:list

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

## Global Options

```bash
# 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`:

```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:

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

## Examples

### Search and assign

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

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

### Create and comment

```bash
# 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

```bash
# 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:

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

```bash
# 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:

```bash
npm install -g @hypertask/hypertask_cli
# or
npx @hypertask/hypertask_cli <command>
```

### Token expired

Log in again to get a new token:

```bash
hypertask login
```

## Development

See [HYPERTASK.md](./HYPERTASK.md) for detailed CLI command reference and development guide.

See [CLI_READY.md](./CLI_READY.md) for implementation status and roadmap.

## License

MIT