gantt-board/scripts/README.md

# Gantt Board CLI Tools

Complete command-line interface for the Gantt Board. All web UI operations available via CLI.

## Quick Start

```bash
# List all tasks
./scripts/gantt.sh task list

# Create a task
./scripts/gantt.sh task create "Fix login bug" open high

# Create task with natural language
./scripts/gantt.sh task natural "Research TTS options by Friday, high priority"

# Update task
./scripts/gantt.sh task update <task-id> status done

# Add comment
./scripts/gantt.sh task comment <task-id> "Working on this now"

# Attach file
./scripts/gantt.sh task attach <task-id> ./notes.md
```

## Main CLI: `gantt.sh`

A unified CLI that covers all API operations.

### Task Commands

```bash
# List tasks (optionally filter by status)
./scripts/gantt.sh task list
./scripts/gantt.sh task list open
./scripts/gantt.sh task list in-progress

# Get specific task
./scripts/gantt.sh task get <task-id>

# Create task
./scripts/gantt.sh task create <title> [status] [priority] [project-id]
./scripts/gantt.sh task create "Fix bug" open high 1

# Create from natural language
./scripts/gantt.sh task natural "Fix login bug by Friday, assign to Matt, high priority"

# Update any field
./scripts/gantt.sh task update <task-id> <field> <value>
./scripts/gantt.sh task update abc-123 status done
./scripts/gantt.sh task update abc-123 priority urgent
./scripts/gantt.sh task update abc-123 title "New title"
./scripts/gantt.sh task update abc-123 assigneeId <user-id>

# Delete task
./scripts/gantt.sh task delete <task-id>

# Add comment
./scripts/gantt.sh task comment <task-id> "Your comment here"

# Attach file
./scripts/gantt.sh task attach <task-id> <file-path>
./scripts/gantt.sh task attach abc-123 ./research.pdf
```

### Project Commands

```bash
# List all projects
./scripts/gantt.sh project list
```

### Sprint Commands

```bash
# List all sprints
./scripts/gantt.sh sprint list
```

### Auth Commands

```bash
# Check current session
./scripts/gantt.sh auth session

# Log in
./scripts/gantt.sh auth login <email> <password>

# Log out
./scripts/gantt.sh auth logout
```

### Debug

```bash
# Call debug endpoint
./scripts/gantt.sh debug
```

## Legacy Scripts (Supabase Direct)

These scripts use Supabase directly (not the API) and work without the web server running:

### `gantt-task-crud.sh` - Direct Supabase Task Operations

Uses Supabase REST API directly with service role key.

```bash
./scripts/gantt-task-crud.sh list              # List all tasks
./scripts/gantt-task-crud.sh list open         # List open tasks
./scripts/gantt-task-crud.sh get <task-id>     # Get specific task
./scripts/gantt-task-crud.sh create "Title"    # Create task
./scripts/gantt-task-crud.sh update <id> field value  # Update field
./scripts/gantt-task-crud.sh delete <task-id>  # Delete task
```

### `attach-file.sh` - Direct Supabase File Attachments

```bash
./scripts/attach-file.sh <task-id> <file-path>
```

Supports: md, txt, json, pdf, png, jpg, gif

### `view-attachment.sh` - View Attached Files

```bash
./scripts/view-attachment.sh <task-id> [index]
```

Displays text files in terminal, saves binary files to `/tmp/`.

## API Coverage Matrix

| Feature | Web UI | gantt.sh (API) | Legacy Scripts (Supabase) |
|---------|--------|----------------|---------------------------|
| List tasks | ✅ | ✅ | ✅ |
| Get task | ✅ | ✅ | ✅ |
| Create task | ✅ | ✅ | ✅ |
| Natural language create | ✅ | ✅ | ❌ |
| Update task | ✅ | ✅ | ✅ |
| Delete task | ✅ | ✅ | ✅ |
| Add comment | ✅ | ✅ | ❌ |
| Attach file | ✅ | ✅ | ✅ |
| List projects | ✅ | ✅ | ❌ |
| List sprints | ✅ | ✅ | ❌ |
| Auth login/logout | ✅ | ✅ | ❌ |
| View attachments | ✅ | ❌ | ✅ |

### Auditing Coverage

Use the audit script to verify CLI stays in sync with API:

```bash
./scripts/audit-cli-coverage.sh
```

This scans all API routes and checks that each has a matching CLI command. Run this before committing any API changes to ensure Rule 2.5 compliance.

## Requirements

- `curl` - HTTP requests (built into macOS)
- `jq` - JSON parsing: `brew install jq`

## Environment Variables

```bash
# Override API URL
export API_URL=http://localhost:3001/api
./scripts/gantt.sh task list
```

## Common Workflows

### Create Task with Natural Language

```bash
./scripts/gantt.sh task natural "Fix the login bug by Friday, high priority, assign to Matt"
```

### Complete Task with Documentation

```bash
# Add completion comment
./scripts/gantt.sh task comment abc-123 "Completed. See attached notes."

# Attach notes
./scripts/gantt.sh task attach abc-123 ./completion-notes.md

# Mark done
./scripts/gantt.sh task update abc-123 status done
```

### Find Tasks

```bash
# All open tasks
./scripts/gantt.sh task list open

# Filter with jq
./scripts/gantt.sh task list | jq '.[] | select(.priority == "urgent") | {id, title}'
```

## Which Script to Use?

**Use `gantt.sh` (API) when:**
- Web server is running
- You want natural language task creation
- You need to add comments
- You want to use the same API as the web UI

**Use legacy scripts (Supabase) when:**
- Web server is not running
- You need to view attachment content
- You want direct database access

## Troubleshooting

### "jq: command not found"
```bash
brew install jq
```

### "API call failed (HTTP 401)"
- Check that you're logged in: `./scripts/gantt.sh auth session`
- Log in: `./scripts/gantt.sh auth login <email> <password>`

### "API call failed (HTTP 500)"
- Check that the dev server is running: `npm run dev`
- Check server logs for errors

### Task ID format
Task IDs are UUIDs like `33ebc71e-7d40-456c-8f98-bb3578d2bb2b`. Find them:
- In the URL when viewing a task
- From `task list` output
- From `task create` output

## Tips

1. **Tab completion:** Add `source <(./scripts/gantt.sh completion bash)` to your `.bashrc`
2. **jq filtering:** Pipe output to `jq` for precise data extraction
3. **Task URLs:** `https://gantt-board.vercel.app/tasks/<task-id>`
4. **Always verify:** After attach/update, run `task get` to confirm