Background Tasks CLI

CLI commands for managing background tasks

Background Tasks CLI

Manage background tasks from the command line. Submit recipes, check status, cancel tasks, and clear completed tasks.

Commands Overview

Command	Description
praisonai background list	List all background tasks
praisonai background status <id>	Get task status
praisonai background cancel <id>	Cancel a running task
praisonai background clear	Clear completed tasks
praisonai background submit	Submit a recipe as background task

Submit a Recipe

Submit a recipe to run in the background:

# Basic submission
praisonai background submit --recipe my-recipe

# With input data
praisonai background submit --recipe my-recipe --input '{"query": "test"}'

# With config overrides
praisonai background submit --recipe my-recipe --config '{"max_tokens": 1000}'

# With session ID
praisonai background submit --recipe my-recipe --session-id session_123

# With timeout
praisonai background submit --recipe my-recipe --timeout 600

# JSON output for scripting
praisonai background submit --recipe my-recipe --json

Submit Options

Option	Short	Description
--recipe		Recipe name to execute (required)
--input	-i	Input data as JSON string
--config	-c	Config overrides as JSON string
--session-id	-s	Session ID for conversation continuity
--timeout		Timeout in seconds (default: 300)
--json		Output JSON for scripting

Alternative: Recipe Run with Background Flag

You can also use the recipe run command with the --background flag:

# Run recipe in background
praisonai recipe run my-recipe --background

# With input
praisonai recipe run my-recipe --background --input '{"query": "test"}'

# With session ID
praisonai recipe run my-recipe --background --session-id session_123

List Tasks

List all background tasks:

# List all tasks
praisonai background list

# Filter by status
praisonai background list --status running
praisonai background list --status completed
praisonai background list --status failed

# Pagination
praisonai background list --page 1 --page-size 20

# JSON output
praisonai background list --json

List Options

Option	Description
--status	Filter by status: pending, running, completed, failed, cancelled
--page	Page number (default: 1)
--page-size	Tasks per page (default: 20)
--json	Output JSON for scripting

Check Status

Get detailed status of a specific task:

# Get status
praisonai background status task_abc123

# JSON output
praisonai background status task_abc123 --json

Status Output

Task: task_abc123
Status: running
Progress: 45%
Duration: 12.5s
Recipe: my-recipe
Session: session_123

Cancel Task

Cancel a running task:

# Cancel task
praisonai background cancel task_abc123

# JSON output
praisonai background cancel task_abc123 --json

Clear Completed Tasks

Remove completed tasks from the list:

# Clear completed tasks
praisonai background clear

# Clear all tasks (including running)
praisonai background clear --all

# Clear tasks older than N seconds
praisonai background clear --older-than 3600

# JSON output
praisonai background clear --json

Clear Options

Option	Description
--all	Clear all tasks including running
--older-than	Clear tasks older than N seconds
--json	Output JSON for scripting

Examples

Complete Workflow

# 1. Submit a recipe
praisonai background submit --recipe news-monitor --input '{"topic": "AI"}' --json
# Output: {"ok": true, "task_id": "task_abc123", "recipe": "news-monitor", "session_id": "session_xyz"}

# 2. Check status
praisonai background status task_abc123

# 3. Wait and check again
sleep 30
praisonai background status task_abc123

# 4. List all tasks
praisonai background list

# 5. Clear completed
praisonai background clear

Scripting with JSON Output

#!/bin/bash

# Submit and capture task ID
RESULT=$(praisonai background submit --recipe my-recipe --json)
TASK_ID=$(echo $RESULT | jq -r '.task_id')

echo "Submitted task: $TASK_ID"

# Poll for completion
while true; do
    STATUS=$(praisonai background status $TASK_ID --json | jq -r '.status')
    echo "Status: $STATUS"
    
    if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
        break
    fi
    
    sleep 5
done

echo "Task finished with status: $STATUS"

Troubleshooting

Task Not Starting

If tasks remain in pending status:

• Check if max concurrent tasks limit is reached
• Verify the recipe exists and is valid
• Check system resources

Task Timeout

If tasks are timing out:

• Increase timeout with --timeout flag
• Check if the recipe is making slow API calls
• Consider breaking into smaller tasks

Cannot Find Task

If task ID is not found:

• Tasks may have been cleared
• Check if using correct task ID format
• List all tasks to verify

See Also

• Background Tasks SDK - Python API for background tasks
• Async Jobs CLI - Server-based job execution
• Scheduler CLI - Periodic task scheduling