Skip to main content

​
Background Tasks CLI

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

​
Commands Overview

CommandDescription
praisonai background listList all background tasks
praisonai background status <id>Get task status
praisonai background cancel <id>Cancel a running task
praisonai background clearClear completed tasks
praisonai background submitSubmit 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

OptionShortDescription
--recipeRecipe name to execute (required)
--input-iInput data as JSON string
--config-cConfig overrides as JSON string
--session-id-sSession ID for conversation continuity
--timeoutTimeout in seconds (default: 300)
--jsonOutput 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

OptionDescription
--statusFilter by status: pending, running, completed, failed, cancelled
--pagePage number (default: 1)
--page-sizeTasks per page (default: 20)
--jsonOutput 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

OptionDescription
--allClear all tasks including running
--older-thanClear tasks older than N seconds
--jsonOutput 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