Examples

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

This page contains practical examples showing how to use the Skipper CLI for common tasks. Each example includes the command and its expected output. For the full verb and operation reference, see the CLI Reference.

Get Project Schema

Dump the entire project as a JSON summary. This is useful for inspecting entities, fields, associations, and modules programmatically.

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

Sample output (abbreviated):

{
  "status": "ok",
  "command": "schema-summary",
  "data": {
    "project": {
      "name": "MyApp",
      "orm": "Doctrine2",
      "modules": [
        {
          "name": "Default",
          "entities": [
            {
              "name": "User",
              "fields": [
                { "name": "id", "type": "integer", "primary": true },
                { "name": "email", "type": "string", "size": 255 }
              ],
              "associations": [ ... ]
            }
          ]
        }
      ]
    }
  },
  "warnings": [],
  "meta": { "duration_ms": 320, "skipper_version": "3.3.8.1844", "schema_version": "1.0", "started_at": "..." }
}

Validate a Project

Check your project for consistency issues such as missing primary keys, orphaned associations, or migration staleness.

Skipper.exe -cli-validate myproject.skipper

Sample output with warnings:

{
  "status": "ok",
  "command": "validate",
  "data": {
    "issues": [
      { "severity": "warning", "code": "MISSING_PRIMARY_KEY", "object": "Session", "message": "Entity 'Session' has no primary key field." },
      { "severity": "warning", "code": "UNUSED_ENTITY", "object": "TempLog", "message": "Entity 'TempLog' is not referenced by any association." }
    ],
    "summary": { "error_count": 0, "warning_count": 2 }
  },
  "warnings": [],
  "meta": { "duration_ms": 150, "skipper_version": "3.3.8.1844", "schema_version": "1.0", "started_at": "..." }
}

Add Entity with Fields

Create a patch file (ops.json) that adds a new entity and two fields, then apply it. The add_entity operation automatically creates an id primary key field from the framework template, so you only need to add non-PK fields.

Contents of ops.json:

[
  { "op": "add_entity", "args": { "module": "Default", "name": "Product" } },
  { "op": "add_field", "args": { "entity": "Product", "name": "name", "type": "string", "size": 255 } },
  { "op": "add_field", "args": { "entity": "Product", "name": "price", "type": "decimal" } }
]

Apply the patch:

Skipper.exe -cli-apply-patch myproject.skipper -patch ops.json -output myproject.skipper

Compare Two Projects

Diff two .skipper files to see what changed between versions. The comparison uses the migration diff engine.

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

Sample output:

{
  "status": "ok",
  "command": "compare",
  "data": {
    "summary": { "added": 2, "removed": 0, "modified": 1, "identical": 5 },
    "items": [
      { "action": "added", "type": "entity", "name": "Payment" },
      { "action": "added", "type": "field", "name": "Payment.amount" },
      { "action": "modified", "type": "entity", "name": "Order", "details": "Added field: total_price" }
    ],
    "input_new": "new.skipper",
    "input_old": "old.skipper"
  },
  "warnings": [],
  "meta": { "duration_ms": 280, "skipper_version": "3.3.8.1844", "schema_version": "1.0", "started_at": "..." }
}

Create Migration

Generate a new migration revision from pending schema changes. Migrations must be enabled in the project.

Skipper.exe -cli-create-migration myproject.skipper

If there are pending changes, the migration is created. If the schema is already up to date:

{
  "status": "ok",
  "command": "create-migration",
  "data": { "created": false, "reason": "no_changes_pending" },
  "warnings": [],
  "meta": { "duration_ms": 95, "skipper_version": "3.3.8.1844", "schema_version": "1.0", "started_at": "..." }
}

Import from Codebase

Scan an existing codebase directory to reverse-engineer a Skipper project from your source files.

Skipper.exe -cli-import-project ./src -output imported.skipper -orm Doctrine2 -mvc Symfony

Skipper scans the directory for entity definitions (annotations, attributes, XML mappings, YAML mappings) matching the chosen ORM framework and creates a .skipper file with all discovered entities, fields, and relationships.

List Available Frameworks

Query which ORM and MVC frameworks are available in your Skipper installation. This is useful for scripting project creation or validating framework names before use.

SkipperCli.exe -cli-list-frameworks

Expected output (abbreviated):

{
  "status": "ok",
  "command": "list-frameworks",
  "data": {
    "orm_frameworks": [
      { "name": "Doctrine2" },
      { "name": "Laravel" },
      { "name": "Propel2" },
      { "name": "CakePHP" }
    ],
    "mvc_frameworks": [
      { "name": "Symfony" },
      { "name": "Zend" },
      { "name": "Without MVC" }
    ]
  },
  "warnings": [],
  "meta": { "duration_ms": 50, "skipper_version": "3.3.8.1844", "schema_version": "1.0", "started_at": "..." }
}

Set ORM Attributes on Fields

Configure ORM-specific attributes on individual fields using set_orm_attribute. Fields are addressed with Entity.field dotted notation and object_type set to "field".

This example sets the precision and scale on a decimal field:

[
  { "op": "set_orm_attribute", "args": { "object": "Product.price", "object_type": "field", "path": "precision", "value": "10" } },
  { "op": "set_orm_attribute", "args": { "object": "Product.price", "object_type": "field", "path": "scale", "value": "2" } }
]

Skipper.exe -cli-apply-patch myproject.skipper -patch field-attrs.json -output myproject.skipper

Note: Use Entity.field dotted notation (e.g. Product.price) when targeting fields. For entity-level attributes, use just the entity name and "object_type": "entity".

Add Lifecycle Callbacks

Add ORM lifecycle callbacks to an entity using add_orm_attribute_item. Each callback specifies the event type and the method to invoke:

[
  { "op": "add_orm_attribute_item", "args": { "object": "Product", "path": "lifecycle-callbacks", "values": { "type": "prePersist", "method": "onPrePersist" } } },
  { "op": "add_orm_attribute_item", "args": { "object": "Product", "path": "lifecycle-callbacks", "values": { "type": "preUpdate", "method": "onPreUpdate" } } }
]

Skipper.exe -cli-apply-patch myproject.skipper -patch lifecycle.json -output myproject.skipper

Apply Merge with Nullable Fields

Use -cli-apply-merge to declaratively merge a desired state into an existing project. Fields are NOT NULL by default; set "nullable": true explicitly where needed:

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

SkipperCli.exe -cli-apply-merge project.skipper -merge state.json -output updated.skipper

The merge adds or updates the Customer entity and its fields. Existing entities not mentioned in the merge file are left untouched.

Reset Visual Layout

Reset all visual positions in the diagram so that the auto-arranger runs on the next GUI open. Useful after batch-adding many entities via CLI:

[
  { "op": "reset_layout", "args": {} }
]

Skipper.exe -cli-apply-patch myproject.skipper -patch reset.json -output myproject.skipper

After applying this patch, opening the project in the Skipper GUI will trigger the automatic layout engine to arrange all entities.

Tutorial: Build a Blog Schema

This tutorial walks through building a complete blog schema from scratch using the CLI. We will create a Doctrine2 project with four entities (User, Post, Tag, Comment), add relationships between them, configure indexes, set ORM attributes, validate, and export.

Step 1: Create the Project

Start by creating an empty Skipper project configured for Doctrine2:

Skipper.exe -cli-create-project -output blog.skipper -orm Doctrine2 -mvc "Without MVC" -name Blog

Step 2: Add Entities and Fields

Create a patch file (blog-entities.json) with all four entities and their fields:

Note: The add_entity operation automatically creates an id integer primary key field (auto-increment) from the framework template. The explicit add_field calls for id below are shown for clarity, but in practice you can omit them — adding a PK field manually when one is already auto-created will result in a duplicate field (e.g. id + id2).

[
  { "op": "add_entity", "args": { "module": "Default", "name": "User" } },
  { "op": "add_field", "args": { "entity": "User", "name": "email", "type": "string", "size": 255, "unique": true } },
  { "op": "add_field", "args": { "entity": "User", "name": "username", "type": "string", "size": 100 } },
  { "op": "add_field", "args": { "entity": "User", "name": "created_at", "type": "datetime" } },

  { "op": "add_entity", "args": { "module": "Default", "name": "Post" } },
  { "op": "add_field", "args": { "entity": "Post", "name": "title", "type": "string", "size": 255 } },
  { "op": "add_field", "args": { "entity": "Post", "name": "body", "type": "text" } },
  { "op": "add_field", "args": { "entity": "Post", "name": "published_at", "type": "datetime" } },

  { "op": "add_entity", "args": { "module": "Default", "name": "Tag" } },
  { "op": "add_field", "args": { "entity": "Tag", "name": "label", "type": "string", "size": 50 } },

  { "op": "add_entity", "args": { "module": "Default", "name": "Comment" } },
  { "op": "add_field", "args": { "entity": "Comment", "name": "content", "type": "text" } },
  { "op": "add_field", "args": { "entity": "Comment", "name": "created_at", "type": "datetime" } }
]

Apply the patch:

Skipper.exe -cli-apply-patch blog.skipper -patch blog-entities.json -output blog.skipper

Step 3: Add Relationships

Create a second patch file (blog-relations.json) to wire the entities together with associations and a many-to-many relationship:

[
  { "op": "add_association", "args": { "from": "User", "to": "Post", "owner_alias": "posts", "inverse_alias": "author" } },
  { "op": "add_association", "args": { "from": "Post", "to": "Comment", "owner_alias": "comments", "inverse_alias": "post" } },
  { "op": "add_many_to_many", "args": { "owner": "Post", "inverse": "Tag", "mn_entity": "PostTag", "owner_alias": "tags", "inverse_alias": "posts" } }
]

Apply:

Skipper.exe -cli-apply-patch blog.skipper -patch blog-relations.json -output blog.skipper

Step 4: Add Indexes

Add a unique index on User email and a regular index on Post published_at for query performance:

[
  { "op": "add_index", "args": { "entity": "User", "name": "idx_user_email", "unique": true, "fields": ["email"] } },
  { "op": "add_index", "args": { "entity": "Post", "name": "idx_post_published", "fields": ["published_at"] } }
]

Skipper.exe -cli-apply-patch blog.skipper -patch blog-indexes.json -output blog.skipper

Step 5: Set ORM Attributes

Configure Doctrine2 table names for each entity using set_orm_attribute:

[
  { "op": "set_orm_attribute", "args": { "object": "User", "object_type": "entity", "path": "table", "value": "app_users" } },
  { "op": "set_orm_attribute", "args": { "object": "Post", "object_type": "entity", "path": "table", "value": "app_posts" } },
  { "op": "set_orm_attribute", "args": { "object": "Tag", "object_type": "entity", "path": "table", "value": "app_tags" } },
  { "op": "set_orm_attribute", "args": { "object": "Comment", "object_type": "entity", "path": "table", "value": "app_comments" } }
]

Skipper.exe -cli-apply-patch blog.skipper -patch blog-attributes.json -output blog.skipper

Step 6: Validate

Run validation to ensure the project is consistent:

Skipper.exe -cli-validate blog.skipper

Expected output with no issues:

{
  "status": "ok",
  "command": "validate",
  "data": {
    "issues": [],
    "summary": { "error_count": 0, "warning_count": 0 }
  },
  "warnings": [],
  "meta": { "duration_ms": 120, "skipper_version": "3.3.8.1844", "schema_version": "1.0", "started_at": "..." }
}

Step 7: Export

Export the project to generate Doctrine2 entity classes and mappings:

Skipper.exe -cli-export blog.skipper

Sample output:

{
  "status": "ok",
  "command": "export",
  "data": {
    "files_written": [
      { "path": "src/Entity/User.php", "bytes": 1842 },
      { "path": "src/Entity/Post.php", "bytes": 2105 },
      { "path": "src/Entity/Tag.php", "bytes": 1024 },
      { "path": "src/Entity/Comment.php", "bytes": 1356 },
      { "path": "src/Entity/PostTag.php", "bytes": 890 }
    ],
    "framework": "Doctrine2",
    "output_dir": "src/"
  },
  "warnings": [],
  "meta": { "duration_ms": 450, "skipper_version": "3.3.8.1844", "schema_version": "1.0", "started_at": "..." }
}

Your blog schema is now complete. You can open blog.skipper in the Skipper GUI to visualize the diagram, or continue building on it with additional CLI patch operations.