Getting Started

Let's build your first Culvii workflow. We'll install the SDK, write a simple "Hello World" workflow, and run it.

1. Configure npm

First, tell npm where to find the Culvii package. Create an .npmrc file in your project root and add the Culvii registry.

@culvii:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}

Make sure your NODE_AUTH_TOKEN environment variable has access to the Culvii package.

2. Install the SDK

Install @culvii/kit using your preferred package manager.

pnpm add @culvii/kit

3. Write a Hello World workflow

A workflow is a sequence of steps. Let's create a simple workflow that takes a name and returns a greeting.

Create a file named hello.ts and add this code:

import { Workflow, Step } from '@culvii/kit';

const triggerStep = new Step({
  id: 'trigger',
  name: 'Manual Trigger',
  type: 'manualTrigger'
});

const greetStep = new Step({
  id: 'greet',
  name: 'Generate Greeting',
  type: 'core.set',
  params: {
    values: {
      message: 'Hello, World!'
    }
  }
});

triggerStep.connectTo(greetStep);

export const helloWorkflow = new Workflow({
  id: 'hello-world',
  name: 'Hello World Workflow',
  steps: [triggerStep, greetStep]
});

This code defines a trigger step and an action step that sets a greeting message. Then it connects them and wraps them in a workflow. Every workflow needs a stable id — this is the slug the platform uses to track and version your workflow across deploys.

4. Deploy the workflow

The SDK doesn't deploy workflows itself. Instead, you author your workflow in a file the Culvii CLI can discover, then deploy it with culvii deploy.

Save your file with a .culvii.ts extension (for example hello.culvii.ts) so the CLI picks it up automatically, or list it under entrypoints: in a culvii.yaml at your project root. The CLI evaluates each entrypoint, collects the Workflow (and agent) definitions it constructs, and sends them to the platform.

# Deploy every discovered definition to a workspace
culvii deploy --env sandbox --workspace my-workspace

culvii deploy plans the change, shows you what will be created or versioned, and applies it once you confirm. For local iteration, use culvii dev instead, which watches your files and syncs them to your dev environment as you edit.

That's it. You just built and deployed your first Culvii workflow. Next, let's look at the core concepts to understand how everything fits together.