CLI Reference

Complete reference for all Skipper CLI verbs and patch operations. Every verb emits a single JSON envelope on stdout.

Verbs

Verb Details

help

Skipper.exe -cli-help [<verb-name>]

Lists all available verbs, or shows detailed usage for one verb. Returns UNKNOWN_VERB if the verb name is not recognised.

validate

Skipper.exe -cli-validate <project.skipper>

Data: { issues: [{severity, code, object, message}], summary: {error_count, warning_count} }
Errors: PROJECT_LOAD_FAILED, VALIDATION_FAILED.

export

Skipper.exe -cli-export <project.skipper>

Data: { files_written: [{path, bytes}], framework: "...", output_dir: "..." }
Errors: PROJECT_LOAD_FAILED, EXPORT_FAILED.
Files are written relative to the project file location, into each module's export_path.

export-classes

Skipper.exe -cli-export-classes <project.skipper>

Export classes/models only. Currently returns NOT_IMPLEMENTED; use -cli-export for full export.

export-migrations

Skipper.exe -cli-export-migrations <project.skipper>

Export migrations only. Currently returns NOT_IMPLEMENTED; use -cli-export for full export.

create-migration

Skipper.exe -cli-create-migration <project.skipper>

Data: { created: true } (success) or { created: false, reason: "no_changes_pending" } (no changes).
Errors: MIGRATIONS_DISABLED.

create-project

Skipper.exe -cli-create-project -output <path> -orm <name> -mvc <name> [-name <project-name>]

Creates an empty .skipper file with the chosen ORM and MVC framework.
Data: { output_path: "...", orm: "...", mvc: "..." }
Errors: UNKNOWN_FRAMEWORK, IO_ERROR, VIEWER_LICENSE.

schema-summary

Skipper.exe -cli-schema-summary <project.skipper> [-with-visual]

Data: { project: {...} } -- see the Schema JSON Format page for the full structure.

import-project

Skipper.exe -cli-import-project <scan-dir> -output <path> -orm <name> -mvc <name> [-name <project-name>]

Scans a codebase directory and builds a .skipper from discovered files.
Data: { output_path: "...", orm: "...", mvc: "...", modules_created: <int>, entities_imported: <int> }
Errors: IO_ERROR, VIEWER_LICENSE.

import-database

Skipper.exe -cli-import-database -output <path> -db-class <sqlite|mysql|postgres|sqlserver> -connection <conn> -orm <name> -mvc <name> [-name <project-name>] [-skip-initial-migrations]

Reverse-engineers a .skipper from a live database connection.
Errors: DB_CONNECTION_FAILED, DB_IMPORT_FAILED, UNKNOWN_FRAMEWORK, VIEWER_LICENSE.

compare

Skipper.exe -cli-compare <new.skipper> <old.skipper>

Data: { summary: {added, removed, modified, identical}, items: [{action, type, name, details?}] }
Diffs two .skipper files using the migration diff engine.

apply-patch

Skipper.exe -cli-apply-patch <project.skipper> -patch <ops.json> -output <out.skipper>

Data (success): { ops_executed: <int>, output_path: "..." }
Data (failure): { ops_attempted: <int>, failed_op_index: <int> }
Errors: INVALID_OP, OBJECT_NOT_FOUND, MALFORMED_INPUT_FILE.
On failure, the output file is not written. Retry with the original input file.

apply-merge

Skipper.exe -cli-apply-merge <project.skipper> -merge <state.json> -output <out.skipper>

Data: { objects_changed: <int>, output_path: "..." }
Errors: INVALID_MERGE_INPUT, OBJECT_NOT_FOUND, MALFORMED_INPUT_FILE.
See the Merge Input Format section below for the expected JSON structure.

export-diagram

Skipper.exe -cli-export-diagram <project.skipper> -format <png|pdf> -output <path>

Data: { format: "...", output_path: "...", bytes: <int> }
Errors: INVALID_ARG_VALUE, NOT_IMPLEMENTED (svg). Available in Skipper.exe (GUI build), not in SkipperCli.exe (console build). On Linux set QT_QPA_PLATFORM=offscreen.

list-frameworks

List available ORM and MVC frameworks.

Skipper.exe -cli-list-frameworks

Data: { orm_frameworks: [{name: "..."}], mvc_frameworks: [{name: "..."}] }

Patch Operations

The apply-patch verb accepts a JSON file containing an ordered list of operations. The format follows the spirit of RFC 6902 (JSON Patch). Each operation is an object with op (the operation name) and args (an object of arguments). The top-level structure is:

{"ops": [{"op": "name", "args": {...}}, ...]}

There are 36 operations in total. Operations are executed in order. If any operation fails, execution stops and the failure index is reported. On failure, the output file is not written. Retry with the original input file. Required arguments are shown in bold; optional arguments are in [brackets].

Entity Operations

Field Operations

Association Operations

Module Operations

Index Operations

Many-to-Many Operations

Embedded Operations

Inheritance Operations

Region Operations

Comment Operations

ORM Attribute Operations

The object_type argument defaults to "entity". Supported types for ORM attribute write operations: entity, field, module, association. Schema-summary emits orm_attributes on all object types (including index, many-to-many, embedded, region) but write operations for those types are not yet implemented.

Visual Layout Operations

Field ORM Attribute Addressing

For object_type: "field", use one of these formats to identify the field:

Examples:

{"op": "set_orm_attribute", "args": {"object": "Product.price", "object_type": "field", "path": "precision", "value": "10"}}
{"op": "set_orm_attribute", "args": {"object": "price", "object_type": "field", "entity": "Product", "path": "scale", "value": "2"}}
{"op": "add_orm_attribute_item", "args": {"object": "Product", "path": "lifecycle-callbacks", "values": {"type": "prePersist", "method": "onPrePersist"}}}

Attribute Paths

Use attribute names without framework prefix. Write table not orm:table. Use / to separate nested paths (e.g. options/charset). The orm: prefix is auto-stripped if present, but should be avoided.

{"op": "set_orm_attribute", "args": {"object": "Product", "path": "table", "value": "app_products"}}
{"op": "set_orm_attribute", "args": {"object": "Product", "path": "options/charset", "value": "utf8mb4"}}

Name Resolution

Entity and module names accept short names (Customer, MainBundle) or fully qualified names (\Customer, \MainBundle). Short names are matched against LocalName.

Ambiguity: If two entities share the same short name in different modules (e.g. \App\Crm\Address and \App\EShop\Address), the short name Address matches the first one found. Use the fully qualified name to disambiguate.

Index and Association Referencing

update_index and remove_index use the index name (string), not a numeric ID. Example: {"op": "remove_index", "args": {"entity": "Customer", "index": "idx_email"}}

update_association, remove_association, update_many_to_many, and remove_many_to_many require a numeric id from -cli-schema-summary output. IDs are project-scoped auto-increment numbers.

Merge Input Format

The -cli-apply-merge verb accepts a JSON file with a project root key mirroring schema-summary structure. Only include objects you want to change — unmentioned objects are left as-is. Merge updates existing fields by name and adds new ones.

{
  "project": {
    "modules": [
      {
        "name": "MainBundle",
        "entities": [
          {
            "name": "Customer",
            "fields": [
              {"name": "email", "type": "string", "size": 320},
              {"name": "middleName", "type": "string", "size": 100, "nullable": true}
            ]
          }
        ]
      }
    ]
  }
}

Global Flags