tasks Commands

Commands for managing background tasks and long-running operations. When you start a long operation (like creating an environment) and press Ctrl+C, the operation continues in the background and can be tracked with these commands.

Overview

Long-running operations in Teabar can be:

• Foreground: Shows progress in your terminal (default)
• Background: Runs server-side, trackable via teactl tasks

Press Ctrl+C during any long operation to background it. You’ll receive a task ID to track progress.

$ teactl env create --blueprint cicd-workshop --name march-training
Creating environment 'march-training'...
  ◐ Provisioning cluster...
^C
Task backgrounded: task_abc123
Run 'teactl tasks watch task_abc123' to monitor progress.

teactl tasks list

List recent and running background tasks.

teactl tasks list [flags]

Flags

Examples

# List recent tasks
teactl tasks list

# Show only running tasks
teactl tasks list --running

# Show all tasks from last 24 hours
teactl tasks list --all --since 24h

# Output as JSON
teactl tasks list -o json

Sample output:

TASK ID        TYPE          STATUS     STARTED          DURATION   RESOURCE
task_abc123    env.create    running    10 minutes ago   10m        march-training
task_def456    env.delete    completed  25 minutes ago   2m         old-workshop
task_ghi789    checkpoint    failed     1 hour ago       5m         staging-env

teactl tasks watch

Attach to a running task to monitor its progress.

teactl tasks watch <task-id> [flags]

Flags

Examples

# Watch a specific task
teactl tasks watch task_abc123

# Watch with minimal output
teactl tasks watch task_abc123 --quiet

Sample output:

Task: task_abc123 (env.create)
Environment: march-training
Blueprint: cicd-workshop

Progress:
  ✓ Validated blueprint
  ✓ Reserved resources
  ◐ Provisioning cluster...
    Creating control plane (2/3 nodes ready)
  ○ Installing GitLab
  ○ Configuring runners
  ○ Setting up DNS

Elapsed: 8m 32s
Estimated remaining: ~4m

teactl tasks get

Get detailed information about a specific task.

teactl tasks get <task-id> [flags]

Flags

Examples

# Get task details
teactl tasks get task_abc123

# Get as JSON (useful for scripting)
teactl tasks get task_abc123 -o json

Sample output:

Task ID:      task_abc123
Type:         env.create
Status:       running
Resource:     march-training
Started:      2024-01-15 09:30:00 UTC
Duration:     10m 32s
Progress:     65%

Steps:
  1. ✓ Validate blueprint         (2s)
  2. ✓ Reserve resources          (5s)
  3. ◐ Provision cluster          (8m, in progress)
  4. ○ Install GitLab             (pending)
  5. ○ Configure runners          (pending)
  6. ○ Setup DNS                  (pending)

Last Log:
  [09:38:22] Creating node worker-2 in hetzner/fsn1...

teactl tasks cancel

Cancel a running task.

teactl tasks cancel <task-id> [flags]

Flags

Examples

# Cancel with confirmation
teactl tasks cancel task_abc123

# Force cancel
teactl tasks cancel task_abc123 --force

# Cancel and clean up partial resources
teactl tasks cancel task_abc123 --cleanup

teactl tasks retry

Retry a failed task.

teactl tasks retry <task-id> [flags]

Flags

Examples

# Retry failed task
teactl tasks retry task_ghi789

# Retry and watch progress
teactl tasks retry task_ghi789 --watch

# Retry from a specific step
teactl tasks retry task_ghi789 --from-step 3

teactl tasks logs

View logs from a task execution.

teactl tasks logs <task-id> [flags]

Flags

Examples

# View task logs
teactl tasks logs task_abc123

# Follow logs for running task
teactl tasks logs task_abc123 -f

# Show last 50 lines with timestamps
teactl tasks logs task_abc123 --tail 50 --timestamps

Task Types

Task Notifications

When a backgrounded task completes, you’ll see a notification in your terminal (if supported):

✓ Task task_abc123 completed: Environment 'march-training' is ready
  URL: https://march-training.env.teabar.dev

Failed tasks show error information:

✗ Task task_ghi789 failed: Cluster provisioning error
  Run 'teactl tasks get task_ghi789' for details
  Run 'teactl tasks retry task_ghi789' to retry

Best Practices

1. Use --watch for critical operations - Stay attached to important tasks
2. Check failed tasks promptly - Review logs and retry or clean up
3. Use --cleanup when cancelling - Avoid orphaned resources
4. Set up notifications - Configure webhooks for task completion in CI/CD

See Also

• Environment Commands - Environment lifecycle operations
• Checkpoint Commands - Checkpoint operations