MOVA CLI

Command-line interface for MOVA workflows, traces, mocks, and connectors

Installation

npm install -g leryk-cli-mova

Or use with npx:

npx leryk-cli-mova [command]

Quick Start

# Run a workflow in mock mode
mova run ./workflow.json --mode mock --trace

# List recent traces
mova trace:list --limit 10

# View connector info
mova connectors:info slack

# Set mock mode
mova mock:mode hybrid

Commands

🚀 Run Workflows

Execute MOVA envelopes with various modes and options.

mova run <envelope> [options]

Options:
  --mode <mode>        Execution mode: mock|live|hybrid|record (default: mock)
  --inputs <file>      Input data JSON file
  --secrets <file>     Secrets JSON file  
  --trace              Show execution trace after completion
  --executor <type>    Executor type: local|remote (default: remote)
  --json               Output as JSON
  --base-url <url>     Sandbox base URL
  --token <token>      Auth token

Examples:

# Run in mock mode with trace
mova run ./envelopes/slack.message.json --mode mock --trace

# Run with inputs and secrets
mova run ./workflow.json --inputs ./data.json --secrets ./secrets.json

# Run in hybrid mode (use fixtures when available, otherwise real API)
mova run ./workflow.json --mode hybrid

# Output as JSON for parsing
mova run ./workflow.json --json > result.json

📊 Traces

View and monitor workflow execution traces.

List Traces

mova trace:list [options]

Options:
  --limit <n>      Number of runs to show (default: 10)
  --json           Output as JSON

Show Trace Details

mova trace:show <run_id> [options]

Options:
  --json           Output as JSON

Tail Trace (Live)

mova trace:tail <run_id> [options]

Options:
  --interval <ms>  Poll interval in milliseconds (default: 2000)

Examples:

# List last 20 traces
mova trace:list --limit 20

# Show trace details
mova trace:show abc12345

# Tail a running workflow
mova trace:tail abc12345 --interval 1000

🎭 Mocks

Control Mock Manager for testing workflows without real APIs.

Mock Mode

# Get current mode
mova mock:mode

# Set mode
mova mock:mode <mock|live|hybrid|record>

List Fixtures

# List all fixtures
mova mock:list

# List fixtures for specific service
mova mock:list slack

Record & Replay

# Start recording
mova mock:record:start [options]

Options:
  --service <name>      Filter by service
  --sanitize <fields>   Comma-separated fields to sanitize

# Stop recording
mova mock:record:stop

Hit Log

# View recent mock hits (for debugging)
mova mock:hitlog

Examples:

# Switch to hybrid mode
mova mock:mode hybrid

# List all fixtures
mova mock:list

# Record Slack API calls
mova mock:record:start --service slack --sanitize authorization,api_key

# Stop recording
mova mock:record:stop

# Check what was matched
mova mock:hitlog

🔌 Connectors

Explore and diagnose connector configurations.

List Connectors

mova connectors:list

Connector Info

mova connectors:info <name>

Connector Doctor

mova connectors:doctor <name>

Examples:

# List all connectors
mova connectors:list

# View Slack connector details
mova connectors:info slack

# Check Stripe connector configuration
mova connectors:doctor stripe

✅ Validate

Validate MOVA envelope files.

mova validate <file> [options]

Options:
  --output <type>  Output format: json, text (default: text)

🔧 Utilities

Schema Sync

mova schema:sync [url]

Snippet Generate

mova snippet:generate <type>

Configuration

Config File: ~/.mova/config.json

{
  "sandbox": {
    "baseUrl": "http://localhost:4000",
    "authToken": ""
  },
  "defaultMode": "mock",
  "output": {
    "colors": true
  },
  "executor": "remote"
}

Environment Variables

# Sandbox URL
export MOVA_SANDBOX_URL=http://localhost:4000

# Auth token
export MOVA_TOKEN=your_token_here

# Default mode
export MOVA_MODE=mock

# Executor type
export MOVA_EXECUTOR=remote

# Disable colors
export NO_COLOR=1

Configuration Priority

1. CLI flags (highest)
2. Environment variables
3. Config file (~/.mova/config.json)
4. Defaults (lowest)

Output Formats

Human-Readable (Default)

Colored, formatted output with tables and trees.

mova trace:list

run_id    started_at           duration  status   mode
abc123    2025-10-18 10:30     1.2s     success  mock
def456    2025-10-18 10:25     0.8s     success  hybrid

JSON Output

Machine-readable JSON for parsing and automation.

mova trace:list --json

[
  {
    "run_id": "abc123",
    "started_at": "2025-10-18T10:30:00Z",
    "duration_ms": 1200,
    "status": "success",
    "mode": "mock"
  }
]

Exit Codes

• 0 - Success
• 1 - CLI error (invalid input, network error, etc.)
• 2 - Workflow execution error (failed step)

Examples

Complete Workflow Testing

# 1. Set mock mode
mova mock:mode mock

# 2. Run workflow
mova run ./workflow.json --trace

# 3. View traces
mova trace:list --limit 5

# 4. Check specific trace
mova trace:show abc123

# 5. List available fixtures
mova mock:list slack

Recording Real API Responses

# 1. Start recording
mova mock:record:start --service slack --sanitize authorization

# 2. Switch to record mode
mova mock:mode record

# 3. Run workflow (will call real API and save responses)
mova run ./workflow.json

# 4. Stop recording
mova mock:record:stop

# 5. Switch back to mock mode
mova mock:mode mock

# 6. Run again (will use recorded responses)
mova run ./workflow.json --trace

Hybrid Mode Testing

# Use fixtures when available, fallback to real API
mova mock:mode hybrid
mova run ./workflow.json --trace

# Check what was mocked vs live
mova mock:hitlog

CI/CD Integration

#!/bin/bash

# Run tests in mock mode
export MOVA_MOCK_MODE=mock
export MOVA_SANDBOX_URL=http://localhost:4000

# Run workflow
if mova run ./tests/workflow.json --json > result.json; then
  echo "✅ Workflow passed"
  cat result.json | jq '.duration_ms'
else
  echo "❌ Workflow failed"
  exit 1
fi

Troubleshooting

Cannot find module errors

Make sure you're using Node.js 18+:

node --version

Sandbox connection failed

Check if the Sandbox is running:

curl http://localhost:4000/__mock/health

Update the URL if needed:

mova run ./workflow.json --base-url http://your-sandbox:4000

Connector not found

Make sure @mova-ai/connectors is installed:

npm install @mova-ai/connectors

Development

# Clone repository
git clone https://github.com/leryk-inc/mova.git
cd mova/packages/cli

# Install dependencies
npm install

# Build
npm run build

# Link for local testing
npm link

# Test CLI
mova --help

Related Packages

• @mova-ai/connectors - Connector catalog
• leryk-sdk-mova - MOVA SDK
• leryk-vscode-mova - VS Code extension

License

Apache-2.0 © Sergii Miasoiedov

Support

• Issues: https://github.com/leryk-inc/mova/issues
• Discussions: https://github.com/leryk-inc/mova/discussions
• Email: [email protected]