Tasky - A Modern Task Management System

Tasky is a comprehensive task management system that provides both a command-line interface (CLI) and a RESTful API for managing your tasks. Built with Python, it offers seamless synchronization between local storage and a server, ensuring your tasks are always backed up and accessible across devices.

🚀 Features

• Dual Interface: Use either the intuitive CLI or the RESTful API
• Real-time Synchronization: Sync tasks between local storage and server
• Rich CLI Experience: Beautiful table formatting with rich terminal output
• Persistent Storage: Local JSON storage with server backup
• Task Management: Add, list, mark complete, and sync tasks
• Cross-platform: Works on Windows, macOS, and Linux

📋 Project Overview

Tasky is designed as a lightweight yet powerful task management solution that can work both offline and online. The CLI provides a fast, terminal-based interface for daily task management, while the API server enables synchronization and multi-device access.

Architecture

• CLI Component: Built with Typer for command-line interface and Rich for beautiful terminal output
• API Server: FastAPI-based RESTful service for task synchronization
• Storage: JSON-based storage for both local (CLI) and server-side persistence
• Sync Protocol: Simple push/pull/fetch operations for data synchronization

🚀 Deployment Options

Tasky offers two main deployment approaches to suit different use cases and preferences:

1. Host the Server Remotely

Deploy the API server on a remote server or cloud service for multi-device access and centralized management.

2. Run Locally and Access via CLI

Start the server locally and use the CLI for personal task management without external dependencies.

Choose the approach that best fits your workflow and infrastructure needs.

🛠️ Installation

Prerequisites

• Python 3.8 or higher
• pip (Python package manager)

Step 1: Clone the Repository

git clone <repository-url>
cd tasky

Step 2: Install Dependencies

pip install -r requirements.txt

Step 3: Verify Installation

# Test CLI
python -m app.cli.tasky --help

# Test API server (in a separate terminal)
python -m app.api.main

🎯 Usage Guide

CLI Usage

The CLI provides an intuitive interface for managing tasks locally. All commands are accessible through the main tasky script.

Basic Commands

Add a new task:

python -m app.cli.tasky add "Buy groceries"
python -m app.cli.tasky add "Finish project report"

List all tasks:

python -m app.cli.tasky list

Mark tasks as complete:

# Mark task #1 as complete
python -m app.cli.tasky done 1

# Mark multiple tasks (run commands sequentially)
python -m app.cli.tasky done 2
python -m app.cli.tasky done 3

Synchronization Commands

Push local tasks to server:

python -m app.cli.tasky push <username>

Pull tasks from server (replaces local tasks):

python -m app.cli.tasky pull <username>

Fetch server tasks to separate file:

python -m app.cli.tasky fetch <username>

API Server Usage

The API server provides RESTful endpoints for task synchronization.

Starting the Server

# Start the development server
python -m app.api.main

# The server will start on http://127.0.0.1:8000
# API documentation available at http://127.0.0.1:8000/docs

API Endpoints

Method	Endpoint	Description	Parameters
POST	/push	Push tasks to server	username (query), JSON payload
GET	/pull	Pull tasks from server	username (query)
GET	/fetch	Fetch tasks from server	username (query)

API Usage Examples

Push tasks to server:

curl -X POST "http://127.0.0.1:8000/push?username=batman" \
  -H "Content-Type: application/json" \
  -d '{
    "tasks": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "title": "Complete README",
        "created_at": "2025-07-30T10:00:00+00:00",
        "updated_at": "2025-07-30T10:00:00+00:00",
        "completed": false
      }
    ]
  }'

Pull tasks from server:

curl "http://127.0.0.1:8000/pull?username=batman"

🚀 Deployment Options

Remote Hosting

Deploy the API server on a remote server or cloud service for multi-device access and centralized task management.

Setup Steps

1. Prepare Your Server

   # Install Python and dependencies
   sudo apt update
   sudo apt install python3-pip python3-venv
   
   # Create a dedicated user (recommended)
   sudo adduser tasky
   sudo su - tasky

2. Clone and Install

   git clone <repository-url>
   cd tasky
   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt

3. Configure Environment Variables

   # Create a .env file
   echo "HOST=0.0.0.0" > .env
   echo "PORT=8000" >> .env
   echo "RELOAD=false" >> .env

4. Set Up Reverse Proxy (Optional but Recommended)

   # Using Nginx as example
   sudo apt install nginx
   sudo nano /etc/nginx/sites-available/tasky

   Nginx configuration:

   server {
       listen 80;
       server_name your-domain.com;
   
       location / {
           proxy_pass http://127.0.0.1:8000;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
       }
   }

5. Start the Server

   # Using uvicorn directly
   python3 -m uvicorn app.api.main:app --host 0.0.0.0 --port 8000
   
   # Or using systemd for production
   sudo systemctl start tasky
   sudo systemctl enable tasky

Environment Variables for Remote Deployment

Variable	Default	Description
HOST	127.0.0.1	Bind address (use 0.0.0.0 for external access)
PORT	8000	Port to run the server on
RELOAD	true	Enable auto-reload during development

Network Considerations

• Firewall Configuration: Ensure ports 80/443 (HTTP/HTTPS) and 8000 (direct API) are open
• Security: Use HTTPS in production with valid SSL certificates
• Accessibility: Configure your domain DNS to point to the server IP
• Authentication: Consider adding authentication middleware for production use

Local Development Setup

Run both the server and CLI locally for personal use and development.

Running the Server Locally

# Start the development server
python -m app.api.main

# The server will start on http://127.0.0.1:8000
# API documentation available at http://127.0.0.1:8000/docs

Running the CLI Locally

# All CLI commands work with local server
python -m app.cli.tasky add "Buy groceries"
python -m app.cli.tasky list
python -m app.cli.tasky push <username>
python -m app.cli.tasky pull <username>

Configuration for Remote vs Local

CLI Configuration

The CLI uses two JSON files for storage:

• app/cli/store.json: Local task storage
• app/cli/server.json: Server-fetched task storage (for comparison)

Configure CLI for Remote Server:

# In app/cli/tasky.py, modify the API variable
API = "https://your-domain.com"  # Remote server
# OR
API = "http://your-server-ip:8000"  # Direct IP access

Configure CLI for Local Server:

# Default local configuration
API = "http://127.0.0.1:8000"  # Local development

API Server Configuration

The API server stores user data in:

• app/api/data/: Directory containing user-specific JSON files
• Files are named <username>.json for each user

Environment Variables

You can configure the API endpoint by modifying the API variable in app/cli/tasky.py:

# Local development
API = "http://127.0.0.1:8000"

# Remote server
API = "https://your-domain.com"
# OR
API = "http://your-server-ip:8000"

Deployment Examples

Example 1: Local Development Setup

# Terminal 1: Start local server
python -m app.api.main

# Terminal 2: Use CLI with local server
python -m app.cli.tasky add "Local task example"
python -m app.cli.tasky push myusername
python -m app.cli.tasky pull myusername

Example 2: Remote Server Deployment

# On your remote server
git clone <repository-url>
cd tasky
pip install -r requirements.txt
python -m uvicorn app.api.main:app --host 0.0.0.0 --port 8000

# On your local machine
# Configure CLI to point to remote server
python -m app.cli.tasky --help
python -m app.cli.tasky add "Remote task example"
python -m app.cli.tasky push myusername
python -m app.cli.tasky pull myusername

Example 3: Cloud Service (Heroku) Deployment

# Create requirements.txt with gunicorn
echo "gunicorn" >> requirements.txt

# Create Procfile
echo "web: gunicorn app.api.main:app" > Procfile

# Deploy to Heroku
heroku create your-app-name
git push heroku main
heroku open

📁 Project Structure

tasky/
├── app/
│   ├── __init__.py
│   ├── models.py              # Pydantic models and utilities
│   ├── example.py             # Usage examples
│   ├── api/
│   │   ├── __init__.py
│   │   ├── main.py           # FastAPI server implementation
│   │   └── data/             # User data storage
│   │       └── batman.json   # Example user data
│   └── cli/
│       ├── __init__.py
│       ├── tasky.py          # CLI implementation
│       ├── store.json        # Local task storage
│       └── server.json       # Server-fetched tasks
├── requirements.txt          # Python dependencies
├── projectDesign.md          # Original design document
└── README.md                # This file

🔧 Development

Running Tests

# Run CLI tests
python -m app.cli.tasky list

# Test API endpoints
python -m app.api.main
# Then visit http://127.0.0.1:8000/docs for interactive testing

Adding New Features

1. CLI Features: Modify app/cli/tasky.py
2. API Features: Modify app/api/main.py

Data Format

Tasks are stored in JSON format with the following structure:

[
  {
    "id": "uuid-string",
    "title": "Task description",
    "created_at": "2025-07-30T10:00:00+00:00",
    "updated_at": "2025-07-30T10:00:00+00:00",
    "completed": false
  }
]

🤝 Contributing

We welcome contributions! Here's how you can help:

Getting Started

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Contribution Guidelines

Code Style

• Follow PEP 8 Python style guidelines
• Use meaningful variable and function names
• Add docstrings for new functions and classes
• Keep functions focused and single-purpose

Testing

• Test CLI commands manually
• Verify API endpoints work correctly
• Test synchronization between CLI and API
• Ensure backward compatibility

Documentation

• Update README.md for new features
• Add inline comments for complex logic
• Update docstrings for API changes

Reporting Issues

When reporting issues, please include:

• Operating system and Python version
• Steps to reproduce the issue
• Expected vs actual behavior
• Error messages (if any)

🐛 Troubleshooting

Common Issues

CLI not found:

# Ensure you're in the project root
cd /path/to/tasky
python -m app.cli.tasky --help

API server won't start:

# Check if port 8000 is available
lsof -i :8000

# Try a different port
python -m uvicorn app.api.main:app --port 8080

Sync failures:

• Ensure the API server is running
• Check network connectivity
• Verify username parameter is provided

Permission errors:

# Ensure write permissions for data directories
chmod -R 755 app/cli/
chmod -R 755 app/api/data/

📄 License

This project is open source and available under the MIT License.

🙋‍♂️ Support

For questions or support:

• Open an issue on GitHub
• Check existing documentation
• Review the project design document: projectDesign.md

---

Happy tasking with Tasky! 🎉