Async Jobs CLI

CLI commands for managing async jobs

Async Jobs CLI

Manage async jobs from the command line. Submit jobs, check status, get results, stream progress, and cancel jobs.

Commands Overview

Command	Description
praisonai run submit	Submit a new job
praisonai run status <id>	Get job status
praisonai run result <id>	Get job result
praisonai run stream <id>	Stream job progress
praisonai run list	List all jobs
praisonai run cancel <id>	Cancel a job

Starting the Jobs Server

Before using job commands, start the jobs server:

# Start server on default port (8005)
python -m uvicorn praisonai.jobs.server:create_app --port 8005 --factory

# Or with custom host/port
python -m uvicorn praisonai.jobs.server:create_app --host 0.0.0.0 --port 8080 --factory

Submit a Job

Submit a new job for execution:

# Basic submission with prompt
praisonai run submit "Analyze this data"

# Submit with recipe
praisonai run submit "Analyze AI trends" --recipe news-analyzer

# With recipe config
praisonai run submit "Analyze AI trends" --recipe news-analyzer --recipe-config '{"format": "json"}'

# With agent file
praisonai run submit "Analyze this data" --agent-file agents.yaml

# Wait for completion
praisonai run submit "Quick task" --wait

# Stream progress after submission
praisonai run submit "Long task" --stream

# With timeout
praisonai run submit "Complex task" --timeout 7200

# With webhook
praisonai run submit "Task" --webhook-url https://example.com/callback

# With idempotency
praisonai run submit "Task" --idempotency-key order-123 --idempotency-scope session

# With metadata
praisonai run submit "Task" --metadata user=john --metadata priority=high

# JSON output
praisonai run submit "Task" --json

# Custom API URL
praisonai run submit "Task" --api-url http://localhost:8080

Submit Options

Option	Description
--agent-file	Path to agents.yaml
--recipe	Recipe name (mutually exclusive with —agent-file)
--recipe-config	Recipe config as JSON string
--framework	Framework to use (default: praisonai)
--timeout	Timeout in seconds (default: 3600)
--wait	Wait for completion
--stream	Stream progress after submission
--idempotency-key	Key to prevent duplicates
--idempotency-scope	Scope: none, session, global
--webhook-url	Webhook URL for completion
--session-id	Session ID for grouping
--metadata	Custom metadata (KEY=VALUE, repeatable)
--json	Output JSON for scripting
--api-url	Jobs API URL (default: http://127.0.0.1:8005)

Check Job Status

Get the current status of a job:

# Get status
praisonai run status run_abc123

# JSON output
praisonai run status run_abc123 --json

Status Output

Job: run_abc123
Status: running
Progress: 45%
Step: Processing data
Created: 2024-01-15 10:30:00
Duration: 45.2s

Get Job Result

Retrieve the result of a completed job:

# Get result
praisonai run result run_abc123

# JSON output
praisonai run result run_abc123 --json

Stream Job Progress

Stream real-time progress updates via SSE:

# Stream progress
praisonai run stream run_abc123

# Raw JSON events
praisonai run stream run_abc123 --json

Stream Output

[10%] Initializing agent
[20%] Loading recipe
[50%] Processing data
[90%] Finalizing
[100%] Completed

List Jobs

List all jobs with optional filtering:

# List all jobs
praisonai run list

# Filter by status
praisonai run list --status running
praisonai run list --status succeeded
praisonai run list --status failed

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

# JSON output
praisonai run list --json

List Options

Option	Description
--status	Filter by status
--page	Page number (default: 1)
--page-size	Jobs per page (default: 20)
--json	Output JSON for scripting
--api-url	Jobs API URL

Cancel a Job

Cancel a running job:

# Cancel job
praisonai run cancel run_abc123

# JSON output
praisonai run cancel run_abc123 --json

Examples

Complete Workflow

# 1. Start the server (in another terminal)
python -m uvicorn praisonai.jobs.server:create_app --port 8005 --factory

# 2. Submit a job with recipe
praisonai run submit "Analyze AI news" --recipe news-analyzer --json
# Output: {"job_id": "run_abc123", "status": "queued", ...}

# 3. Check status
praisonai run status run_abc123

# 4. Stream progress
praisonai run stream run_abc123

# 5. Get result when done
praisonai run result run_abc123

# 6. List all jobs
praisonai run list

Submit with Wait

# Submit and wait for completion
praisonai run submit "Quick analysis" --recipe quick-analyzer --wait --json

Scripting with JSON

#!/bin/bash

API_URL="http://127.0.0.1:8005"

# Submit job
RESULT=$(praisonai run submit "Analyze data" --recipe analyzer --json --api-url $API_URL)
JOB_ID=$(echo $RESULT | jq -r '.job_id')

echo "Submitted job: $JOB_ID"

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

# Get result
praisonai run result $JOB_ID --json --api-url $API_URL

Using Webhooks

# Submit with webhook
praisonai run submit "Long running task" \
    --recipe long-task \
    --webhook-url https://example.com/webhook \
    --json

Idempotent Submission

# First submission creates job
praisonai run submit "Process order" --idempotency-key order-123 --json

# Second submission returns same job (no duplicate)
praisonai run submit "Process order" --idempotency-key order-123 --json

Troubleshooting

Connection Refused

If you get “Connection refused”:

• Ensure the jobs server is running
• Check the API URL is correct
• Verify the port is not blocked

Job Stuck in Queued

If jobs remain queued:

• Check server logs for errors
• Verify max concurrent limit
• Ensure recipe/agent file exists

Timeout Errors

If jobs are timing out:

• Increase timeout with --timeout
• Check if external APIs are slow
• Consider breaking into smaller jobs

See Also

• Async Jobs SDK - Python API for jobs
• Background Tasks CLI - In-process background tasks
• Scheduler CLI - Periodic job scheduling