Loro CLI

Command-line interface for the Loro Template transformation service.

Installation

From NPM (when published)

npm install -g loro-cli

From Source

git clone https://github.com/yourusername/loro-cli.git
cd loro-cli
npm install
npm link

Configuration

Before using the CLI, configure your API credentials:

# Interactive configuration
loro config

# Or set directly
loro config --api-key YOUR_API_KEY
loro config --api-url https://api.lorotemplates.com

# View current configuration
loro config --list

Alternatively, you can set environment variables:

• LORO_API_KEY - Your Loro API key
• LORO_API_URL - Loro API endpoint (default: https://api.lorotemplates.com)

Usage

Transform a Template

Transform templates using local files or remote templates:

# Local template transformation (positional argument)
loro transform template.scriban -d data.json

# Local template using -t option (requires -d)
loro transform -t template.scriban -d data.json

# With output file
loro transform -t template.scriban -d data.json -o output.txt

# Specify formats
loro transform -t template.scriban -d data.xml -i xml -f json -o output.json

# Remote template by GUID with your own data
loro transform -g 72d561bf-3c17-4b34-b48d-cee00f1f0e1e -d data.json

# Remote template with sample data (no data file needed)
loro transform -g 72d561bf-3c17-4b34-b48d-cee00f1f0e1e

# Verbose output
loro transform -t template.scriban -d data.json --verbose

List Available Templates

# List templates from Loro service
loro list

# Search templates
loro list -s "invoice"

# Show more templates
loro list -l 20

# Output as JSON
loro list --json

Validate Template Syntax

# Basic validation
loro validate template.scriban

# Validate with test data
loro validate template.scriban -d test-data.json

# Verbose validation
loro validate template.scriban --verbose

Command Reference

loro transform

Transform a template with provided data.

Options:

• -t, --template <path> - Path to local template file (requires -d option)
• -d, --data <path> - Path to data file (JSON/XML/text) - required with -t, optional for -g
• -o, --output <path> - Output file path (default: stdout)
• -f, --format <format> - Output format: json, xml, text (default: json)
• -i, --input-format <format> - Input data format: json, xml, text (default: json)
• -g, --guid <guid> - Use a remote template by GUID from Loro service
• -k, --api-key <key> - API key (overrides config)
• --api-url <url> - API URL (overrides config)
• --verbose - Show detailed output

Template Source Options:

• Local file (positional): loro transform template.scriban -d data.json
• Local file (with -t): loro transform -t template.scriban -d data.json - Both -t and -d are required
• Remote template by GUID: loro transform -g <guid> - Uses Loro's remote rendering API
  • If no -d option is provided, automatically uses the template's sample data
  • More efficient for remote templates (single API call)

loro config

Configure Loro CLI settings.

Options:

• -k, --api-key <key> - Set API key
• -u, --api-url <url> - Set API URL
• -l, --list - List current configuration
• -r, --reset - Reset to default configuration

loro list

List available templates from Loro service.

Options:

• -l, --limit <number> - Number of templates to show (default: 10)
• -s, --search <query> - Search templates by name or description
• --json - Output in JSON format

loro validate

Validate Scriban template syntax.

Options:

• -d, --data <path> - Optional: Test with sample data
• --verbose - Show detailed validation output

Template Source Options Explained

When to Use Each Option

Local Template File (Positional Argument)

loro transform template.scriban -d data.json

Use when you have a template file on your local filesystem and prefer the shorter syntax.

Local Template File (Using -t Option)

loro transform -t template.scriban -d data.json

• Explicitly specifies the template file using the -t flag
• Requires the -d option for data file (both must be provided)
• Use when you prefer explicit flags or for scripting clarity

Remote Template by GUID

# With your own data
loro transform -g 72d561bf-3c17-4b34-b48d-cee00f1f0e1e -d data.json

# Using template's sample data (no data file needed)
loro transform -g 72d561bf-3c17-4b34-b48d-cee00f1f0e1e

• Performs direct transformation on Loro's servers
• More efficient for remote templates (single API call)
• If no data file is provided (-d), automatically uses the template's sample data
• Recommended for production use with remote templates
• GUID must be a valid UUID format

Important Notes

• When using -t, you must also provide -d for the data file
• You cannot use both -t and -g options together
• Remote templates (-g) can work without a data file by using sample data

Examples

Example 1: Simple Template Transformation

Create a template file greeting.scriban:

Hello {{ name }}!
Today is {{ date }}.

Create data file data.json:

{
  "name": "John Doe",
  "date": "2024-01-15"
}

Transform:

loro transform greeting.scriban -d data.json

Output:

Hello John Doe!
Today is 2024-01-15.

Example 2: Remote Template Usage

# List available templates
loro list -s invoice

# Use a remote template with your own data
loro transform -g 72d561bf-3c17-4b34-b48d-cee00f1f0e1e -d order-data.json -o invoice.html

# Use a remote template with its sample data (no data file needed)
loro transform -g 72d561bf-3c17-4b34-b48d-cee00f1f0e1e -o invoice.html

Example 3: Batch Processing

#!/bin/bash
# Process multiple data files with the same template

for datafile in data/*.json; do
  output="${datafile%.json}.html"
  loro transform template.scriban -d "$datafile" -o "$output"
  echo "Processed: $datafile -> $output"
done

Troubleshooting

API Key Issues

If you get authentication errors:

1. Check your API key: loro config --list
2. Ensure the key is valid in your Loro dashboard
3. Try setting the key again: loro config --api-key YOUR_KEY

Network Issues

If you can't reach the API:

1. Check your internet connection
2. Verify the API URL: loro config --list
3. Try the default URL: loro config --api-url https://api.lorotemplates.com

Template Syntax Errors

Use the validate command to check templates:

loro validate template.scriban --verbose

Development

Running Tests

npm test

Building

npm run build

Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

MIT

Support

For issues and questions:

• GitHub Issues: https://github.com/yourusername/loro-cli/issues
• Documentation: https://lorotemplates.com/docs/cli
• Email: [email protected]