Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kapso.ai/llms.txt

Use this file to discover all available pages before exploring further.

Use the Kapso CLI to bring workflows and functions into a local repository. You can edit the generated JSON directly, or use @kapso/workflows to build workflow definitions with JavaScript or TypeScript.

​
Start a local repo

mkdir kapso-workflows
cd kapso-workflows
npm init -y
npm install --save-dev @kapso/cli @kapso/workflows

npx kapso login
npx kapso link --project <project-id>
npx kapso pull
kapso link binds the current directory to one Kapso project. kapso pull downloads source files for workflows and functions.

​
Repository layout

After pulling, the repo includes a project binding, sync metadata, and one directory per source object. 
kapso.yaml
.kapso/project.json
.kapso/remote-map.json

functions/
  send-slack-message/
    function.yaml
    index.js

workflows/
  support-router/
    workflow.yaml
    definition.json
    workflow.js
You can commit the source files you want to version. The .kapso/remote-map.json file stores the last pulled remote state, so keep it in the repo when multiple people push changes.

​
Build with code

kapso pull creates a workflow.js file next to definition.json. Edit that file when you want code to become the source of truth for the workflow. You can also create workflow.ts manually if you prefer TypeScript. 
import { START, Workflow } from "@kapso/workflows";

const workflow = new Workflow("support-router", {
  name: "Support Router",
  status: "draft"
});

workflow.addTrigger({
  type: "inbound_message",
  phoneNumberId: "<phone-number-id>"
});

workflow.addNode(START, {
  position: { x: 100, y: 100 }
});

workflow.addNode("reply", {
  type: "send_text",
  message: "Thanks for reaching out. We will help you shortly."
});

workflow.addEdge(START, "reply");

export default workflow;
Build the workflow JSON before pushing: 
npx kapso build
If a pulled workflow.js file is unchanged, kapso push uses the existing workflow.yaml and definition.json files. Once you edit workflow.js or add workflow.ts, kapso push compiles that code before uploading.

​
Push changes

Preview changes before writing to Kapso: 
npx kapso push --dry-run
Push one workflow: 
npx kapso push workflow support-router
Push everything in the local repo: 
npx kapso push
Workflows and functions are matched by slug. If a remote object with the same slug exists but your repo does not have a pull baseline, run npx kapso pull first.

​
Build with AI

For AI-assisted edits, point your coding assistant at the workflow directory and ask it to edit workflow.js or workflow.ts. Keep the generated definition.json if you want to review diffs, or ignore it if your team prefers code as the source. Kapso docs are available to AI tools through the MCP endpoint: 
https://docs.kapso.ai/mcp

​
Sync behavior

The CLI protects local and remote work during sync:
  • kapso pull refuses to overwrite dirty local files.
  • kapso push checks the last pulled remote version before updating existing objects.
  • Remote-only workflows and functions are reported, not deleted.
  • Local-only workflows and functions are created on push.