Reference · DML SDK/CLI

DML SDK & CLI

Embed DeepClause in a TypeScript service, or run compiled DML headless in CI. The SDK and CLI use the same runtime that powers the pi extension.

SDK on GitHub Standalone guide Decision models API reference

Install

DeepClause requires Node.js 18+.

npm install -g deepclause-sdk
deepclause init --model openai:gpt-4o
deepclause show-model

deepclause init creates .deepclause/config.json, the local tools directory, and the seeded system assets. Every command except init expects a .deepclause/ directory in the workspace. Use npx deepclause-sdk@latest for a one-off run.

CLI

Command	Effect
`deepclause init`	Initialize `.deepclause/` in the workspace
`deepclause set-model <model>`	Set the model for all slots, or one with `--slot`
`deepclause show-model`	Show the resolved `gateway`, `run`, `compile` slots
`deepclause compile <file.md>`	Compile a spec to DML (static analysis always; LLM audit by default)
`deepclause run <file.dml> [args]`	Execute a compiled DML program
`deepclause plan <file.md>`	Generate a standalone DML plan from a Markdown spec
`deepclause list-tools`	Show the resolved built-in and MCP tools

Useful run flags:

deepclause run skill.dml "input" \
    --model google:gemini-2.5-flash \
    --stream \
    --workspace ./data \
    --sandbox \
    --trace run.json

Embed in TypeScript

Supply a host-provided model backend with createDeepClause; no provider credentials are required when the host supplies the LLM.

import { createDeepClause, type LLMBackend } from "deepclause-sdk";

const llmBackend: LLMBackend = {
  async complete(request) {
    const response = await hostModel.complete({
      messages: request.messages,
      tools: request.tools,
      signal: request.signal,
    });
    return {
      text: response.text,
      toolCalls: response.toolCalls,
      usage: response.usage,
    };
  },
};

const deepclause = await createDeepClause({
  model: "host-active-model",
  llmBackend,
});

The backend receives messages, DML task tools, cancellation, token limits, and an optional onText callback. DML-defined tool predicates stay under a runtime tool whitelist, so an embedding exposes high-level DML tools without handing over the full runtime registry.

API reference → SDK examples →

Models and providers

Model choice is split into three slots: gateway (orchestration), run (skill execution), and compile (authoring).

deepclause set-model anthropic:claude-sonnet-4-20250514 --slot compile
deepclause set-model openrouter:google/gemini-2.5-flash --slot gateway

For local or self-hosted models, use an OpenAI-compatible custom: provider:

export LLM_PROVIDER_LOCAL_BASE_URL="http://localhost:11434/v1"
export LLM_PROVIDER_LOCAL_API_KEY="dummy"
deepclause set-model custom:local:qwen3-32b --slot run

Works with Ollama, vLLM, LM Studio, or any endpoint that speaks an OpenAI-style chat/completions API.

Runtime and sandboxing

WASM logic core. DML executes in a logic engine compiled to WebAssembly; the host is reachable only through explicit hooks.
Host shell by default. Shell tools run in the active workspace; shell.wrapper can force clean-room, bwrap, or sandbox-exec.
AgentVM on demand. --sandbox runs shell tools inside a dependency-free container VM, with network off by default.
Compile-time security. Static taint analysis flags untrusted data reaching the system prompt, dangerous tools, or task memory; an optional LLM audit reviews the program. Use --no-audit to skip only the LLM review.

Decision models → Handbook → DML → SpecKit → DML reference →