# CLI Reference

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"
```
