taskx - Modern Python Task Runner

npm scripts for Python. Task automation that just works.

---

🎉 What's New in v0.2.0

• Shell Completion - TAB completion for commands and tasks in bash, zsh, fish, and PowerShell
• Task Aliases - Create short names for frequently used tasks (e.g., t for test)
• Interactive Prompts - Ask for user input and confirmations during task execution
• Project Templates - Kickstart projects with 4 production-ready templates (Django, FastAPI, Data Science, Python Library)

See full changelog | Upgrade guide

---

✨ Why taskx?

Stop fighting with Makefiles. taskx brings the simplicity of npm scripts to Python with the power you actually need.

# pyproject.toml
[tool.taskx.tasks]
test = "pytest tests/"
dev = "uvicorn app:app --reload"
lint = "ruff check ."

deploy = {
    depends = ["lint", "test", "build"],
    cmd = "twine upload dist/*"
}

$ taskx list
Available tasks:
  test       Run test suite
  dev        Start development server
  lint       Run linting
  deploy     Deploy to PyPI

$ taskx deploy
→ Running: lint
✓ Completed: lint (1.2s)
→ Running: test
✓ Completed: test (3.4s)
→ Running: build
✓ Completed: build (2.1s)
→ Running: deploy
✓ Completed: deploy (0.8s)

---

🚀 Quick Start

Installation

pip install taskx

Requirements: Python 3.8 or higher

Verify Installation

$ taskx --version
taskx version 0.2.0

Initialize

Create a new project with a template:

# List available templates
$ taskx init --list-templates
Available templates:

  WEB:
    django               Django web application with migrations, testing, and deployment
    fastapi              FastAPI microservice with async support and Docker

  DATA:
    data-science         ML project with Jupyter, MLflow, and pipeline automation

  LIBRARY:
    python-library       Python package with PyPI publishing workflow

# Create project from template
$ taskx init --template django --name myproject
✓ Created django project with taskx configuration

# Or create a basic project
$ taskx init
✓ Created pyproject.toml with example tasks

Define Tasks

Add tasks to your pyproject.toml:

[tool.taskx.tasks]
hello = "echo 'Hello from taskx!'"
test = "pytest"
dev = "python manage.py runserver"

Run Tasks

$ taskx hello
Hello from taskx!

$ taskx test
===== test session starts =====
...

---

🎯 Features

✅ Python-Native

• Uses pyproject.toml (Python standard)
• Integrates with Poetry, Hatch, PDM
• No new config files needed

✅ Cross-Platform

• Perfect Windows support (no Make headaches!)
• Works on macOS, Linux, Windows
• Consistent behavior everywhere

✅ Task Dependencies

[tool.taskx.tasks]
lint = "ruff check ."
test = "pytest"
deploy = { depends = ["lint", "test"], cmd = "python deploy.py" }

✅ Parallel Execution

[tool.taskx.tasks]
check = {
    parallel = ["ruff check", "mypy .", "pytest --quick"],
    description = "Run all checks in parallel"
}

3-4x faster than running sequentially!

✅ Environment Variables

[tool.taskx.env]
APP_NAME = "myapp"
PORT = "8000"

[tool.taskx.tasks]
dev = "uvicorn ${APP_NAME}:app --port ${PORT}"
prod = { cmd = "uvicorn ${APP_NAME}:app", env = { PORT = "80" } }

✅ Hooks & Watch Mode

[tool.taskx.tasks]
test = { cmd = "pytest", pre = "echo 'Starting tests...'", post = "coverage report" }

dev = { cmd = "uvicorn app:app --reload", watch = ["**/*.py"] }

Run watch mode:

$ taskx watch dev
👀 Watching for changes...
▶ Running initial execution...
✓ Initial execution completed

📝 Detected 1 change(s):
   → src/app.py
▶ Re-running task 'dev'...
✓ Execution completed successfully

✅ Beautiful Output

• Color-coded task status
• Progress bars for parallel tasks
• Helpful error messages
• Time tracking

✅ Shell Completion (NEW in v0.2.0)

# Install completion for your shell
$ taskx completion bash --install
✓ Completion installed: ~/.bash_completion.d/taskx

# Now get TAB completion for tasks!
$ taskx <TAB>
list  run  watch  graph  init  completion
$ taskx run <TAB>
test  dev  lint  deploy

Supports: bash, zsh, fish, PowerShell

✅ Task Aliases (NEW in v0.2.0)

[tool.taskx.aliases]
t = "test"
d = "dev"
fmt = "format"

[tool.taskx.tasks]
test = { cmd = "pytest", aliases = ["t"] }  # Per-task alias
format = "black . && isort ."

$ taskx t  # Runs 'test'
→ Alias 't' resolves to task 'test'
===== 51 tests passed =====

✅ Interactive Prompts (NEW in v0.2.0)

[tool.taskx.tasks.deploy]
cmd = "sh deploy.sh ${ENVIRONMENT}"
prompt.ENVIRONMENT = {
    type = "select",
    message = "Deploy to which environment?",
    choices = ["staging", "production"]
}
confirm = "Deploy to ${ENVIRONMENT}?"

$ taskx deploy
? Deploy to which environment? (Use arrow keys)
  › staging
    production
? Deploy to staging? (Y/n) y
→ Running: deploy
✓ Completed: deploy

✅ Project Templates (NEW in v0.2.0)

# Start new Django project
$ taskx init --template django
# Prompts for project name, Celery, Docker options
# Generates complete project with 20+ tasks

# Start new FastAPI project
$ taskx init --template fastapi
# Creates API project with testing, Docker, database setup

# Start ML/Data Science project
$ taskx init --template data-science
# Jupyter, MLflow, complete ML pipeline

# Start Python library
$ taskx init --template python-library
# Package with PyPI publishing, testing, docs

---

📊 Comparison

Feature	taskx	Make	Poetry Scripts	Invoke	Taskipy
Python-native	✅	❌	✅	✅	✅
Easy syntax	✅	❌	✅	⚠️	✅
Cross-platform	✅	⚠️	✅	✅	✅
Task dependencies	✅	✅	❌	✅	❌
Parallel execution	✅	✅	❌	✅	❌
Environment vars	✅	✅	❌	✅	❌
Watch mode	✅	❌	❌	❌	❌
Dependency graphs	✅	❌	❌	❌	❌
Pre/post hooks	✅	⚠️	❌	✅	⚠️
Shell completion ⭐	✅	⚠️	❌	⚠️	❌
Task aliases ⭐	✅	❌	❌	❌	❌
Interactive prompts ⭐	✅	❌	❌	⚠️	❌
Project templates ⭐	✅	❌	❌	❌	❌
Security focused	✅	❌	❌	❌	❌

Legend: ✅ Full support | ⚠️ Partial support | ❌ Not supported | ⭐ New in v0.2.0

---

🎓 Examples

Django Project

[tool.taskx.tasks]
dev = "python manage.py runserver"
migrate = "python manage.py migrate"
shell = "python manage.py shell"
test = "pytest"
lint = { parallel = ["ruff check .", "mypy ."] }

Data Science Project

[tool.taskx.tasks]
notebook = "jupyter lab"
train = "python train_model.py"
evaluate = "python evaluate.py"
deploy = { depends = ["test", "evaluate"], cmd = "python deploy.py" }

FastAPI Application

[tool.taskx.env]
APP_MODULE = "app.main:app"

[tool.taskx.tasks]
dev = "uvicorn ${APP_MODULE} --reload"
prod = { cmd = "uvicorn ${APP_MODULE}", env = { WORKERS = "4" } }
test = "pytest tests/ -v"

More examples in examples/ directory.

---

📚 Documentation

Commands

• taskx list - List all available tasks with descriptions and dependencies
  • taskx list --names-only - Output only task names (for shell completion)
  • taskx list --include-aliases - Include aliases in output
• taskx <task> - Run a specific task (with automatic dependency resolution)
• taskx run <task> - Explicit task execution
  • taskx run <task> --env KEY=VALUE - Override environment variables
• taskx watch <task> - Watch files and auto-restart task on changes
• taskx graph - Visualize task dependencies (supports tree, mermaid, dot formats)
• taskx init - Initialize taskx configuration in your project
  • taskx init --template <name> - Create project from template ⭐ NEW
  • taskx init --list-templates - Show available templates ⭐ NEW
• taskx completion <shell> - Generate shell completion script ⭐ NEW
  • taskx completion bash --install - Install completion for bash
  • Supported: bash, zsh, fish, powershell
• taskx --version - Show version information
• taskx --help - Show help for all commands

Graph Visualization

# Show ASCII tree of all tasks
$ taskx graph

# Show dependencies for specific task
$ taskx graph --task deploy

# Export as Mermaid diagram
$ taskx graph --format mermaid > tasks.mmd

# Export as Graphviz DOT
$ taskx graph --format dot > tasks.dot | dot -Tpng -o tasks.png

Configuration Reference

Basic Task

[tool.taskx.tasks]
hello = "echo 'Hello!'"

Task with Description

[tool.taskx.tasks]
test = { cmd = "pytest", description = "Run test suite" }

Task with Dependencies

[tool.taskx.tasks]
deploy = { depends = ["lint", "test"], cmd = "deploy.sh" }

Parallel Tasks

[tool.taskx.tasks]
check = { parallel = ["ruff", "mypy", "pytest"] }

Task with Environment Variables

[tool.taskx.tasks]
prod = { cmd = "uvicorn app:app", env = { PORT = "80", WORKERS = "4" } }

Task with Hooks

[tool.taskx.tasks]
test = "pytest"
test.pre = "echo 'Starting...'"
test.post = "coverage report"
test.on_error = "notify-send 'Tests failed!'"

Watch Mode

[tool.taskx.tasks]
dev = { cmd = "uvicorn app:app", watch = ["**/*.py"] }

Full documentation: GitHub Repository

---

🛣️ Roadmap

v0.1.0 ✅

• Core task execution with dependencies
• Parallel task execution
• Watch mode with file monitoring
• Environment variable support
• Lifecycle hooks (pre/post/error/success)
• Dependency graph visualization
• Multi-layer security validation
• Beautiful terminal output
• Cross-platform support

v0.2.0 (Current Release) ✅

• Shell completion scripts (bash, zsh, fish, PowerShell) ⭐
• Task aliases (global and per-task) ⭐
• Interactive prompts with confirmations ⭐
• Project templates (Django, FastAPI, Data Science, Python Library) ⭐
• Enhanced CLI with environment variable overrides
• Template system with Jinja2 sandboxing
• CI/CD-safe interactive prompt handling

v0.3.0 (Planned)

• Task caching (skip unchanged tasks)
• Remote task execution
• Plugin system
• Enhanced error recovery
• Task profiling and performance analysis
• Multi-project workspace support

See PHASE_1_IMPLEMENTATION_SUMMARY.md for v0.2.0 implementation details.

---

🤝 Contributing

We love contributions! Check out our Contributing Guide.

Quick Links

• Code of Conduct
• Development Setup
• Architecture
• Testing Guide

Ways to Contribute

• 🐛 Report bugs
• 💡 Suggest features
• 📝 Improve documentation
• 🔧 Submit pull requests
• ⭐ Star the project!

---

🙋 FAQ

Why not just use Make?

• Make syntax is complex and error-prone (tabs!)
• Poor Windows support
• Not Python-native
• taskx is simpler and more powerful

Why not Poetry scripts?

• Poetry scripts are too basic (no dependencies, parallelization)
• taskx is complementary - use Poetry for deps, taskx for tasks

Why not Invoke?

• Invoke requires writing Python code for simple tasks
• taskx uses declarative config (faster, simpler)
• Use Invoke for complex logic, taskx for 90% of tasks

Can I use taskx with Poetry/Hatch/PDM?

• Yes! taskx reads pyproject.toml and works with all tools

Does it work on Windows?

• Yes! Cross-platform support designed from day one
• Works on Windows, macOS, and Linux

How fast is it?

• <100ms startup time
• Parallel execution for independent tasks
• Efficient file watching with Rust-based watchfiles library

Is it secure?

• Yes! Multi-layer security validation
• Prevents command injection attacks
• Blocks dangerous patterns (rm -rf /, fork bombs, etc.)
• Proper environment variable escaping
• Optional strict mode for production

---

📄 License

Proprietary License - taskx is free to use but comes with restrictions.

What You CAN Do:

• ✅ Use taskx freely for personal or commercial projects
• ✅ Install and run taskx without limitations
• ✅ View the source code for reference and learning

What You CANNOT Do:

• ❌ Modify the source code or create derivative works
• ❌ Copy or redistribute the software
• ❌ Remove or alter license notices or attribution
• ❌ Create competing products based on taskx

Requirements:

• ⚠️ Must preserve license notices - Cannot remove copyright or license information
• ⚠️ Must include attribution - If using taskx in production, include: "Powered by taskx"

Full license terms: See LICENSE file for complete legal details.

Why proprietary? This license protects the integrity of taskx while allowing free usage. You get all the benefits without restrictions on how you use it, but the code itself remains protected from unauthorized modification or redistribution.

---

🌟 Star History

---

💬 Community

• GitHub: github.com/0xV8/taskx
• Issues: Report bugs or request features

---

🙏 Acknowledgments

Inspired by:

• npm scripts - Simplicity and developer experience
• Make - Power and reliability
• Invoke - Python-native task execution
• Poetry - Modern Python tooling

Built with:

• Click - CLI framework
• Rich - Beautiful terminal output
• watchfiles - Fast file watching
• questionary - Interactive prompts
• Jinja2 - Template engine

---

Made with ❤️ for Python developers everywhere

_{Stop fighting with Makefiles. Start using taskx.}