The Aja CLI (aja) provides command-line access to the Motion Pipeline for
batch processing, automation, and scripting.
Installation#
# 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.
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#
# 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.
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#
# 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.
aja convert formats
aja convert skeletons#
List available skeleton templates.
aja convert skeletons
aja inspect#
Inspect motion file quality.
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#
# 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.
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.
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.
aja jobs cancel [options] <job-ids...>
| Option | Description |
|---|---|
-f, --force |
Cancel without confirmation |
aja jobs retry#
Retry failed jobs.
aja jobs retry [options] <job-ids...>
| Option | Description |
|---|---|
--reset-priority |
Reset to normal priority |
aja jobs watch#
Watch job status in real-time.
aja jobs watch [options] [job-ids...]
| Option | Description |
|---|---|
--all |
Watch all pending/running jobs |
Examples#
# 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.
aja config list [options]
| Option | Description |
|---|---|
--domain <domain> |
Filter by domain |
--verbose |
Show detailed information |
aja config get#
Get configuration details.
aja config get <name-or-id>
aja config create#
Create a new configuration.
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.
aja config update [options] <name-or-id>
aja config delete#
Delete a configuration.
aja config delete [options] <name-or-id>
| Option | Description |
|---|---|
-f, --force |
Delete without confirmation |
Examples#
# 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.
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#
# 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.
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.
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.
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#
# 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:
# 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#
#!/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#
#!/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#
#!/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"