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)

✨ 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)

See PHASE_1_IMPLEMENTATION_SUMMARY.md for v0.2.0 implementation details.

🤝 Contributing

We love contributions! Check out our Contributing Guide.

Quick Links

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.}

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
.github/workflows		.github/workflows
examples		examples
scripts		scripts
taskx		taskx
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

License

0xV8/taskx

Folders and files

Latest commit

History

Repository files navigation