# Orshot CLI

> Generate visuals from your terminal with the Orshot command-line interface

- **URL**: https://orshot.com/docs/integrations/orshot-cli

---

**NPM Package**: [https://www.npmjs.com/package/orshot-cli](https://www.npmjs.com/package/orshot-cli)

## Video Tutorial

<div className="mb-4">
  <iframe
    width="100%"
    height="400"
    src="https://www.youtube.com/embed/xK-5mJc9gcY"
    title="Orshot CLI Demo"
    frameBorder="0"
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
    allowFullScreen
    className="rounded-lg"
  ></iframe>
</div>

## Introduction

The Orshot CLI is a command-line interface that allows you to generate dynamic images from your Orshot templates directly from your terminal. Perfect for automation, scripting, and integrating image generation into your development workflow.

## Features

- **Template Management**: List and discover available library and studio templates
- **Image Generation**: Generate images from both library and studio templates
- **Video & PDF Generation**: Create MP4, WebM, GIF, and multi-page PDFs
- **Multiple Output Formats**: Support for PNG, JPG, JPEG, WebP, AVIF, PDF, MP4, WebM, GIF
- **Flexible Response Types**: Get outputs as base64, binary files, or hosted URLs
- **Interactive Mode**: Guided template modification setup
- **Batch Processing**: Generate multiple variations with different modifications
- **Cross-Platform**: Works on macOS, Linux, and Windows

## Installation

Install the CLI globally using npm:```bash
npm install -g orshot-cli
```## Getting Started

### 1. Authentication

First, obtain your API key from [Orshot Workspace > Settings > API Key](https://orshot.com/signup), then authenticate:```bash
orshot auth login <your-api-key>
```You can also run the command without the API key to be prompted securely:```bash
orshot auth login
```### 2. Verify Authentication

Check your authentication status:```bash
orshot auth whoami
```### 3. Discover Templates

List your available templates:```bash
# List library templates
orshot templates library

# List studio templates
orshot templates studio
```### 4. Generate Your First Image

Generate an image from a template:```bash
# Basic generation
orshot generate library website-screenshot

# Generate with custom modifications
orshot generate library website-screenshot -m websiteUrl="https://example.com"

# Interactive mode for guided setup
orshot generate library website-screenshot --interactive
```## Commands Reference

### Authentication Commands

- `orshot auth login [api-key]` - Log in with your API key
- `orshot auth logout` - Log out and clear credentials
- `orshot auth whoami` - Show current user information

### Template Commands

- `orshot templates library` - List library templates
- `orshot templates studio` - List studio templates
- `orshot templates modifications <template-id>` - Show available modifications

### Generation Commands

- `orshot generate library <template-id>` - Generate from library template
- `orshot generate studio <template-id>` - Generate from studio template

## Common Options

### Generation Options

- `-m, --modification <key=value>` - Template modifications (repeatable)
- `-f, --format <format>` - Output format: png, jpg, webp, avif, pdf, mp4, webm, gif
- `-t, --type <type>` - Response type: base64, binary, url
- `-o, --output <filename>` - Custom output filename
- `-s, --scale <number>` - Scale factor (e.g., 2 for 2x size)
- `-p, --pages <numbers...>` - Specific pages to render (e.g., 1 3 for multi-page templates)
- `--dpi <number>` - DPI for PDF output (default: 72)
- `--quality <number>` - Quality (1-100) for JPG/WebP/AVIF/Video
- `--video-loop` - Set video output to loop
- `--video-muted` - Mute audio in video output
- `--video-trim-start <seconds>` - Trim video start time
- `--video-trim-end <seconds>` - Trim video end time
- `--webhook <url>` - Webhook URL for async notification
- `-i, --interactive` - Interactive modification mode
- `-j, --json` - Output response as JSON

### Template Options

- `-l, --limit <number>` - Limit number of results
- `-j, --json` - Output as JSON
- `-t, --type <type>` - Template type: library or studio

## Usage Examples

### Basic Workflow```bash
# Authenticate
orshot auth login your-api-key

# List available templates
orshot templates library

# Generate with modifications
orshot generate library website-screenshot \
  -m websiteUrl="https://github.com" \
  -o github-screenshot.png
```### Interactive Mode

For templates with many modifications, use interactive mode:```bash
orshot generate library website-screenshot --interactive
```This will guide you through setting up modifications step by step.

### Batch Processing

Generate multiple variations:```bash
orshot generate library website-screenshot -m websiteUrl="https://github.com" -o github.png
orshot generate library website-screenshot -m websiteUrl="https://stackoverflow.com" -o stackoverflow.png
orshot generate library website-screenshot -m websiteUrl="https://npmjs.com" -o npmjs.png
```### Different Output Formats```bash
# Generate PNG (default)
orshot generate library website-screenshot -m websiteUrl="https://example.com" -o website.png

# Generate JPG
orshot generate library website-screenshot -m websiteUrl="https://example.com" -f jpg -o website.jpg

# Generate PDF
orshot generate library website-screenshot -m websiteUrl="https://example.com" -f pdf -o website.pdf

# Get download URL instead of file
orshot generate library website-screenshot -m websiteUrl="https://example.com" -t url
```### Video Generation

Generate MP4 videos or GIFs with trim and loop options:```bash
# Generate a looping video
orshot generate studio video-template-123 -f mp4 --video-loop

# Generate a GIF trimmed to first 5 seconds
orshot generate studio video-template-123 -f gif --video-trim-start 0 --video-trim-end 5
```### Multi-Page Documents

Generate PDF reports or specific page ranges:```bash
# Generate high-quality PDF (300 DPI)
orshot generate studio report-template-456 -f pdf --dpi 300

# Generate only specific pages (1 and 3)
orshot generate studio multi-page-template-789 -f pdf --pages 1 3
```### Async Operations (Webhooks)

For long-running tasks like 4K video rendering, use webhooks:```bash
orshot generate studio heavy-video-template \
  -f mp4 \
  --quality 100 \
  --webhook "https://your-api.com/webhooks/orshot-callback"
```### Studio Templates

Studio templates work the same way as library templates:```bash
# List studio templates
orshot templates studio

# Generate from studio template
orshot generate studio def456 -m name="John Doe" -m title="CEO"
```## Configuration

The CLI stores configuration in your system's config directory:

- **macOS**: `~/Library/Preferences/orshot-cli/config.json`
- **Linux**: `~/.config/orshot-cli/config.json`
- **Windows**: `%APPDATA%/orshot-cli/config.json`

## Troubleshooting

### Common Issues

**Authentication Error**:```bash
❌ Not authenticated. Please run:
   orshot auth login <your-api-key>
```Solution: Run the login command with your API key.

**Template Not Found**:```bash
❌ Failed to generate image: Template not found.
```Solution: Verify the template ID and ensure you have access to it.

**Invalid API Key**:```bash
❌ Login failed: Invalid API key. Please check your credentials.
```Solution: Double-check your API key from the Orshot dashboard.

### Getting Help

Use the `--help` flag with any command for detailed usage information:```bash
orshot --help
orshot generate --help
orshot templates --help
```## Integration with Scripts

The CLI is perfect for automation and scripting:```bash
#!/bin/bash

# Generate website screenshots for different sites
orshot generate library website-screenshot \
  -m websiteUrl="https://github.com/$REPO_NAME" \
  -o "github-${REPO_NAME}.png"

orshot generate library website-screenshot \
  -m websiteUrl="https://docs.$DOMAIN.com" \
  -o "docs-${DOMAIN}.png"
```The CLI supports JSON output for programmatic use:```bash
# Get template list as JSON
templates=$(orshot templates library --json)

# Generate image and get response as JSON
response=$(orshot generate library website-screenshot -m websiteUrl="https://example.com" -j)
```