CLI AI Automation

Skipper CLI enables headless automation of your ORM design workflow. AI assistants and CI/CD pipelines can drive Skipper programmatically without launching the GUI, performing schema operations, exports, validations, and more through structured command-line flags with JSON output.

Typical Workflow

A full project lifecycle through the CLI typically follows this sequence:

1. List frameworks — discover available ORM and MVC frameworks.

2. Create or import project — start a new project or import from existing code / database.

3. Apply patches — modify the schema with apply-patch or apply-merge.

4. Validate — check the schema for errors and warnings.

5. Schema summary — review the current state of entities, fields, and associations.

6. Export — generate ORM code (classes and migrations).

7. Export diagram — render a visual diagram as PNG or PDF.

For incremental changes to an existing project, the workflow is shorter: schema-summary to inspect the current state, then apply-patch or apply-merge to make changes, followed by validate to confirm correctness.

Why CLI?

The CLI complements the visual designer by opening Skipper to automation scenarios where a graphical interface is impractical or unnecessary.

Running the CLI

How you invoke the CLI depends on your operating system:

Windows

On Windows, use the SkipperCli.exe wrapper included in the installation directory. This ensures proper console output in all terminals (cmd.exe, PowerShell, Windows Terminal):

SkipperCli.exe -cli-help
SkipperCli.exe -cli-validate project.skipper
SkipperCli.exe -cli-schema-summary project.skipper

Note: Do not call Skipper.exe directly from the command line — as a GUI application, its stdout is not connected to the console in PowerShell. Always use SkipperCli.exe for CLI operations.

Linux

On Linux, call the Skipper binary directly from any shell:

./Skipper -cli-help
./Skipper -cli-validate project.skipper
./Skipper -cli-schema-summary project.skipper

macOS

On macOS, call the binary inside the app bundle:

/Applications/Skipper.app/Contents/MacOS/Skipper -cli-help
/Applications/Skipper.app/Contents/MacOS/Skipper -cli-validate project.skipper
/Applications/Skipper.app/Contents/MacOS/Skipper -cli-schema-summary project.skipper

You can also create a shell alias for convenience: alias skipper="/Applications/Skipper.app/Contents/MacOS/Skipper"

How It Works

Skipper CLI operations are invoked by passing -cli-* flags to Skipper.exe. Each flag corresponds to a specific verb (action) that Skipper executes in headless mode before exiting.

• stdout receives the JSON envelope containing structured results.

• stderr receives diagnostic messages, warnings, and debug output.

• Exit codes indicate the outcome of the operation.

Prerequisites

• Valid Skipper license — a full license is required for write operations. Viewer (free) licenses can use read-only verbs only (see table below).

• Active maintenance — your license maintenance must be current. Expired maintenance will be rejected with a MAINTENANCE_EXPIRED error.

• Supported platform — Windows, Linux, or macOS with Skipper installed.

License Capabilities

The table below shows which CLI verbs are available for each license type:

Note: Viewer licenses can read and export existing projects but cannot create, modify, or import projects via CLI. For full CLI automation capabilities including apply-patch, a full Skipper license with active maintenance is required.

Quick Start

List all available CLI verbs and their usage:

Skipper.exe -cli-help

Validate a project file for errors and warnings:

Skipper.exe -cli-validate project.skipper

Get a high-level summary of entities, fields, and associations in a project:

Skipper.exe -cli-schema-summary project.skipper

JSON Envelope Format

Every CLI verb outputs a JSON envelope to stdout. This consistent structure makes it straightforward for scripts and AI assistants to parse the results regardless of which verb was called.

{
  "status": "ok",
  "command": "schema-summary",
  "data": {
    "entities": 42,
    "fields": 318,
    "associations": 67
  },
  "warnings": [],
  "meta": {
    "duration_ms": 1250,
    "skipper_version": "3.3.8.1844",
    "schema_version": "3",
    "started_at": "2026-04-30T10:15:32Z"
  }
}

When an error occurs, the envelope includes an error object instead of data:

{
  "status": "error",
  "command": "validate",
  "error": {
    "code": "PROJECT_LOAD_FAILED",
    "message": "Cannot open project file: project.skipper",
    "hint": "Check that the file exists and is a valid Skipper project."
  },
  "warnings": [],
  "meta": {
    "duration_ms": 320,
    "skipper_version": "3.3.8.1844",
    "schema_version": "3",
    "started_at": "2026-04-30T10:16:01Z"
  }
}

Key envelope fields:

• status — "ok" on success, "error" on failure.

• command — the verb that was executed.

• data — verb-specific result payload (present on success).

• warnings — array of non-fatal warning strings.

• error — error details with code, message, and optional hint (present on failure).

• meta — execution metadata including duration_ms, skipper_version, schema_version, and started_at timestamp.

Global Flags

These flags can be combined with any CLI verb to control output behavior:

For the full list of available verbs and their parameters, see the CLI Reference. For practical usage examples, see Examples.