Skip to main content

​
Overview

The Refrain SDK provides programmatic access to runbook execution from your TypeScript/JavaScript applications. It never reads process.env — all configuration is passed explicitly.

​
Install

npm install @refrainai/sdk

​
Quick start

import { Refrain, loadRunbook } from "@refrainai/sdk";

// 1. Create client
const client = new Refrain({
  ai: {
    modelId: "claude-sonnet-4-6",
    provider: "anthropic",
    apiKey: "sk-ant-...",
  },
  headless: true,
});

// 2. Load runbook
const runbook = await loadRunbook("./runbooks/login-flow.yaml");

// 3. Execute
const report = await client.execute(runbook, {
  contextMarkdown: "# Login Info\n- Use staging credentials",
  variables: { username: "[email protected]" },
  secrets: { password: "secret123" },
});

// 4. Check results
console.log(`${report.succeeded}/${report.totalSteps} steps succeeded`);

// 5. Cleanup
await client.dispose();

​
Key exports

ExportTypeDescription
RefrainclassMain client for local execution
loadRunbookfunctionLoad and parse a runbook YAML file

​
Design principles

  • Zero process.env — All configuration passed explicitly via constructor and method arguments
  • Non-interactive — No user prompts; unresolved required variables throw errors
  • Plan-aware — Features silently disabled if not available in your plan tier
  • Comprehensive diagnostics — Step results include retry counts, resolve methods, and failure categories

​
Next steps

Local Execution

Refrain class, configuration, and execution options.

Type Reference

All exported types organized by category.

Examples

Practical examples for common use cases.