Preview CLI

The Preview CLI validates annotation configurations and previews how schemas will render without running the full server. This is useful for rapid prototyping, debugging, and CI/CD validation.

Overview

The preview CLI provides:

• Configuration validation: Check for errors and warnings before deployment
• Schema preview: See how annotation schemas will render as HTML
• Keybinding conflict detection: Identify conflicting keyboard shortcuts
• Multiple output formats: Summary, HTML, JSON, or layout-only snippets

Basic Usage

# Default summary output
python -m potato.preview_cli config.yaml
 
# Or using the module directly
python -m potato.preview_cli path/to/your/config.yaml

Output Formats

Summary (Default)

Displays a text summary of the configuration:

python -m potato.preview_cli config.yaml

Output:

============================================================
ANNOTATION TASK PREVIEW
============================================================
Task Name: Sentiment Annotation
Task Directory: ./my_task

Validation: PASSED

ANNOTATION SCHEMAS (2 total):
----------------------------------------
  [radio] sentiment
          Select the sentiment of the text...
          Labels: 3
          Keybindings: 3

  [multiselect] topics
          Select all relevant topics...
          Labels: 5
          Keybindings: 0

============================================================

HTML Output

Generate a full HTML page preview:

python -m potato.preview_cli config.yaml --format html > preview.html

Open preview.html in a browser to see how your annotation schemas will look.

JSON Output

Generate structured JSON output for programmatic processing:

python -m potato.preview_cli config.yaml --format json

Layout-Only HTML

Generate just the annotation schema HTML snippet:

python -m potato.preview_cli config.yaml --layout-only > task_layout.html

This is useful for embedding in custom templates or testing schema rendering in isolation.

Command Line Options

Configuration Validation

The preview CLI validates your configuration and reports issues:

Errors (Blocking)

ERROR: Missing required field 'annotation_task_name'
ERROR: Must have either 'data_files' or 'data_directory'

Warnings (Non-Blocking)

WARNING: No annotation schemes found in configuration
WARNING: Key '1' used by both 'schema1:Label1' and 'schema2:Label2'

Exit Codes

• 0: Configuration is valid
• 1: Configuration has errors

Use exit codes in CI/CD pipelines:

python -m potato.preview_cli config.yaml || echo "Config validation failed"

Use Cases

Rapid Prototyping

Quickly iterate on schema designs:

# Edit config, then preview immediately
python -m potato.preview_cli config.yaml --format html > preview.html && open preview.html

CI/CD Integration

Validate configurations in your deployment pipeline:

# .github/workflows/validate.yml
- name: Validate Potato Config
  run: python -m potato.preview_cli configs/production.yaml

Template Development

Generate layout snippets for custom template integration:

python -m potato.preview_cli config.yaml --layout-only > templates/includes/schemas.html

API Reference

The preview CLI functions can also be used programmatically:

from potato.preview_cli import (
    load_config,
    validate_config,
    get_annotation_schemes,
    detect_keybinding_conflicts,
    generate_preview_html,
)
 
# Load and validate
config = load_config("config.yaml")
issues = validate_config(config)
 
# Extract schemes and check for conflicts
schemes = get_annotation_schemes(config)
conflicts = detect_keybinding_conflicts(schemes)
 
# Generate output
html = generate_preview_html(schemes)

Troubleshooting

"Module not found" Error

Ensure Potato is installed:

pip install potato-annotation

Schema Rendering Errors

If a schema fails to render, the output will include an error message. Check that your schema configuration is complete.

Further Reading

• Configuration Basics - Full configuration reference
• Annotation Schemes - Annotation schema types
• UI Configuration - Customizing the interface

For implementation details, see the source documentation.