Skip to main content
/ Docs
Quickstart API SDKs

CLI: Background Jobs

Monitor and manage background jobs and queues in Trix with the CLI.

Updated

Overview

The jobs command provides tools for viewing and managing background jobs that handle asynchronous operations like embedding generation, memory enrichment, and audio transcription. Use these commands to monitor job status, troubleshoot failures, and retry failed jobs.

Aliases: job, j

Background jobs are automatically created when you perform operations like creating memories, uploading audio files, or running bulk operations.

List Jobs

View all background jobs with optional filtering by queue, status, or other criteria.

# List recent jobs
trix jobs list

# Filter by queue
trix jobs list --queue embedding
trix jobs list --queue transcription
trix jobs list --queue enrichment

# Filter by status
trix jobs list --status waiting
trix jobs list --status active
trix jobs list --status completed
trix jobs list --status failed

# Pagination
trix jobs list --limit 50
trix jobs list --limit 20 --offset 20

# Output as JSON
trix jobs list -o json

# Use jq for filtering
trix jobs list --jq '[.[] | select(.status == "failed")]'
trix jobs list --jq '.[].id'
trix jobs list --jq '[.[] | {id, status, queue}]'

Example output:

ID           QUEUE        STATUS      PROGRESS  CREATED
job_abc123   embedding    completed   100%      5 mins ago
job_def456   embedding    active      45%       2 mins ago
job_ghi789   transcribe   failed      0%        10 mins ago

Job Statuses

StatusDescription
waitingJob is queued and waiting to be processed
activeJob is currently being processed
completedJob finished successfully
failedJob failed and may need to be retried

Get Job Details

Retrieve detailed information about a specific job, including progress, error messages, and job data.

# Get job by queue and ID
trix jobs get embedding job_abc123

# Output as JSON
trix jobs get embedding job_abc123 -o json

Example output:

  ID: job_abc123
  Queue: embedding
  Status: completed
  Progress: 100%
  Created: Jan 15, 2026 10:30:00
  Started: Jan 15, 2026 10:30:05
  Completed: Jan 15, 2026 10:30:15
  Attempts: 1

  Data:
    memory_id: mem_xyz789
    status: completed

When a job fails, the detailed view will show error messages to help diagnose the issue.

Queue Statistics

View statistics for all job queues, showing the number of jobs in each status across all queues.

# Show queue statistics
trix jobs stats

# Output as JSON
trix jobs stats -o json

Example output:

Queue Statistics

QUEUE          WAITING  ACTIVE  COMPLETED  FAILED
embedding      5        2       1,523      12
transcription  0        1       234        3
enrichment     3        0       891        5

  Total Waiting: 8
  Total Active: 3
  Total Completed: 2,648
  Total Failed: 20

Queue statistics help you:

  • Identify bottlenecks in processing
  • Monitor failed jobs that need attention
  • Understand system load and capacity
  • Track job completion rates

Retry Failed Jobs

Retry a failed job to attempt processing again. This is useful when jobs fail due to temporary issues like network errors or service unavailability.

# Retry a specific job
trix jobs retry embedding job_abc123

# The command will prompt for confirmation
# Confirm and the job will be queued for retry

Jobs are automatically retried a limited number of times before being marked as permanently failed. Manual retry allows you to try again after the automatic retry limit has been reached.

Common Job Queues

Embedding Queue

Handles generation of vector embeddings for memory content, enabling semantic search.

  • Created when: Memories are added or updated
  • Typical duration: 1-5 seconds per job
  • Common failures: API rate limits, invalid content

Transcription Queue

Processes audio files to generate text transcriptions.

  • Created when: Audio memories are uploaded
  • Typical duration: 10-60 seconds (depends on audio length)
  • Common failures: Unsupported format, corrupted file

Enrichment Queue

Extracts facts, entities, and relationships from memory content.

  • Created when: Memories are added with enrichment enabled
  • Typical duration: 5-15 seconds per job
  • Common failures: LLM API errors, rate limits

Bulk Operations Queue

Processes bulk memory operations like batch imports or bulk tag updates.

  • Created when: Bulk operations are requested
  • Typical duration: Varies by operation size
  • Common failures: Invalid data, validation errors

Command Reference

jobs Commands

CommandDescription
listList jobs with optional filtering
get <queue> <id>Get detailed information about a job
statsShow queue statistics
retry <queue> <id>Retry a failed job

List Options

OptionDescription
--queueFilter by queue name
--statusFilter by status (waiting, active, completed, failed)
--limitMaximum number of results (default: 20)
--offsetOffset for pagination
--jqFilter output using jq expression

Common Examples

Monitor Job Processing

# Check overall queue health
trix jobs stats

# View recent jobs
trix jobs list --limit 10

# Watch for failures
trix jobs list --status failed

# Check embedding queue
trix jobs list --queue embedding --limit 20

Troubleshoot Failed Jobs

# Find all failed jobs
trix jobs list --status failed

# Get details of a failed job
trix jobs get embedding job_abc123

# Retry the failed job
trix jobs retry embedding job_abc123

# Check if retry succeeded
trix jobs get embedding job_abc123

Monitor Bulk Operations

# After starting a bulk operation, monitor progress
trix jobs list --queue bulk --status active

# Check completion
trix jobs list --queue bulk --status completed --limit 5

# If any failed, review details
trix jobs list --queue bulk --status failed

Job Audit & Analysis

# Export job data for analysis
trix jobs list --limit 1000 -o json > jobs-export.json

# Count jobs by status
trix jobs list -o json | jq 'group_by(.status) | map({status: .[0].status, count: length})'

# Find long-running jobs
trix jobs list --status active -o json | jq '[.[] | select(.progress < 50)]'

# Analyze failure patterns
trix jobs list --status failed -o json | jq '[.[] | {queue, error: .error[:100]}]'

Scripting with Jobs

#!/bin/bash
# Check for failed jobs and send alert

FAILED_COUNT=$(trix jobs list --status failed -o json | jq 'length')

if [ "$FAILED_COUNT" -gt 10 ]; then
  echo "WARNING: $FAILED_COUNT failed jobs detected"
  trix jobs list --status failed --jq '.[].id'
  # Send alert to monitoring system
fi

Best Practices

Regular Monitoring

  • Check trix jobs stats regularly to monitor queue health
  • Set up alerts for high failure rates
  • Review failed jobs promptly to identify systemic issues

Troubleshooting

  • Always check detailed job information with trix jobs get before retrying
  • Look for patterns in failures (same queue, same error type)
  • Check your credit balance - some jobs fail when credits are exhausted
  • Verify API rate limits aren't being exceeded

Performance

  • Large numbers of waiting jobs may indicate a processing bottleneck
  • High failure rates may indicate configuration or API issues
  • Monitor active job counts to understand system load

Next Steps