Skip to content
ShipGate

Quick Start

This page is optional — your first ISL spec in a few minutes (not the Tier‑1 shipgate next path).

1. Install ShipGate

Terminal window
npm install -g @shipgate.dev/cli@3.0.0

If you’re building from source, you may have the CLI as isl; use isl instead of shipgate in the examples below.

2. Create a spec file

Create a file called user-service.isl:

domain UserService {
  version: "1.0.0"


  entity User {
    id: UUID [immutable, unique]
    email: Email [unique]
    name: String
    status: UserStatus
    created_at: Timestamp [immutable]


    invariants {
      email.is_valid
      name.length > 0
    }


    lifecycle {
      PENDING -> ACTIVE
      ACTIVE -> SUSPENDED
      SUSPENDED -> ACTIVE
    }
  }


  enum UserStatus {
    PENDING
    ACTIVE
    SUSPENDED
  }


  behavior CreateUser {
    description: "Register a new user account"


    input {
      email: Email
      name: String
    }


    output {
      success: User
      errors {
        DUPLICATE_EMAIL {
          when: "A user with this email already exists"
        }
        INVALID_INPUT {
          when: "Email or name is invalid"
        }
      }
    }


    preconditions {
      email.is_valid
      name.length > 0
      not User.exists(email)
    }


    postconditions {
      success implies {
        User.count == old(User.count) + 1
        result.email == email
        result.status == PENDING
      }
      failure implies {
        User.count == old(User.count)
      }
    }
  }
}

3. Parse and type-check

Terminal window
shipgate check user-service.isl

Expected output:

✓ Parsed successfully
✓ Type checking passed
✓ 1 domain, 1 entity, 1 behavior found

4. Generate TypeScript types

Terminal window
shipgate gen typescript user-service.isl -o ./src/generated

This produces TypeScript interfaces, Zod validators, and contract checkers from your spec.

5. Verify an implementation

If you have a TypeScript implementation:

Terminal window
shipgate verify user-service.isl --impl ./src/user-service.ts

Output:

Running verification...


CreateUser:
  ✓ Precondition: email.is_valid (passed)
  ✓ Precondition: name.length > 0 (passed)
  ✓ Precondition: not User.exists(email) (passed)
  ✓ Postcondition: User.count == old(User.count) + 1 (passed)
  ✓ Postcondition: result.email == email (passed)
  ✓ Postcondition: result.status == PENDING (passed)


Verdict: SHIP ✓  Trust Score: 100/100

6. Run the gate

The gate provides a definitive SHIP/NO_SHIP verdict for CI:

Terminal window
shipgate gate user-service.isl --impl ./src/user-service.ts
┌─────────────────────────────┐
│ Verdict: SHIP               │
│ Trust Score: 100/100        │
│ Confidence: 95%             │
│ Duration: 1.2s              │
└─────────────────────────────┘

Exit code 0 means SHIP. Exit code 1 means NO_SHIP. Use this in your CI pipeline.

What’s next?