@stephendolan/omnifocus-cli 2.1.0 → 2.3.0

package/README.md

@@ -1,494 +1,151 @@
 # OmniFocus CLI
 
 [![npm version](https://img.shields.io/npm/v/@stephendolan/omnifocus-cli.svg)](https://www.npmjs.com/package/@stephendolan/omnifocus-cli)
-[![npm downloads](https://img.shields.io/npm/dm/@stephendolan/omnifocus-cli.svg)](https://www.npmjs.com/package/@stephendolan/omnifocus-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Bun](https://img.shields.io/badge/Bun-%3E%3D1.0-black)](https://bun.sh)
-[![Platform](https://img.shields.io/badge/platform-macOS-lightgrey.svg)](https://www.apple.com/macos/)
 
-A powerful command-line interface for OmniFocus on macOS, inspired by the GitHub CLI (`gh`).
-
-## Features
-
-- 📝 **Task Management** - Create, list, update, and delete tasks
-- 📂 **Project Management** - Manage projects and their organization
-- 📥 **Inbox Management** - View and count inbox items
-- 🏷️ **Tag Analysis** - View tag usage statistics and identify stale tags
-- 🔍 **Search** - Full-text search across tasks
-- 📊 **JSON Output** - Machine-readable output for automation and scripting
-- ⚡ **Fast** - Direct OmniFocus integration using JXA
+A command-line interface for OmniFocus on macOS.
 
 ## Installation
 
-Requires [Bun](https://bun.sh) runtime.
-
 ```bash
-# Install globally with bun (recommended)
 bun install -g @stephendolan/omnifocus-cli
-
-# Or run directly without installing
-bunx @stephendolan/omnifocus-cli task list
-npx @stephendolan/omnifocus-cli task list  # also works
-```
-
-### From Source
-
-```bash
-git clone https://github.com/stephendolan/omnifocus-cli.git
-cd omnifocus-cli
-bun install
-bun run link  # Build and link globally
-```
-
-Now you can use the `of` command anywhere in your terminal.
-
-## Output Format
-
-All commands output JSON by default:
-
-```bash
-# Pretty-printed JSON (default)
-of task list
-
-# Compact JSON (single line)
-of task list --compact
-```
-
-### Working with JSON Output
-
-Use `jq` to filter and transform the JSON output:
-
-```bash
-# Count inbox tasks
-of inbox list | jq 'length'
-
-# Get task names only
-of task list | jq '.[] | .name'
-
-# Get flagged tasks with specific fields
-of task list --flagged | jq '.[] | {name, project, due}'
-
-# Find tasks added more than 2 hours ago
-of inbox list | jq --arg cutoff "$(date -u -v-2H +%Y-%m-%dT%H:%M:%SZ)" \
-  '.[] | select(.added < $cutoff)'
-
-# Count unprocessed inbox items
-of inbox list | jq '[.[] | select(.project == null)] | length'
-```
-
-## Usage
-
-### Task Commands
-
-#### List Tasks
-
-```bash
-# List all active tasks
-of task list
-
-# List flagged tasks only
-of task list --flagged
-
-# Filter by project
-of task list --project "Work"
-
-# Filter by tag
-of task list --tag "urgent"
-
-# Include completed tasks
-of task list --completed
-```
-
-#### Create a Task
-
-```bash
-# Simple task to inbox
-of task create "Review pull requests"
-
-# Task with project
-of task create "Write documentation" --project "Website"
-
-# Task with multiple options
-of task create "Call dentist" \
-  --project "Personal" \
-  --tag "phone" \
-  --due "2024-01-15" \
-  --flagged \
-  --estimate 15
-```
-
-#### Update a Task
-
-```bash
-# Mark as completed
-of task update "Review pull requests" --complete
-
-# Flag a task
-of task update "Call dentist" --flag
-
-# Move to different project
-of task update "Write docs" --project "Documentation"
-
-# Update multiple properties
-of task update "Email team" \
-  --name "Email team about launch" \
-  --due "2024-01-20" \
-  --flag
-```
-
-#### View Task Details
-
-```bash
-# View by name
-of task view "Review pull requests"
-
-# View by ID
-of task view "kXu3B-LZfFH"
-```
-
-#### Delete a Task
-
-```bash
-of task delete "Old task"
-of task rm "Old task"  # alias
-```
-
-### Project Commands
-
-#### List Projects
-
-```bash
-# List all active projects
-of project list
-
-# Filter by folder
-of project list --folder "Work"
-
-# Filter by status
-of project list --status "on hold"
-
-# Include dropped projects
-of project list --dropped
-```
-
-#### Create a Project
-
-```bash
-# Simple project
-of project create "Website Redesign"
-
-# Project with folder and tags
-of project create "Q1 Planning" \
-  --folder "Work" \
-  --tag "quarterly" \
-  --sequential
-```
-
-#### View Project Details
-
-```bash
-of project view "Website Redesign"
-```
-
-#### Delete a Project
-
-```bash
-of project delete "Old Project"
-of project rm "Old Project"  # alias
 ```
 
-### Inbox Commands
-
-```bash
-# List inbox items
-of inbox list
-
-# Get inbox count
-of inbox count
-```
+Requires [Bun](https://bun.sh) and macOS with OmniFocus installed.
 
-### Search
+## Quick Start
 
 ```bash
-# Search for tasks
-of search "documentation"
+of inbox count                              # Check inbox
+of task list --flagged                      # Today's tasks
+of task create "Buy groceries"              # Quick capture
+of task update "Buy groceries" --complete   # Mark done
 ```
 
-### Tag Commands
+## Commands
 
-#### List Tags
+### Tasks
 
 ```bash
-# List all tags with usage counts
-of tag list
-
-# Show tags unused for 30+ days
-of tag list --unused-days 30
+of task list                        # List active tasks
+of task list --flagged              # Flagged tasks only
+of task list --project "Work"       # Filter by project
+of task list --tag "urgent"         # Filter by tag
+of task list --completed            # Include completed
 
-# Sort by usage (most used first)
-of tag list --sort usage
+of task create "Name" [options]
+  --project <name>                  # Assign to project
+  --tag <tags...>                   # Add tags
+  --due <YYYY-MM-DD>                # Set due date
+  --defer <YYYY-MM-DD>              # Set defer date
+  --flagged                         # Flag the task
+  --estimate <minutes>              # Time estimate
+  --note <text>                     # Add note
 
-# Sort by activity (most recent first)
-of tag list --sort activity
+of task update <name|id> [options]
+  --complete                        # Mark completed
+  --flag / --unflag                 # Toggle flag
+  --name <new-name>                 # Rename
+  --project/--tag/--due/--defer     # Same as create
 
-# Only count active (incomplete) tasks
-of tag list --active-only
+of task view <name|id>              # View details
+of task delete <name|id>            # Delete task
 ```
 
-#### Tag Statistics
+### Projects
 
 ```bash
-# Show comprehensive tag usage statistics
-of tag stats
-```
-
-Displays total tag counts, average tasks per tag, most/least used tags, and stale tags.
+of project list                     # List active projects
+of project list --folder "Work"     # Filter by folder
+of project list --status "on hold"  # Filter by status
+of project list --dropped           # Include dropped
 
-#### Create Tag
+of project create "Name" [options]
+  --folder <name>                   # Assign to folder
+  --tag <tags...>                   # Add tags
+  --sequential                      # Sequential project
+  --note <text>                     # Add note
 
-```bash
-# Create a new tag
-of tag create "New Tag"
-
-# Create a nested tag (child of existing tag)
-of tag create "Child Tag" --parent "Parent Tag"
+of project view <name|id>           # View details
+of project delete <name|id>         # Delete project
 ```
 
-#### View Tag
-
-```bash
-# View tag details by name
-of tag view "Tag Name"
-
-# View tag by ID (always unique)
-of tag view "kXu3B-LZfFH"
-
-# View nested tag using path syntax
-of tag view "Parent/Child"
-```
-
-If multiple tags share the same name in different hierarchies, use the full hierarchical path or tag ID. The command will show available paths if the name is ambiguous.
-
-#### Update Tag
+### Tags
 
 ```bash
-# Rename a tag
-of tag update "Old Name" --name "New Name"
+of tag list                         # All tags with counts
+of tag list --unused-days 30        # Stale tags
+of tag list --sort usage            # Most used first
+of tag list --sort activity         # Most recent first
+of tag list --active-only           # Only count incomplete tasks
 
-# Deactivate a tag
-of tag update "Tag Name" --inactive
+of tag stats                        # Usage statistics
 
-# Reactivate a tag
-of tag update "Tag Name" --active
+of tag create "Name"                # Create tag
+of tag create "Child" --parent "Parent"  # Nested tag
 
-# Update nested tag using path
-of tag update "Parent/Child" --name "New Name"
+of tag view <name|path|id>          # View details
+of tag update <name> --name "New"   # Rename
+of tag update <name> --inactive     # Deactivate
+of tag delete <name>                # Delete tag
 ```
 
-#### Delete Tag
-
-```bash
-# Delete a tag by name
-of tag delete "Tag Name"
-
-# Delete using alias
-of tag rm "Tag Name"
-
-# Delete nested tag using path
-of tag delete "Parent/Child"
-```
-
-## Command Reference
-
-### Global Options
-
-- `-h, --help` - Show help for any command
-- `-V, --version` - Show version number
-- `--compact` - Compact JSON output (single line)
-
-### Task Filters
-
-- `-f, --flagged` - Show only flagged tasks
-- `-p, --project <name>` - Filter by project name
-- `-t, --tag <name>` - Filter by tag name
-- `-c, --completed` - Include completed tasks
-
-### Task Options
-
-- `--project <name>` - Assign to project
-- `--note <text>` - Add note
-- `--tag <tags...>` - Add tags (space-separated)
-- `--due <date>` - Set due date (ISO format: YYYY-MM-DD)
-- `--defer <date>` - Set defer date (ISO format)
-- `--flagged` - Flag the task
-- `--estimate <minutes>` - Set time estimate in minutes
-
-### Project Options
-
-- `--folder <name>` - Assign to folder
-- `--note <text>` - Add note
-- `--tag <tags...>` - Add tags (space-separated)
-- `--sequential` - Make it a sequential project
-- `--status <status>` - Set status (active, on hold, dropped)
-
-### Tag Options
-
-**List options:**
-- `-u, --unused-days <days>` - Show tags unused for N days
-- `-s, --sort <field>` - Sort by: name, usage, activity (default: name)
-- `-a, --active-only` - Only count active (incomplete) tasks
-
-**Create/Update options:**
-- `-p, --parent <name>` - Create as child of parent tag (create only)
-- `-n, --name <name>` - Rename tag (update only)
-- `-a, --active` - Set tag as active (update only)
-- `-i, --inactive` - Set tag as inactive (update only)
-
-## Task Object Schema
-
-Task objects include these fields:
-
-- `id` - Unique identifier
-- `name` - Task name
-- `note` - Notes (or null)
-- `completed` - Boolean completion status
-- `flagged` - Boolean flagged status
-- `project` - Project name (null for inbox items)
-- `tags` - Array of tag names
-- `defer` - Defer date in ISO format (or null)
-- `due` - Due date in ISO format (or null)
-- `estimatedMinutes` - Time estimate in minutes (or null)
-- `completionDate` - Completion timestamp (or null)
-- `added` - Creation timestamp (or null)
-- `modified` - Last modification timestamp (or null)
-
-## Examples
-
-### Daily Workflow
+### Other
 
 ```bash
-# Check inbox
-of inbox count
-
-# List today's tasks
-of task list --flagged
-
-# Add a quick task
-of task create "Buy groceries" --tag "errands"
-
-# Review project status
-of project list
+of inbox list                       # List inbox items
+of inbox count                      # Inbox count
+of search "query"                   # Search tasks
 ```
 
-### Weekly Review
+## JSON Output
 
-```bash
-# Check all projects
-of project list
-
-# Review flagged items
-of task list --flagged
-
-# Search for specific topics
-of search "meeting"
-```
-
-### Task Management
+All commands output JSON. Use `--compact` for single-line output.
 
 ```bash
-# Create a task in a project with details
-of task create "Draft quarterly report" \
-  --project "Management" \
-  --tag "writing" \
-  --due "2024-02-01" \
-  --estimate 120 \
-  --note "Include metrics from Q4 dashboard"
-
-# Complete a task
-of task update "Draft quarterly report" --complete
-
-# Reschedule a task
-of task update "Team meeting prep" --due "2024-01-22"
+of task list | jq 'length'                    # Count tasks
+of task list | jq '.[] | .name'               # Task names
+of task list --flagged | jq '.[] | {name, due}'  # Specific fields
 ```
 
-### Tag Management
-
-```bash
-# View all tags with usage stats
-of tag list
-
-# Find stale tags not used in 60+ days
-of tag list --unused-days 60
-
-# See most used tags
-of tag list --sort usage
-
-# View recently active tags
-of tag list --sort activity
-
-# Get comprehensive tag statistics
-of tag stats
-
-# Create a new tag
-of tag create "Urgent"
+## Task Schema
 
-# Create nested tags for organization
-of tag create "Work Meetings" --parent "Work"
-of tag create "Personal Meetings" --parent "Personal"
-
-# View a specific tag (with hierarchical path if needed)
-of tag view "Work/Work Meetings"
-
-# Rename a stale tag
-of tag update "Old Project" --name "Archived Project"
-
-# Deactivate unused tags
-of tag update "Archived Project" --inactive
-
-# Delete completely unused tags
-of tag delete "Obsolete Tag"
+```json
+{
+  "id": "kXu3B-LZfFH",
+  "name": "Task name",
+  "completed": false,
+  "flagged": true,
+  "project": "Project Name",
+  "tags": ["tag1", "tag2"],
+  "due": "2024-01-15T00:00:00.000Z",
+  "defer": null,
+  "estimatedMinutes": 30,
+  "note": "Notes here",
+  "added": "2024-01-01T10:00:00.000Z",
+  "modified": "2024-01-10T15:30:00.000Z",
+  "completionDate": null
+}
 ```
 
-## Requirements
+## Troubleshooting
 
-- macOS (OmniFocus is Mac-only)
-- OmniFocus installed and running
-- [Bun](https://bun.sh) 1.0+
+**Permission denied**: Grant automation permission in System Settings > Privacy & Security > Automation.
 
-## How It Works
+**Task not found**: Use exact name or ID. IDs appear in JSON output.
 
-The CLI uses JavaScript for Automation (JXA) to communicate directly with OmniFocus, providing fast, direct access without external services.
+**Date format**: Use ISO format `YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SS`.
 
 ## Development
 
 ```bash
-# Install dependencies
+git clone https://github.com/stephendolan/omnifocus-cli.git
+cd omnifocus-cli
 bun install
-
-# Build TypeScript
-bun run build
-
-# Watch mode for development
-bun run dev
-
-# Link for local testing
-bun link
+bun run dev     # Watch mode
+bun link        # Link globally as `of`
 ```
 
-## Troubleshooting
-
-### Permission Issues
-
-When you first run a command, macOS will ask for permission to control OmniFocus. Make sure to grant this permission in System Settings > Privacy & Security > Automation.
-
-### Task Not Found
-
-Use the exact task name or ID. Task IDs are included in the JSON output of all list commands.
-
-### Date Format
-
-Use ISO format for dates: `YYYY-MM-DD` or full ISO strings like `2024-01-15T10:00:00`.
-
 ## License
 
 MIT