Your first Socotra project

Prerequisites

• .NET SDK 10.0 or later
• Internet connection (for NuGet packages and GitHub templates)

1. Install

dotnet tool install -g EssaLab.Socotra

Verify the installation:

socotra --version

2. Initialize a project

mkdir MyEcommerceApp
cd MyEcommerceApp
socotra init

socotra init generates a socotra.yaml using the modular-monolith template by default. Pick a different architecture with --template:

socotra init --template clean-architecture

3. Examine the config

version: "1.0"
solution:
  name: MyEcommerceApp
  architecture: modular-monolith
  modules:
    - name: MyEcommerceApp.Core
      layers:
        - Domain
        - Application
        - Infrastructure
        - Presentation
    - name: MyEcommerceApp.Shared
      layers:
        - Domain
        - Application

4. Validate

socotra validate

Schema version : 1.0
Solution name  : MyEcommerceApp
Module count   : 2
Configuration  : Valid

validate parses the YAML, verifies the schema version, checks for duplicate module names, and validates layer names — all without touching the filesystem.

5. Preview the plan

socotra plan

The plan output displays the solution file, projects, directories, and any existing state that will be preserved. No filesystem changes are made during planning.

6. Apply

socotra apply

You'll be prompted for confirmation before any writes occur. During execution, a progress bar shows creating the solution file, adding projects, and creating directories.

7. Check status

socotra status

Shows which parts of the configuration are Applied, Pending, or Drifted. For a complete pipeline comparison:

socotra status --full

8. Modify and re-apply

Add a new module to socotra.yaml:

modules:
  - name: MyEcommerceApp.Core
    layers: [Domain, Application, Infrastructure, Presentation]
  - name: MyEcommerceApp.Shared
    layers: [Domain, Application]
  - name: MyEcommerceApp.Reporting   # new module
    layers: [Domain, Infrastructure]

socotra plan
socotra apply

Socotra detects only the new module and creates it non-destructively — existing projects are untouched.

9. Use templates

Add a built-in DDD template to a module:

socotra template export base-entity

This copies the built-in template to .socotra/templates/base-entity/. Reference it in a layer's templates list, then run socotra apply.

To add a custom template from GitHub:

socotra template add github:user/templates/path