> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Cancel task
praisonai background cancel task_abc123

# JSON output
praisonai background cancel task_abc123 --json
```

## Clear Completed Tasks

Remove completed tasks from the list:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
#!/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](/docs/sdk/praisonai/background-tasks) - Python API for background tasks
* [Async Jobs CLI](/docs/sdk/praisonai/cli/async-jobs-cli) - Server-based job execution
* [Scheduler CLI](/docs/sdk/praisonai/cli/scheduler-cli) - Periodic task scheduling