Installation

Prerequisites

• VSCode 1.75.0 or later
• Node.js 16+ (optional, for diagram server)

Install VSCode Extension

Option 1: VSCode Marketplace

1. Open VSCode
2. Press Ctrl+Shift+X (or Cmd+Shift+X on Mac) to open Extensions
3. Search for "Craft" or visit the marketplace page
4. Click Install

Option 2: Command Line

code --install-extension craft

Option 3: Manual Installation

1. Download the .vsix file from GitHub Releases
2. Open VSCode
3. Go to Extensions (Ctrl+Shift+X)
4. Click the ... menu → "Install from VSIX..."
5. Select the downloaded file

Verify Installation

1. Create a new file: test.craft
2. Type:

   use_case "Test" {
     when user does something
   }

3. You should see syntax highlighting

Install Diagram Server (Optional)

To generate diagrams, you need to run the Craft diagram server.

TIP

If you just want to write Craft code with syntax highlighting, you can skip this step.

Using Docker (Recommended)

Run the latest Craft server directly from Docker Hub — no build needed:

docker run --rm -p 8080:8080 tiagocarcao/craft:latest

The server will start on http://localhost:8080.

From Source

# Clone the repository
git clone https://github.com/tcarcao/craft.git
cd craft

# Generate ANTLR parser (pulls tiagocarcao/antlr4-craft:4.13.2 from Docker Hub automatically)
make generate-grammar

# Build and run the server container
make docker-build && make docker-run

The server will start on http://localhost:8080.

Configure Extension

Open VSCode settings (Ctrl+,) and search for "craft":

{
  "craft.server.url": "http://localhost:8080",
  "craft.server.timeout": 30000,
  "craft.logging.level": "warn"
}

Test Diagram Generation

1. Create a file example.craft
2. Add some content:

   services {
     UserService {
       contexts: Authentication
     }
   }

3. Press Ctrl+Shift+C to preview C4 diagram
4. If configured correctly, you'll see the generated diagram

WARNING

Make sure the diagram server is running before trying to preview diagrams.

Next Steps

• Quick Start Tutorial to write your first use case
• Extension Features to learn all the capabilities
• Examples to see complete applications