One typed client. The whole platform.

Install with your package manager of choice. The client reads its token from a { token } option or the TRICKEST_TOKEN environment variable; with neither set, the constructor throws immediately rather than failing on first call.

import { TrickestClient } from "@trickest/sdk"

const client = new TrickestClient() // reads TRICKEST_TOKEN

// List spaces — async iteration paginates for you.
for await (const space of client.spaces.list()) {
  console.log(space.name, space.id)
}

// Create then execute a workflow.
const workflow = await client.workflows.create(spaceId, {
  name: "My Workflow",
})

const run = await client.runs.execute(workflow.id, {
  inputs: { domain: "example.com" },
})

npm install @trickest/sdk · bun add @trickest/sdk · Node.js ≥ 22

The client authenticates via the Authorization header and picks the scheme automatically: a personal API token goes out as Token <token>, while a JWT (it contains a .) goes out as Bearer <token>. Point at a different deployment with baseUrl or TRICKEST_BASE_URL.

// 1 — pass a token directly
const client = new TrickestClient({ token: "your-token" })

// 2 — read TRICKEST_TOKEN from the environment
const client = new TrickestClient()

// 3 — target a custom deployment
const client = new TrickestClient({
  token: "your-token",
  baseUrl: "https://trickest.io", // the default
})

The client instantiates each service the first time you touch its getter; every service extends BaseService, which provides auto-pagination, single-page fetching, and CRUD helpers. Authentication stays internal, so there is no auth namespace to call.

• client.spaces
• client.projects
• client.workflows
• client.library
• client.fleet
• client.database
• client.users
• client.billing
• client.schedules
• client.runs
• client.storage
• client.variables
• client.secretVariables
• client.audit
• client.notifications
• client.sessions
• client.solutions
• client.memory
• client.skills
• client.integrations
• client.sandbox

Every list method returns an AsyncGenerator that transparently fetches pages with page and page_size (default 500). Drop to listPage when you need a single page with cursor and count.

// Auto-paginate every workflow in a space.
for await (const workflow of client.workflows.list(spaceId)) {
  console.log(workflow.name)
}

// Control the page size.
for await (const run of client.runs.list(workflowId, { pageSize: 50 })) {
  // ...
}

// Low-level: one page with { results, next, count }.
import { listPage } from "@trickest/sdk"
const page = await listPage(client.http, "/v1/spaces/", { pageSize: 10 })

Agent turns do not stream over HTTP. sessions.handle() opens a long-lived handle bound to one session: it fetches the canonical projection, then (with realtime: true) subscribes over WebSocket so invalidation frames trigger coalesced refetches and per-character deltas. For headless callers, runTurn dispatches a turn and resolves once the projection seals.

import { TrickestClient, runTurn } from "@trickest/sdk"

const client = new TrickestClient()
const session = await client.sessions.create(vaultId, "Recon Session")
const handle = await client.sessions.handle(session.id, vaultId, {
  realtime: true,
})

try {
  const turn = await runTurn(handle, {
    prompt: "Build a recon workflow for example.com",
    autoApprove: true,
  })
  console.log(turn.answer)               // concatenated text blocks
  console.log(turn.toolCalls.length)     // [{ name, args, status, result? }]
  console.log(turn.phase)                // completed | failed | aborted
} finally {
  handle.close()
}

UI consumers subscribe() for canonical state and subscribeStreaming() for live deltas · dispatch() is the fire-and-forget escape hatch

Every failure throws a class that extends TrickestError and carries status, code, and requestId (aliased traceId). Branch on the instanceof class first, then narrow on the server code for sub-types of the same status.

The SDK retries with exponential backoff (3 attempts, 1s base): 429 always honors Retry-After (capped at 60s); 5xx, network, and timeout failures retry on idempotent methods, or on POST/PATCH carrying an idempotencyKey. Other 4xx throw immediately.

Every service method takes a trailing RequestOptions object, so timeouts, cancellation, retry policy, headers, idempotency, auth, and response validation are all controllable at the call site.

• timeoutRequest timeout in ms (default 30000; 300000 for stream). Timer is cleaned up across retries.
• signalAbortSignal for cancellation, combined with the timeout. Caller-abort is distinguishable from TimeoutError.
• retryOverride retry per call — false to disable, or { maxRetries, baseDelay }.
• headersExtra request headers; caller keys override SDK defaults.
• idempotencyKeySent as Idempotency-Key; makes POST/PATCH eligible for 5xx and network retries.
• tokenPer-call auth token override (e.g. impersonation).
• schemaOptional Zod schema to parse + validate the response before returning.

const space = await client.spaces.get(id, {
  timeout: 5000,
  signal: controller.signal,
  retry: false,
})

// Idempotency-key-aware POST — retried on 5xx / network / timeout.
await client.database.insertRow(
  tableId,
  { host: "example.com", port: 443 },
  { idempotencyKey: `scan:${runId}:${rowHash}` },
)

The SDK is the typed surface. The CLI gives it a terminal shape, MCP exposes it as tools to coding agents, and skills package the repeatable playbooks. Configure it once and use the same Trickest workflows from your editor, your terminal, or an agent runtime.

Claude CodeCursorCXCodex

CLISDKMCP