npm package: @lorotemplates/cli
Description: Command-line interface for Loro Template transformation service
Author: alan@lorotempates.com>
Latest version: 1.1.0

# Loro CLI

Command-line interface for the Loro Template transformation service.

## Installation

### From NPM (when published)
```bash
npm install -g loro-cli
```

### From Source
```bash
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:

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# 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)**
```bash
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)**
```bash
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**
```bash
# 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`:
```json
{
  "name": "John Doe",
  "date": "2024-01-15"
}
```

Transform:
```bash
loro transform greeting.scriban -d data.json
```

Output:
```
Hello John Doe!
Today is 2024-01-15.
```

### Example 2: Remote Template Usage

```bash
# 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

```bash
#!/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:
```bash
loro validate template.scriban --verbose
```

## Development

### Running Tests
```bash
npm test
```

### Building
```bash
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: support@lorotemplates.com