Automate one useful operation

Choose the surface by who invokes the automation and how much supervision it needs. Use the CLI or SDK for direct reads and writes, a skill script for a procedure an agent should discover and invoke, and a workflow for a supervised program that coordinates multiple short agent calls.

These examples run inside a Cairn agent shell, terminal, or workflow environment, where connection details are supplied automatically.

Use the CLI for a shell operation

Use the cairn CLI when a shell script needs to read, write, or watch Cairn state and text output is enough.

cairn read "cairn://p/CAIRN/issues?limit=5"

This prints five issues and composes naturally with shell tools. cairn write accepts its change batch as JSON, and cairn watch follows an issue's attention stream. The CLI has no run subcommand; use an SDK run item when code must execute a command, skill script, external tool, or workflow.

Use The three verbs for address and payload reference rather than copying the runtime's exhaustive help into a script.

Use the SDK for direct operations in code

Use @cairn/sdk when TypeScript needs returned data, several operations, error handling, or a run target.

import { read } from "@cairn/sdk";

const issues = await read("cairn://p/CAIRN/issues?limit=5");
console.log(issues);

Inside an active Cairn environment the client resolves its connection without configuration. For repeated calls, construct new Cairn(). File writes require a commit message:

import { Cairn } from "@cairn/sdk";

const cairn = new Cairn();
await cairn.write(
  { target: "file:notes.md", mode: "create", payload: { content: "hello\n" } },
  "add notes",
);

Outside a running Cairn host, configure the client explicitly or expect a connection error. The CLI may be more convenient for local shell use because it can resolve and retry the local host.

Use a skill script for an agent-invoked procedure

Put a deterministic procedure in a skill's scripts/ directory when an agent should discover the instructions and then run the packaged implementation. This keeps the procedure beside the guidance that explains when and how to use it.

For example, Cairn's rapid-prototyping skill ships a scaffold script. An SDK caller invokes the actual packaged script as a run target:

import { run } from "@cairn/sdk";

await run({
  target: "cairn://skills/rapid-prototyping/scripts/scaffold.sh",
  payload: { args: ["5470", "src/index.css"] },
});

Skill script arguments are positional strings under payload.args. Use this surface for a bounded executable procedure, not for a long-running agent program.

Use a workflow for a supervised multi-call program

Use a workflow when TypeScript must fan out agent calls, run them in phases, combine structured results, or expose declared inputs and outputs. A workflow package contains workflow.yaml and main.ts, imports @cairn/harness, and appears as a supervised run that can be inspected and resumed.

The built-in Fan Out workflow applies one prompt to each item concurrently:

import { run } from "@cairn/sdk";

const result = await run({
  target: "cairn://workflows/fan-out",
  payload: {
    args_json: {
      prompt: "Summarize this item in one sentence: {item}",
      items: ["Cairn", "MCP"],
    },
  },
});

console.log(result);

Workflow arguments are named values under payload.args_json and are validated against the manifest. Calls with an output schema return validated structured data; calls without one return text content. Use a recipe instead when operators should launch and edit a visible sequence of issue agents and gates.

Decide quickly

For issue work, delegation, coordinators, and long-running topics, see Choose how to orchestrate work.