Add CLI documentation for scripts folder
- Added comprehensive README.md documenting all 3 CLI scripts - Includes quick start, command reference, examples, workflows - Documents troubleshooting and common patterns - No code changes, docs only
This commit is contained in:
parent
70f4d78c0c
commit
98536e368d
240
scripts/README.md
Normal file
240
scripts/README.md
Normal file
@ -0,0 +1,240 @@
|
||||
# Gantt Board CLI Tools
|
||||
|
||||
Command-line interface for managing tasks without using the browser.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# List all tasks
|
||||
./scripts/gantt-task-crud.sh list
|
||||
|
||||
# List only open tasks
|
||||
./scripts/gantt-task-crud.sh list open
|
||||
|
||||
# Get specific task
|
||||
./scripts/gantt-task-crud.sh get <task-id>
|
||||
|
||||
# Create a new task
|
||||
./scripts/gantt-task-crud.sh create "Fix login bug" open high
|
||||
|
||||
# Update task status
|
||||
./scripts/gantt-task-crud.sh update <task-id> status done
|
||||
|
||||
# Attach a file to a task
|
||||
./scripts/attach-file.sh <task-id> ./document.pdf
|
||||
|
||||
# View attached file content
|
||||
./scripts/view-attachment.sh <task-id> 0
|
||||
```
|
||||
|
||||
## Scripts
|
||||
|
||||
### `gantt-task-crud.sh` - Task CRUD Operations
|
||||
|
||||
Full Create, Read, Update, Delete for tasks.
|
||||
|
||||
**Commands:**
|
||||
|
||||
| Command | Arguments | Description |
|
||||
|---------|-----------|-------------|
|
||||
| `list` | `[status]` | List all tasks (optional: filter by status) |
|
||||
| `get` | `<task-id>` | Get a specific task by ID |
|
||||
| `create` | `<title> [status] [priority] [project-id] [assignee-id]` | Create new task |
|
||||
| `update` | `<task-id> <field> <value>` | Update any task field |
|
||||
| `delete` | `<task-id>` | Delete a task |
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# List all tasks
|
||||
./scripts/gantt-task-crud.sh list
|
||||
|
||||
# List only tasks with status "in-progress"
|
||||
./scripts/gantt-task-crud.sh list in-progress
|
||||
|
||||
# Get a specific task
|
||||
./scripts/gantt-task-crud.sh get 33ebc71e-7d40-456c-8f98-bb3578d2bb2b
|
||||
|
||||
# Create a high priority open task
|
||||
./scripts/gantt-task-crud.sh create "Update documentation" open high
|
||||
|
||||
# Mark task as done
|
||||
./scripts/gantt-task-crud.sh update 33ebc71e-7d40-456c-8f98-bb3578d2bb2b status done
|
||||
|
||||
# Change priority
|
||||
./scripts/gantt-task-crud.sh update 33ebc71e-7d40-456c-8f98-bb3578d2bb2b priority urgent
|
||||
|
||||
# Assign to Matt (0a3e400c-3932-48ae-9b65-f3f9c6f26fe9)
|
||||
./scripts/gantt-task-crud.sh update 33ebc71e-7d40-456c-8f98-bb3578d2bb2b assignee_id 0a3e400c-3932-48ae-9b65-f3f9c6f26fe9
|
||||
|
||||
# Delete a task
|
||||
./scripts/gantt-task-crud.sh delete 33ebc71e-7d40-456c-8f98-bb3578d2bb2b
|
||||
```
|
||||
|
||||
**Default Values:**
|
||||
- Status: `open`
|
||||
- Priority: `medium`
|
||||
- Project ID: `1`
|
||||
- Assignee: Max (9c29cc99-81a1-4e75-8dff-cd7cc5ceb5aa)
|
||||
|
||||
---
|
||||
|
||||
### `attach-file.sh` - File Attachments
|
||||
|
||||
Attach files to tasks. Files are stored as base64 data URLs in the database.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
./scripts/attach-file.sh <task-id> <file-path>
|
||||
```
|
||||
|
||||
**Supported file types:**
|
||||
- `.md` / `.markdown` → `text/markdown`
|
||||
- `.txt` → `text/plain`
|
||||
- `.json` → `application/json`
|
||||
- `.pdf` → `application/pdf`
|
||||
- `.png` → `image/png`
|
||||
- `.jpg` / `.jpeg` → `image/jpeg`
|
||||
- `.gif` → `image/gif`
|
||||
- Other → `application/octet-stream`
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Attach a markdown file
|
||||
./scripts/attach-file.sh 33ebc71e-7d40-456c-8f98-bb3578d2bb2b ./research-notes.md
|
||||
|
||||
# Attach a PDF
|
||||
./scripts/attach-file.sh 33ebc71e-7d40-456c-8f98-bb3578d2bb2b ./specs.pdf
|
||||
|
||||
# Attach an image
|
||||
./scripts/attach-file.sh 33ebc71e-7d40-456c-8f98-bb3578d2bb2b ./screenshot.png
|
||||
```
|
||||
|
||||
**Verification:**
|
||||
```bash
|
||||
# Check attachment count after attaching
|
||||
./scripts/gantt-task-crud.sh get 33ebc71e-7d40-456c-8f98-bb3578d2bb2b | jq '.attachments | length'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `view-attachment.sh` - View Attached Files
|
||||
|
||||
View the content of attached files from the command line.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
./scripts/view-attachment.sh <task-id> [attachment-index]
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# View first attachment (index 0)
|
||||
./scripts/view-attachment.sh 33ebc71e-7d40-456c-8f98-bb3578d2bb2b
|
||||
|
||||
# View second attachment (index 1)
|
||||
./scripts/view-attachment.sh 33ebc71e-7d40-456c-8f98-bb3578d2bb2b 1
|
||||
|
||||
# List attachments first, then view
|
||||
./scripts/gantt-task-crud.sh get 33ebc71e-7d40-456c-8f98-bb3578d2bb2b | jq '.attachments[].name'
|
||||
```
|
||||
|
||||
**Text files** (md, txt, json) are displayed directly in the terminal.
|
||||
**Binary files** (pdf, images) are saved to `/tmp/` and you get the path to open them.
|
||||
|
||||
---
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Create Task and Attach File
|
||||
|
||||
```bash
|
||||
# Create the task
|
||||
TASK=$(./scripts/gantt-task-crud.sh create "Research iOS MRR" open high)
|
||||
TASK_ID=$(echo "$TASK" | jq -r '.id')
|
||||
|
||||
# Attach the research file
|
||||
./scripts/attach-file.sh "$TASK_ID" ./ios-mrr-research.md
|
||||
|
||||
# Verify attachment
|
||||
./scripts/gantt-task-crud.sh get "$TASK_ID" | jq '.attachments | length'
|
||||
```
|
||||
|
||||
### Complete a Task with Documentation
|
||||
|
||||
```bash
|
||||
# Attach completion notes first
|
||||
./scripts/attach-file.sh 33ebc71e-7d40-456c-8f98-bb3578d2bb2b ./completion-notes.md
|
||||
|
||||
# Then mark as done
|
||||
./scripts/gantt-task-crud.sh update 33ebc71e-7d40-456c-8f98-bb3578d2bb2b status done
|
||||
|
||||
# Verify
|
||||
./scripts/gantt-task-crud.sh get 33ebc71e-7d40-456c-8f98-bb3578d2bb2b | jq '{status, attachments: .attachments | length}'
|
||||
```
|
||||
|
||||
### Batch Operations
|
||||
|
||||
```bash
|
||||
# List all open tasks and get their IDs
|
||||
./scripts/gantt-task-crud.sh list open | jq -r '.[].id'
|
||||
|
||||
# Find tasks by title
|
||||
./scripts/gantt-task-crud.sh list | jq '.[] | select(.title | contains("iOS")) | {id, title, status}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Requirements
|
||||
|
||||
- `curl` - HTTP requests (built into macOS)
|
||||
- `jq` - JSON parsing: `brew install jq`
|
||||
- `uuidgen` - UUID generation (built into macOS)
|
||||
- `base64` - File encoding (built into macOS)
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
These scripts use the **Supabase REST API** directly with a service role key. This means:
|
||||
|
||||
- ✅ No browser needed
|
||||
- ✅ No authentication flow
|
||||
- ✅ Full access to all tasks
|
||||
- ✅ Works from anywhere (cron, scripts, CLI)
|
||||
|
||||
The service role key is embedded in the scripts (read-only risk for local dev).
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "jq: command not found"
|
||||
```bash
|
||||
brew install jq
|
||||
```
|
||||
|
||||
### "Error: File not found"
|
||||
Make sure you're providing the correct relative or absolute path to the file.
|
||||
|
||||
### Task ID format
|
||||
Task IDs are UUIDs like `33ebc71e-7d40-456c-8f98-bb3578d2bb2b`. You can find them:
|
||||
- In the URL when viewing a task in the UI
|
||||
- From `list` command output
|
||||
- From `create` command output
|
||||
|
||||
### Empty response from list
|
||||
If you get `[]`, either:
|
||||
- There are no tasks
|
||||
- The status filter doesn't match any tasks
|
||||
|
||||
---
|
||||
|
||||
## Tips
|
||||
|
||||
1. **Always verify after attach:** Run `get` and check `attachments | length`
|
||||
2. **Use jq for filtering:** Pipe output to `jq` for precise data extraction
|
||||
3. **Task URLs:** Tasks are viewable at `https://gantt-board.vercel.app/tasks/<task-id>`
|
||||
4. **No edit on view:** `view-attachment.sh` shows content but doesn't save edits
|
||||
Loading…
Reference in New Issue
Block a user