Integration Guide

Preview feature: CLI AI Automation is a preview feature. If you encounter any issues, please report them at support.skipper18.com.

Skipper CLI can be integrated into any automated workflow that runs command-line tools. This guide covers common integration patterns for CI/CD pipelines, AI-powered development tools, and custom scripting.

All examples assume Skipper is installed and available on the system PATH. On Linux, set QT_QPA_PLATFORM=offscreen when running headless. Every CLI verb outputs a JSON envelope on stdout that you can parse programmatically.

AI Tool Integration

Skipper CLI was designed with AI assistants in mind. The structured JSON output makes it straightforward for any AI tool to read and manipulate your ORM schema. Below are setup examples for popular AI coding tools.

Claude Code

Add Skipper as a skill in your project's CLAUDE.md file so Claude Code can use the CLI automatically when working with your database schema.

## Skipper ORM Tool

This project uses Skipper for ORM schema management. The schema file is `project.skipper`.

Available CLI commands:
- Validate: `Skipper.exe -cli-validate project.skipper -quiet`
- Export:   `Skipper.exe -cli-export project.skipper -quiet`
- Summary:  `Skipper.exe -cli-schema-summary project.skipper -quiet`
- Patch:    `Skipper.exe -cli-apply-patch project.skipper -patch ops.json -output project.skipper -quiet`

All commands output a JSON envelope on stdout. Parse with jq.
When modifying the schema, use -cli-apply-patch with an ops.json file.
Always run -cli-validate after making changes.

With this in place, Claude Code can read your schema, make changes, and validate results within a single conversation.

ChatGPT

Add Skipper CLI reference to your ChatGPT Custom Instructions so it knows how to generate correct commands for your project.

# Custom Instructions for ChatGPT

I use Skipper ORM tool for database schema management. When I ask about
database changes, generate Skipper CLI commands:

- Validate: Skipper.exe -cli-validate <project.skipper> -quiet
- Export:   Skipper.exe -cli-export <project.skipper> -quiet
- Patch:    Skipper.exe -cli-apply-patch <project.skipper> -patch <ops.json> -output <out.skipper> -quiet
- Compare:  Skipper.exe -cli-compare <new.skipper> <old.skipper> -quiet

Patch operations use JSON format: {"op": "<name>", "args": {...}}
Available ops: add_entity, add_field, add_association, remove_entity, etc.
Output is always a JSON envelope with "status" and "data" fields.

Cursor

Add Skipper commands to your .cursorrules file so Cursor can suggest and run CLI commands when you work with your schema.

# .cursorrules

## Database Schema (Skipper)

The project schema is defined in project.skipper.
Use these CLI commands to interact with it:

  Skipper.exe -cli-schema-summary project.skipper -quiet   # Read current schema as JSON
  Skipper.exe -cli-validate project.skipper -quiet         # Check for errors
  Skipper.exe -cli-export project.skipper -quiet           # Generate ORM code
  Skipper.exe -cli-apply-patch project.skipper -patch ops.json -output project.skipper -quiet

After any schema change, always validate and then export.
Parse stdout JSON to check the "status" field ("ok" or "error").

Generic AI

For any AI tool that accepts a system prompt or project context file, include the Skipper CLI reference so the model can generate valid commands.

# Skipper CLI Reference for AI Tools

Skipper is an ORM design tool with a headless CLI.
All commands print a JSON envelope to stdout: {"status": "ok"|"error", "data": {...}}

Key commands:
  Skipper.exe -cli-validate <project.skipper>           # Validate schema
  Skipper.exe -cli-export <project.skipper>             # Export ORM code
  Skipper.exe -cli-schema-summary <project.skipper>     # Dump schema as JSON
  Skipper.exe -cli-compare <new.skipper> <old.skipper>  # Diff two schemas
  Skipper.exe -cli-apply-patch <project> -patch <ops.json> -output <out>  # Modify schema
  Skipper.exe -cli-create-migration <project.skipper>   # Create migration

Add -quiet to suppress stderr. Add -verbose for debug output.
Pipe stdout through jq for parsing: Skipper.exe -cli-validate project.skipper -quiet | jq '.data'

Scripting Patterns

When building custom automation scripts around Skipper CLI, these patterns will help you handle common scenarios.

Batch Operations

Apply multiple patch files in sequence to make a series of changes to your schema. This is useful when you have separate patch files for different features or migration steps.

#!/bin/bash
# Apply multiple patches to a Skipper project

PROJECT="project.skipper"
PATCHES_DIR="./patches"

for PATCH in "$PATCHES_DIR"/*.json; do
    echo "Applying $(basename "$PATCH")..."
    RESULT=$(Skipper.exe -cli-apply-patch "$PROJECT" -patch "$PATCH" -output "$PROJECT" -quiet)
    STATUS=$(echo "$RESULT" | jq -r '.status')

    if [ "$STATUS" != "ok" ]; then
        echo "FAILED: $(basename "$PATCH")"
        echo "$RESULT" | jq '.error'
        exit 1
    fi

    OPS=$(echo "$RESULT" | jq '.data.ops_executed')
    echo "  Applied $OPS operation(s)"
done

echo "All patches applied successfully."

Error Handling

Every Skipper CLI verb returns a JSON envelope with a status field. Check this field to determine success or failure, and inspect the error object for details.

#!/bin/bash
# Robust error handling for Skipper CLI

run_skipper() {
    local DESCRIPTION="$1"
    shift
    local RESULT
    RESULT=$(Skipper.exe "$@" -quiet 2>/dev/null)
    local EXIT_CODE=$?

    # Check process exit code
    if [ $EXIT_CODE -ne 0 ]; then
        echo "ERROR: $DESCRIPTION - Skipper exited with code $EXIT_CODE"
        return 1
    fi

    # Check envelope status
    local STATUS
    STATUS=$(echo "$RESULT" | jq -r '.status' 2>/dev/null)
    if [ "$STATUS" != "ok" ]; then
        local ERROR_CODE
        ERROR_CODE=$(echo "$RESULT" | jq -r '.error.code // "UNKNOWN"')
        local ERROR_MSG
        ERROR_MSG=$(echo "$RESULT" | jq -r '.error.message // "No message"')
        echo "ERROR: $DESCRIPTION - $ERROR_CODE: $ERROR_MSG"
        return 1
    fi

    echo "$RESULT"
    return 0
}

# Usage
RESULT=$(run_skipper "Validate schema" -cli-validate project.skipper) || exit 1
echo "Validation passed"

RESULT=$(run_skipper "Export code" -cli-export project.skipper) || exit 1
FILES=$(echo "$RESULT" | jq '.data.files_written | length')
echo "Exported $FILES file(s)"

Chaining Verbs

A common workflow is to validate the schema, apply changes, and then export updated code. Chain these verbs together in a single script with proper error handling at each step.

#!/bin/bash
# Full pipeline: validate -> patch -> validate -> export

PROJECT="project.skipper"
PATCH="changes.json"
set -e

echo "Step 1: Validate current schema..."
RESULT=$(Skipper.exe -cli-validate "$PROJECT" -quiet)
ERRORS=$(echo "$RESULT" | jq '.data.summary.error_count')
if [ "$ERRORS" -gt 0 ]; then
    echo "Current schema has errors. Fix them before patching."
    echo "$RESULT" | jq '.data.issues[]'
    exit 1
fi
echo "  Schema is valid."

echo "Step 2: Apply patch..."
RESULT=$(Skipper.exe -cli-apply-patch "$PROJECT" -patch "$PATCH" -output "$PROJECT" -quiet)
STATUS=$(echo "$RESULT" | jq -r '.status')
if [ "$STATUS" != "ok" ]; then
    echo "Patch failed."
    echo "$RESULT" | jq '.error'
    exit 1
fi
OPS=$(echo "$RESULT" | jq '.data.ops_executed')
echo "  Applied $OPS operation(s)."

echo "Step 3: Validate patched schema..."
RESULT=$(Skipper.exe -cli-validate "$PROJECT" -quiet)
ERRORS=$(echo "$RESULT" | jq '.data.summary.error_count')
if [ "$ERRORS" -gt 0 ]; then
    echo "Schema has errors after patching!"
    echo "$RESULT" | jq '.data.issues[]'
    exit 1
fi
echo "  Patched schema is valid."

echo "Step 4: Export code..."
RESULT=$(Skipper.exe -cli-export "$PROJECT" -quiet)
FILES=$(echo "$RESULT" | jq '.data.files_written | length')
echo "  Exported $FILES file(s)."

echo "Pipeline completed successfully."

Error Behavior on Patch Failure

On apply-patch failure, the output file is not written. Operations 0 through failed_op_index-1 were applied in memory but not saved. Always retry with a clean copy of the original input file.

CI/CD Integration

License requirement: Every server running CI/CD with Skipper CLI needs its own full Skipper license. Viewer licenses are not sufficient for write operations (apply-patch, create-migration, import).

Adding Skipper CLI to your CI/CD pipeline ensures that your ORM schema is always validated and exported as part of your build process. A typical CI pipeline follows the workflow described in the Introduction: validate the schema, apply any pending patches, validate again, then export code and optionally export a diagram.

Jenkins

A Jenkins pipeline can validate and export your schema in dedicated stages. Use the JSON envelope to detect failures and abort the build early.

pipeline {
    agent any
    environment {
        QT_QPA_PLATFORM = 'offscreen'
    }
    stages {
        stage('Validate Schema') {
            steps {
                sh '''
                    RESULT=$(Skipper.exe -cli-validate project.skipper -quiet)
                    ERRORS=$(echo "$RESULT" | jq '.data.summary.error_count')
                    if [ "$ERRORS" -gt 0 ]; then
                        echo "Schema validation failed with $ERRORS error(s)"
                        echo "$RESULT" | jq '.data.issues[]'
                        exit 1
                    fi
                    echo "Schema validation passed"
                '''
            }
        }
        stage('Export Code') {
            steps {
                sh '''
                    Skipper.exe -cli-export project.skipper -quiet
                '''
            }
        }
        stage('Deploy') {
            steps {
                sh 'echo "Deploying application..."'
            }
        }
    }
}

Pre-commit Hook

A Git pre-commit hook that validates any staged .skipper files before allowing the commit. Save this as .git/hooks/pre-commit and make it executable.

#!/bin/bash
# Pre-commit hook: validate Skipper project files before commit

SKIPPER_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.skipper$')

if [ -z "$SKIPPER_FILES" ]; then
    exit 0
fi

echo "Validating Skipper project files..."

for FILE in $SKIPPER_FILES; do
    RESULT=$(Skipper.exe -cli-validate "$FILE" -quiet 2>/dev/null)
    STATUS=$(echo "$RESULT" | jq -r '.status')
    ERRORS=$(echo "$RESULT" | jq '.data.summary.error_count')

    if [ "$STATUS" != "ok" ] || [ "$ERRORS" -gt 0 ]; then
        echo "ERROR: Validation failed for $FILE"
        echo "$RESULT" | jq '.data.issues[] | "  \(.severity): \(.message)"' -r
        exit 1
    fi
    echo "  OK: $FILE"
done

echo "All Skipper files validated successfully."
exit 0