simple-task-cli

A powerful GitHub-based task manager with hierarchical organization and a beautiful web interface.

Manage your tasks from the command line with an intuitive folder-based syntax. All your tasks automatically sync to GitHub and display in a beautiful web dashboard via GitHub Pages.

✨ Features

• 📋 Hierarchical Organization - Organize tasks in nested folders
• 🎯 Priority Levels - Three priority levels with visual indicators
• 🏷️ Tagging System - Add tags for easy filtering and organization
• 📊 Beautiful Web Dashboard - Auto-generated via GitHub Pages
• 🔄 Automatic Sync - All tasks stored in GitHub (version control!)
• 📱 Cross-Device - Access your tasks anywhere
• 🎨 Multiple Projects - Separate work, personal, and side projects
• ⚡ Fast & Lightweight - No database required, just JSON

🚀 Quick Start

Installation

npm install -g simple-task-cli

Setup (One-Time)

task init

You'll need:

1. A GitHub Personal Access Token with repo permissions
2. A repository name (e.g., username/my-tasks)

The CLI will automatically:

• Create the GitHub repository
• Set up the web dashboard
• Initialize your first project

Enable Web View

1. Go to your repository on GitHub
2. Navigate to Settings → Pages
3. Set Source to Deploy from a branch
4. Select branch: main and folder: / (root)
5. Click Save

Wait 1-2 minutes, then visit: https://username.github.io/repository-name

📖 Usage

Basic Syntax

task <folder> / <folder> / <action>

Creating Tasks

# Create a simple task
task home / + buy groceries

# Create with priority (L, M, H)
task home / + finish report H
task work / tasks / + code review M

# Create with tags
task home / + fix bug @urgent H
task explore / + change search bar @color H

Finding and Managing Tasks

Global find (searches across ALL folders):

task find highlight .           # Close any task with "highlight"
task find bug H                 # Set any task with "bug" to high priority
task find old @archive          # Tag any task with "old"
task find completed -           # Archive any task with "completed"

Folder-specific find:

task home / find task .         # Close task in home folder only
task work / find bug M          # Change priority in work folder only
task home / find groceries @shopping  # Add tag in home folder only

List tasks in a folder:

task home /                     # List all tasks in home
task work / tasks /             # List all tasks in work/tasks

Note: When multiple tasks match your search, you'll be prompted to choose which one(s) to modify, or you can select 'all' to apply the action to all matches.

Global Views

View tasks across ALL folders by priority:

task H               # Show all high priority tasks
task M               # Show all medium priority tasks
task L               # Show all low priority tasks

View tasks across ALL folders by tag:

task @urgent         # Show all @urgent tasks
task @shopping       # Show all @shopping tasks

View completed and archived:

task completed       # Show all completed tasks
task archived        # Show all archived tasks

Folder-Specific Filtering

Filter tasks within a specific folder:

task home / H        # Show only high priority tasks in home
task home / M        # Show only medium priority tasks in home
task work / @urgent  # Show only @urgent tasks in work

List all tasks in folder:

task home /          # Show all tasks in home folder

Note: When listing tasks in a folder, only the last 3 completed tasks are shown. Use task completed to see the full list of all completed tasks across all folders in the current project.

🎨 Projects

Organize your tasks into separate projects (work, personal, side projects, etc.)

# Create a new project
task new-project work
task new-project side-hustle

# Switch between projects
task use work
task use personal

# List all projects
task projects

Each project has its own folder structure and tasks. The web dashboard includes tabs to switch between projects.

📝 Examples

Personal Task Management

# Setup
task use personal

# Add tasks
task home / shopping / + buy milk L
task home / shopping / + buy bread L
task home / errands / + pick up dry cleaning M
task home / projects / + finish photo album H

# Complete tasks
task home / shopping / find milk .
task home / errands / find dry cleaning .

# View all tasks
task home /

Work Project

# Create and switch to work project
task new-project work
task use work

# Sprint planning
task sprint / backlog / + implement login H
task sprint / backlog / + write tests M
task sprint / backlog / + update docs L

# Add tags for organization
task sprint / backlog / find login @backend
task sprint / backlog / find tests @qa

# Move to in-progress (create new folder)
task sprint / in-progress / + implement login H

# Complete and archive
task sprint / in-progress / find login .
task sprint / in-progress / find login -

Side Project

task new-project side-hustle
task use side-hustle

# Ideas and planning
task ideas / + build Chrome extension H
task ideas / + create API wrapper M
task ideas / + write blog post L

# Development
task dev / features / + user authentication H
task dev / features / + dark mode M
task dev / bugs / + fix memory leak @critical H

🎯 Command Reference

Actions

| Action | Syntax | Description | Example | |--------|--------|-------------|---------| | Create | + name | Create a new task | task home / + new task | | Create with priority | + name H | Create with priority level | task home / + urgent task H | | Create with tag | + name @tag | Create with tag | task home / + bug fix @urgent | | List | / | List all tasks in folder | task home / | | Find | find search | Find tasks matching search | task home / find bug | | Close | find search . | Close a task | task home / find bug . | | Change priority | find search M | Update priority | task home / find bug H | | Add tag | find search @tag | Add tag to task | task home / find bug @critical | | Archive | find search - | Archive a task | task home / find bug - |

Priority Levels

| Symbol | Level | Color (Web) | Use Case | |--------|-------|-------------|----------| | H | High | 🔴 Red | Urgent, critical tasks | | M | Medium | 🟡 Yellow | Important, should do soon | | L | Low | 🟢 Green | Nice to have, low priority |

Project Commands

task projects              # List all projects
task new-project <name>    # Create a new project
task use <name>           # Switch to a project

🌐 Web Dashboard

Your tasks are automatically displayed in a beautiful, modern web interface:

Features

• Project Tabs - Switch between projects with one click
• Statistics Dashboard - See open, completed, high priority, and archived task counts
• Priority Grouping - Tasks organized by priority level
• Tag Display - Visual tags for easy identification
• Folder Hierarchy - Clear folder structure visualization
• Auto-Refresh - Updates every 30 seconds
• Responsive Design - Works on desktop, tablet, and mobile
• Dark Theme - Easy on the eyes for long sessions

Accessing the Web View

After setup, your dashboard is available at:

https://username.github.io/repository-name

🔧 Configuration

Configuration is stored in ~/.task-manager/config.json:

{
  "githubToken": "your-token",
  "owner": "your-username",
  "repo": "repository-name",
  "branch": "main"
}

📁 Data Structure

Tasks are stored in GitHub as JSON:

{
  "currentProject": "personal",
  "projects": {
    "personal": {
      "folders": {
        "home": [
          {
          "id": "task_123",
          "name": "buy groceries",
          "priority": "M",
          "status": "open",
          "tags": ["@shopping"],
            "created": "2024-01-01T00:00:00.000Z",
            "modified": "2024-01-01T00:00:00.000Z"
          }
        ]
      }
    }
  },
  "archive": []
}

🔒 Security

• Your GitHub token is stored locally in ~/.task-manager/config.json
• Never commit this file to version control
• The token needs repo scope to read/write to your repository
• You can revoke the token anytime from GitHub settings

🐛 Troubleshooting

"Command not found: task"

npm link

Run this again from the simple-task-cli directory.

"401 Unauthorized"

Your GitHub token may have expired or lacks permissions.

1. Generate a new token at https://github.com/settings/tokens/new
2. Ensure it has repo scope
3. Run task init again

Web view not updating

• Wait 1-2 minutes for GitHub Pages to deploy
• Check that GitHub Pages is enabled in repo settings
• Clear your browser cache
• Verify the repository is public or you have access

Changes not saving

• Check your internet connection
• Verify your GitHub token is still valid
• Check the repository hasn't been deleted

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

MIT © [Your Name]

🙏 Acknowledgments

• Built with @octokit/rest
• Inspired by command-line productivity tools
• Web interface uses modern CSS and vanilla JavaScript

📮 Support

• 🐛 Report a bug
• 💡 Request a feature
• 📖 View documentation

Made with ❤️ by developers, for developers.