Getting Started with tasker-ctl

tasker-ctl is the command-line tool for managing Tasker workflows, generating project scaffolding, and working with configuration. This guide covers the developer-facing features for bootstrapping new projects.

Initialize Your Project

Run tasker-ctl init to create a .tasker-ctl.toml configuration file in your project directory:

tasker-ctl init

This creates a .tasker-ctl.toml pre-configured with the tasker-contrib remote, which provides community templates for all supported languages and default configuration files.

To skip the tasker-contrib remote (e.g., if you only use private templates):

tasker-ctl init --no-contrib

Fetch Remote Templates

After initialization, fetch the remote templates:

tasker-ctl remote update

This clones the configured remotes to a local cache (~/.cache/tasker-ctl/remotes/). Subsequent fetches only pull changes. The cache is checked for freshness automatically and warnings are shown when it becomes stale (default: 24 hours).

Browse Templates

List all available templates:

tasker-ctl template list

Filter by language:

tasker-ctl template list --language ruby
tasker-ctl template list --language python

Get detailed information about a template:

tasker-ctl template info step_handler --language ruby

Generate Code

Generate a step handler from a template:

tasker-ctl template generate step_handler \
  --language ruby \
  --param name=ProcessPayment \
  --output ./app/handlers/

This creates handler files using the naming conventions and patterns for your chosen language. Template parameters (like name) are transformed automatically — ProcessPayment becomes process_payment for file names and ProcessPaymentHandler for class names.

Generate Configuration

Generate a deployable configuration file from the base + environment configs:

# From local config directory
tasker-ctl config generate \
  --context orchestration \
  --environment production \
  --output config/orchestration.toml

# From a remote (tasker-contrib provides default configs)
tasker-ctl config generate \
  --remote tasker-contrib \
  --context orchestration \
  --environment development \
  --output config/orchestration.toml

The config generate command merges base configuration with environment-specific overrides and strips documentation metadata, producing a clean deployment-ready TOML file.

Manage Remotes

tasker-ctl remote list                    # Show configured remotes and cache status
tasker-ctl remote add my-templates URL    # Add a new remote
tasker-ctl remote update                  # Fetch latest for all remotes
tasker-ctl remote update tasker-contrib   # Fetch a specific remote
tasker-ctl remote remove my-templates     # Remove a remote and its cache

Typical Workflow

A new project typically follows this sequence:

# 1. Initialize CLI configuration
tasker-ctl init

# 2. Fetch community templates
tasker-ctl remote update

# 3. Generate a step handler
tasker-ctl template generate step_handler --language python --param name=ValidateOrder

# 4. Generate a task template
tasker-ctl template generate task_template --language python \
  --param name=OrderProcessing \
  --param namespace=default \
  --param handler_callable=handlers.validate_order_handler.ValidateOrderHandler

# 5. Generate infrastructure (uses --plugin for ops templates)
tasker-ctl template generate docker_compose --plugin tasker-contrib-ops --param name=myproject

# 6. Generate environment-specific config (merges base + environment overrides)
tasker-ctl config generate --remote tasker-contrib \
  --context worker --environment development --output config/worker.toml

Note: Language templates use --language to select the plugin (e.g., --language ruby selects tasker-contrib-rails). Ops templates use --plugin tasker-contrib-ops directly since they are language-independent.

Next Steps

• Your First Handler — Write a step handler from scratch
• Your First Workflow — Define a task template and run it
• Configuration Management — Understanding the TOML config structure
• tasker-ctl Architecture — How the CLI is built