Eve library

CLI Reference

Guide

Revision 1

On this page

The Aja CLI (aja) provides command-line access to the Motion Pipeline for batch processing, automation, and scripting.

Installation#

bash
# Install globally with pnpm
pnpm add -g @aja/cli

# Or install locally in your project
pnpm add @aja/cli

Global Options#

These options are available for all commands:

Option Description
-v, --version Display the current version
-q, --quiet Suppress non-essential output
--no-color Disable colored output
--json Output results as JSON
--api-url <url> Motion pipeline API URL (default: http://localhost:3000)
--api-key <key> API key for authentication
-h, --help Display help for command

Environment Variables#

Variable Description
AJA_API_URL Default API URL
AJA_API_KEY Default API key

Commands#

aja process#

Process videos to extract motion data.

bash
aja process [options] [input...]

Arguments#

Argument Description
input... Video files or URLs to process

Options#

Option Description
-c, --config <name> Pipeline configuration name or ID
-p, --preset <preset> Quality preset: draft, standard, high, ultra (default: standard)
-d, --domain <domain> Target domain: yoga, fitness, dance, martial-arts, general (default: general)
-o, --output <dir> Output directory for results
-f, --format <formats...> Output formats: bvh, fbx, glb, usd, alembic (default: fbx)
--priority <priority> Job priority: critical, high, normal, low, background (default: normal)
--webhook <url> Webhook URL for completion notification
--tags <tags...> Tags for job organization
--timeout <ms> Processing timeout in milliseconds (default: 3600000)
--wait Wait for processing to complete
--no-download Do not download results after completion
-i, --interactive Interactive mode for configuration

Examples#

bash
# Process a single video
aja process video.mp4

# Process with high quality preset
aja process --preset high --domain dance video.mp4

# Process multiple videos
aja process video1.mp4 video2.mp4 video3.mp4

# Process with URL input
aja process https://example.com/video.mp4

# Process and wait for results
aja process --wait --output ./output video.mp4

# Process with webhook notification
aja process --webhook https://myapp.com/webhook video.mp4

# Interactive mode
aja process -i

# Output as JSON
aja process --json video.mp4

aja convert#

Convert motion files between formats.

bash
aja convert [options] <input> <output-format>

Arguments#

Argument Description
input Input file(s) or glob pattern
output-format Target format: bvh, fbx, glb, gltf, usd, usda, usdc, abc, c3d, trc, asf, amc

Options#

Option Description
-o, --output <dir> Output directory (default: same as input)
--fps <rate> Target frame rate (default: 30)
--skeleton <template> Target skeleton template: mixamo, unity, unreal, h36m
--scale <factor> Scale factor for units (default: 1.0)
--up-axis <axis> Up axis: Y, Z (default: Y)
--forward-axis <axis> Forward axis: +X, -X, +Y, -Y, +Z, -Z (default: -Z)
--cleanup Apply motion cleanup (noise reduction, foot sliding)
--preserve-hierarchy Preserve original skeleton hierarchy
--embed-skeleton Embed skeleton definition in output
-r, --recursive Process directories recursively
--overwrite Overwrite existing files
--dry-run Show what would be converted without converting

Examples#

bash
# Convert BVH to FBX
aja convert motion.bvh fbx

# Convert with skeleton retargeting
aja convert --skeleton mixamo motion.bvh fbx

# Batch convert all BVH files in a directory
aja convert "*.bvh" fbx

# Convert with axis correction
aja convert --up-axis Z --forward-axis +Y motion.bvh glb

# Preview changes without converting
aja convert --dry-run "*.bvh" fbx

# Recursive conversion
aja convert -r ./motions fbx -o ./output

Subcommands#

aja convert formats#

List all supported motion formats.

bash
aja convert formats
aja convert skeletons#

List available skeleton templates.

bash
aja convert skeletons

aja inspect#

Inspect motion file quality.

bash
aja inspect [options] <input...>

Arguments#

Argument Description
input... Motion files to inspect

Options#

Option Description
--skeleton Check skeleton consistency
--contacts Check foot contacts and ground plane
--quality Calculate quality metrics
--all Run all checks
--threshold <value> Quality threshold for pass/fail (0-1, default: 0.8)
-o, --output <file> Save report to file
--format <format> Report format: text, json, html (default: text)

Examples#

bash
# Basic inspection
aja inspect motion.fbx

# Full quality analysis
aja inspect --all motion.fbx

# Check multiple files
aja inspect --quality *.bvh

# Save report as JSON
aja inspect --all --format json -o report.json motion.fbx

# Quality threshold check (for CI/CD)
aja inspect --quality --threshold 0.9 motion.fbx

aja jobs#

Manage pipeline jobs.

aja jobs list#

List pipeline jobs.

bash
aja jobs list [options]
Option Description
-s, --status <status> Filter by status
-t, --tags <tags...> Filter by tags
--limit <n> Maximum number of jobs (default: 20)
--before <id> Cursor for pagination
--sort <field> Sort by field: created, updated, priority
--order <order> Sort order: asc, desc

aja jobs status#

Get job status and details.

bash
aja jobs status [options] <job-id>
Option Description
-w, --watch Watch for status changes
--interval <ms> Watch interval in milliseconds (default: 2000)

aja jobs cancel#

Cancel running or queued jobs.

bash
aja jobs cancel [options] <job-ids...>
Option Description
-f, --force Cancel without confirmation

aja jobs retry#

Retry failed jobs.

bash
aja jobs retry [options] <job-ids...>
Option Description
--reset-priority Reset to normal priority

aja jobs watch#

Watch job status in real-time.

bash
aja jobs watch [options] [job-ids...]
Option Description
--all Watch all pending/running jobs

Examples#

bash
# List recent jobs
aja jobs list

# List failed jobs
aja jobs list --status failed

# Get job status
aja jobs status job-abc-123

# Watch job progress
aja jobs status -w job-abc-123

# Cancel a job
aja jobs cancel job-abc-123

# Retry failed jobs
aja jobs retry job-abc-123 job-def-456

# Watch all running jobs
aja jobs watch --all

aja config#

Manage pipeline configurations.

aja config list#

List all configurations.

bash
aja config list [options]
Option Description
--domain <domain> Filter by domain
--verbose Show detailed information

aja config get#

Get configuration details.

bash
aja config get <name-or-id>

aja config create#

Create a new configuration.

bash
aja config create [options] <name>
Option Description
-d, --domain <domain> Target domain (default: general)
-p, --preset <preset> Quality preset (default: standard)
--description <text> Configuration description
-f, --file <path> Create from YAML/JSON file

aja config update#

Update an existing configuration.

bash
aja config update [options] <name-or-id>

aja config delete#

Delete a configuration.

bash
aja config delete [options] <name-or-id>
Option Description
-f, --force Delete without confirmation

Examples#

bash
# List all configs
aja config list

# Create a new config
aja config create dance-hq --domain dance --preset high

# Create from file
aja config create -f config.yaml

# Get config details
aja config get dance-hq

# Update config
aja config update dance-hq --preset ultra

# Delete config
aja config delete dance-hq

aja health#

Check service health and status.

bash
aja health [options]

Options#

Option Description
-w, --watch Continuously monitor health
--interval <ms> Watch interval (default: 5000)
--include-queue Include queue statistics
--include-components Include component health details

Examples#

bash
# Basic health check
aja health

# Detailed health with queue stats
aja health --include-queue --include-components

# Monitor health continuously
aja health -w

aja debug#

Debug and troubleshoot pipeline operations.

aja debug stream#

Stream real-time processing events.

bash
aja debug stream [options] <job-id>
Option Description
--verbose Show all event details
--stage <stage> Filter by stage

aja debug queue#

View queue status and statistics.

bash
aja debug queue [options]
Option Description
-w, --watch Continuously monitor queue
--interval <ms> Watch interval (default: 2000)

aja debug replay#

Replay a job for debugging.

bash
aja debug replay [options] <job-id>
Option Description
--config <name> Use different configuration
--preset <preset> Use different preset
--stage <stage> Start from specific stage

Examples#

bash
# Stream job events
aja debug stream job-abc-123

# Monitor queue
aja debug queue -w

# Replay a job with different settings
aja debug replay job-abc-123 --preset ultra

Exit Codes#

Code Meaning
0 Success
1 General error
2 Invalid arguments
3 API connection failed
4 Authentication failed
5 Job failed

JSON Output#

Use --json flag for machine-readable output:

bash
# Get job status as JSON
aja jobs status --json job-abc-123 | jq '.status'

# List jobs as JSON
aja jobs list --json | jq '.jobs[] | {id, status}'

# Health check as JSON
aja health --json | jq '.components'

Scripting Examples#

Batch Processing Script#

bash
#!/bin/bash

# Process all videos in a directory
for video in ./videos/*.mp4; do
  echo "Processing: $video"
  aja process --wait --output ./output "$video"
done

CI/CD Quality Gate#

bash
#!/bin/bash

# Check motion quality meets threshold
result=$(aja inspect --quality --threshold 0.9 --json output.fbx)
quality=$(echo "$result" | jq '.overallScore')

if (( $(echo "$quality < 0.9" | bc -l) )); then
  echo "Quality check failed: $quality"
  exit 1
fi

echo "Quality check passed: $quality"

Webhook Processing#

bash
#!/bin/bash

# Submit job with webhook
job_id=$(aja process --json --webhook https://myapp.com/webhook video.mp4 | jq -r '.jobIds[0]')
echo "Submitted job: $job_id"