Getting started

Your first Socotra project

A five-minute walkthrough from install to a running .NET solution.

Prerequisites

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

1. Install

dotnet tool install -g EssaLab.Socotra

Installing a prerelease build

If the latest Socotra release is a beta or other prerelease, the .NET CLI will not install it by default. Pass --prerelease to opt in:

dotnet tool install --global EssaLab.Socotra --prerelease

The --prerelease flag is required for preview, beta, RC, and any other prerelease builds.

Verify the installation:

socotra --version

2. Initialize a project

mkdir MyEcommerceApp
cd MyEcommerceApp
socotra init

socotra init generates a socotra.yaml using the empty template by default — a minimal file containing only the schema version. Pick a pre-built architecture with --template:

socotra init --template modular-monolith
socotra init --template clean-architecture

3. Examine the config

The default empty output is intentionally tiny — just a schema annotation and the version key, so editors with the YAML Language Server give you IntelliSense from the first keystroke:

socotra.yaml (empty template)

# yaml-language-server: $schema=https://essalab.github.io/Socotra.Schemas/schemas/v1/schema.json
socotra:
  version: "1.0"

Choosing --template modular-monolith produces a fuller starter that you can edit in place:

socotra.yaml (modular-monolith)

# yaml-language-server: $schema=https://essalab.github.io/Socotra.Schemas/schemas/v1/schema.json
socotra:
  version: "1.0"
  solution:
    name: MyEcommerceApp
    dotnetVersion: "net9.0"
  architecture:
    pattern: modular-monolith
  modules:
    - name: MyEcommerceApp.Core
      layers:
        - name: Domain
          type: ClassLib
        - name: Application
          type: ClassLib
        - name: Infrastructure
          type: ClassLib
        - name: Api
          type: WebApi
  shared:
    - name: SharedKernel
      type: ClassLib

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.

Automatic rollback

If an error occurs, Socotra rolls back all changes, leaving your directory in its original state.

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

Schema 1.0 · CLI 1.0

PreviousWhat is Socotra?Next State-driven workflow