@boundaryboard/cli

CLI tool to render and edit BoundaryBoard DSL files locally.

Installation

npm install -g @boundaryboard/cli

Or use directly with npx:

npx boundaryboard-render your-file.dsl

Usage

Basic Usage

Render a DSL file in your browser:

npx boundaryboard-render domain-model.dsl

This will:

• Parse your DSL file
• Start a local development server (default port: 3456)
• Open your browser automatically
• Display your diagram with full editing capabilities
• Auto-save changes back to the file

Options

npx boundaryboard-render <file> [options]

Options:
  -p, --port <port>     Port to run the server on (default: 3456)
  --no-open            Do not open the browser automatically
  --no-watch           Disable file watching (won't reload on external changes)
  --read-only          Open in read-only mode (no editing)
  -V, --version        Output the version number
  -h, --help           Display help for command

Examples

Read-only mode:

npx boundaryboard-render diagram.dsl --read-only

Custom port:

npx boundaryboard-render diagram.dsl --port 8080

No auto-open browser:

npx boundaryboard-render diagram.dsl --no-open

Disable file watching:

npx boundaryboard-render diagram.dsl --no-watch

Supported DSL Types

The CLI automatically detects the DSL type based on content:

1. Domain Model DSL (Tactical DDD)

context OrderManagement {
  aggregate Order {
    entity OrderRoot {
      id: OrderId
      customer: CustomerId
      items: OrderItem[]
      status: OrderStatus
    }
  }

  valueObject OrderItem {
    productId: ProductId
    quantity: int
    price: decimal
  }
}

Order -> Customer { label: "belongs to" }

2. C4 Model DSL (Architecture)

person Customer {
  description: "A customer of the system"
}

system OrderSystem {
  description: "Handles order processing"
  technology: "Java, Spring Boot"
}

Customer -> OrderSystem {
  description: "Places orders using"
}

3. Context Map DSL (Strategic DDD)

subdomain OrderManagement {
  type: core
}

subdomain Shipping {
  type: supporting
}

OrderManagement -> Shipping {
  relationship: customer_supplier
  downstream: Shipping
}

Features

• Auto-detection: Automatically detects DSL type
• Live editing: Edit nodes, edges, and properties visually
• Auto-save: Changes are automatically saved back to the DSL file (debounced)
• Hot reload: File changes from external editors are detected and reloaded
• Layout preservation: Uses @layout annotations to preserve visual layout
• Read-only mode: View-only mode for presentations or reviews
• Bidirectional sync: Visual changes sync back to DSL with proper formatting

How It Works

1. Parse: The DSL file is parsed using the BoundaryBoard DSL parsers
2. Layout: Elements are auto-layouted or use existing @layout annotations
3. Render: React Flow canvas displays the diagram with sketchy visual style
4. Edit: Make changes visually (drag nodes, edit text, add/remove elements)
5. Save: Changes are converted back to DSL and saved to the file

Layout Annotations

The CLI preserves your visual layout using @layout annotations in the DSL:

entity Order {
  description: "Main order entity"
  attributes { id: string, total: decimal }
  @layout {
    id: "uuid-123"
    position: (150, 200)
    size: (200, 150)
    color: "#10b981"
  }
}

Order -> Customer {
  label: "belongs to"
  @edge {
    id: "uuid-456"
    lineStyle: dashed
    pathType: bezier
    arrowDirection: target
    waypoints: [(100, 100), (150, 150)]
  }
}

These annotations are automatically added when you edit visually and ensure your layout persists across sessions.

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Test locally
npm link
boundaryboard-render test-file.dsl

License

MIT