Using Task Directives

Task directives are special annotations that modify how tasks behave in Paral. They provide powerful ways to control task execution, scheduling, conditions, and workflow management.

Overview of Task Directives

Directives are prefixed with @ and placed before the task definition. You can combine multiple directives on a single task to create sophisticated execution patterns.

test_var = false
test_list = [1, 2]

@description "this is the task description"
@envfile ./.test.env
@schedule 5s
@if test_var
@for test_list
@args first_arg
@args second_arg
@defer
@wait
@manual
task test_task {
  -> echo "Task with multiple directives"
}

Core Directives

@description

Provides human-readable documentation for your task.

@description "Builds the frontend application and optimizes assets"
task build_frontend {
  -> npm run build
  -> npm run optimize
}

Usage:

• Documents what the task does
• Helpful for team collaboration and maintenance
• Displayed in task listings and help output

@envfile

Loads environment variables from a specified file before task execution.

@envfile ./config/production.env
task deploy_production {
  -> docker build -t myapp:latest .
  -> kubectl apply -f k8s/
}

@envfile ./config/development.env  
task start_dev {
  -> npm run dev
}

Usage:

• Isolate environment configuration per task
• Support different environments (dev, staging, prod)
• Keep sensitive variables in separate files

Scheduling Directives

@schedule

Runs tasks on a timed schedule. Supports both simple intervals and cron expressions.

Simple Intervals

@schedule 30s
task health_check {
  -> curl -f http://localhost:8080/health
}

@schedule 5m
task log_rotation {
  -> logrotate /etc/logrotate.d/myapp
}

@schedule 1h
task cleanup_temp {
  -> find /tmp -name "*.tmp" -mtime +1 -delete
}

Cron Expressions

@schedule "0 2 * * *"  # Daily at 2 AM
task daily_backup {
  -> pg_dump mydb > backup-$(date +%Y%m%d).sql
}

@schedule "*/15 * * * *"  # Every 15 minutes
task monitor_queue {
  -> redis-cli llen job_queue
}

@schedule "0 0 1 * *"  # First day of each month
task monthly_report {
  -> python3 scripts/generate_monthly_report.py
}

Schedule Formats:

• Simple: 30s, 5m, 2h, 1d
• Cron: Standard cron syntax with second precision support

Conditional Directives

@if

Conditionally executes a task based on variable evaluation.

production_mode = true
debug_enabled = false

@if production_mode
task optimize_build {
  -> webpack --mode=production --optimize-minimize
}

@if debug_enabled
task enable_debugging {
  -> export DEBUG=*
  -> npm run dev:debug
}

Advanced Conditional Examples:

deploy_target = "staging"

@if @is(deploy_target, "production")
task deploy_production {
  -> kubectl apply -f k8s/production/
}

@if @is(deploy_target, "staging")  
task deploy_staging {
  -> kubectl apply -f k8s/staging/
}

Iteration Directives

@for

Iterates over lists, executing the task for each item.

environments = ["dev", "staging", "prod"]
services = ["api", "web", "worker"]

@for environments
task setup_env {
  -> @printf("Setting up environment: %s", @value)
  -> kubectl create namespace @value
}

@for services
task build_service {
  -> @printf("Building service %d: %s", @key, @value)
  -> docker build -t @sprintf("%s:latest %s", @value, "./services/@value") 
}

Iteration Variables:

• @value: The current item in the iteration
• @key: The current index (0-based) in the iteration

Execution Control Directives

@defer

Marks a task to run after all other non-deferred tasks complete.

@defer
task cleanup {
  -> docker system prune -f
  -> rm -rf /tmp/build-*
}

@defer
task send_completion_notification {
  -> slack-cli send "Build pipeline completed successfully" --channel=#deployments
}

task build {
  -> npm run build
}

task test {
  -> npm test
}

# build and test run first, then deferred tasks execute

Deferred Task Use Cases:

• Cleanup operations
• Notification sending
• Resource deallocation
• Logging and monitoring

@wait

Pauses task execution until specified conditions are met.

@wait @isnot(@buf("database_ready"), "")
task migrate_database {
  -> python3 manage.py migrate
}

@wait @is(@buf("service_status"), "healthy") @isnot(@buf("config_loaded"), "")
task start_workers {
  -> python3 worker.py --config=@buf("config_loaded")
}

Wait Condition Functions:

• @is(a, b): Equals comparison
• @isnot(a, b): Not equals comparison
• @is(a,"gt", b): Greater than
• @is(a,"lt", b): Less than

Manual Task Directives

@manual

Marks a task as requiring manual execution with arguments.

@manual
@args environment
@args version
task manual_deploy {
  -> @printf("Deploying version %s to %s", @arg('version'), @arg('environment'))
  -> kubectl set image deployment/app @sprintf("app:=%s", @arg('version'))
}

@args

Defines arguments that can be passed to manual tasks.

@manual
@args database_name
@args backup_file
@description "Restore database from backup file"
task restore_database {
  -> @printf("Restoring %s from %s", @arg('database_name'), @arg('backup_file'))
  -> pg_restore -d @arg('database_name') @arg('backup_file')
}

@manual
@args service_name
@args replicas
@description "Scale Kubernetes service to specified replicas"
task scale_service {
  -> kubectl scale deployment @arg('service_name') @sprintf("--replicas=%s", @arg('replicas'))
  -> @printf("Scaled %s to %s replicas", @arg('service_name'), @arg('replicas'))
}

Advanced Directive Combinations

Scheduled Conditional Tasks

maintenance_mode = false

@schedule "0 3 * * *"  # Daily at 3 AM
@if maintenance_mode
task automated_backup {
  -> @buf["backup_start"] << date +%s
  -> pg_dump mydb > @sprintf("backup-%s.sql", $(date +%Y%m%d))
  -> @buf["backup_complete"] << date +%s
}

Deferred Cleanup with Conditions

@defer
@if @is(@buf("build_status"), "success")
task cleanup_successful_build {
  -> rm -rf /tmp/build-cache
  -> @printf("Cleaned up successful build at %s", $(date))
}

@defer
@if @is(@buf("build_status"), "failed")
task cleanup_failed_build {
  -> tar -czf @sprintf("failed-build-%s.tar.gz", $(date +%s)) /tmp/build-cache
  -> @printf("Preserved failed build artifacts")
}

Iterative Manual Operations

microservices = ["auth", "api", "notification", "analytics"]

@manual
@args action
@for microservices
@description "Perform action on all microservices"
task manage_services {
  -> @printf("Performing %s on service: %s", @arg('action'), @value)
  -> kubectl @arg('action') deployment @value
}

Directive Execution Order

When multiple directives are applied to a task, they follow this execution order:

1. @envfile - Environment loaded first
2. @if - Condition evaluated
3. @for - Iteration begins (if applicable)
4. @wait - Wait conditions checked
5. Task execution - Commands run
6. @defer - Deferred tasks queued for later
7. @schedule - Next execution scheduled (if applicable)