Skip to content
Cronlet Docs

Cloud Quickstart

This guide covers a minimal Cronlet Cloud integration.

This guide shows how to:

  • install @cronlet/sdk
  • create a hosted task
  • trigger it manually
  • inspect the resulting run
  • understand the minimum shape needed for production integrations

Prerequisites

  • Node.js >=18
  • a Cronlet Cloud API key from the web app settings page
  • a server-side environment where you can keep the API key private

Install

Terminal window
npm install @cronlet/sdk

Set environment variables

Terminal window
export CRONLET_API_KEY=your_api_key_here
# Optional for self-hosting or non-production environments
export CRONLET_BASE_URL=https://api.cronlet.dev

Create a client

import { CloudClient } from "@cronlet/sdk";


export const cronlet = new CloudClient({
  apiKey: process.env.CRONLET_API_KEY!,
  baseUrl: process.env.CRONLET_BASE_URL,
});

Create your first task

tasks.create() accepts either a schedule object or a supported schedule string. Use a webhook handler for the simplest first integration:

import { cronlet } from "./cronlet";


const task = await cronlet.tasks.create({
  name: "API health check",
  description: "Ping the production health endpoint every 5 minutes",
  handler: {
    type: "webhook",
    url: "https://api.example.com/health",
    method: "GET",
  },
  schedule: "every 5 minutes",
  timezone: "UTC",
  retryAttempts: 2,
  retryBackoff: "linear",
  retryDelay: "5s",
  timeout: "30s",
  active: true,
  metadata: {
    environment: "production",
    owner: "platform",
  },
});


console.log(task.id);

Trigger the task manually

const run = await cronlet.tasks.trigger(task.id);
console.log(run.id, run.status);

Read the run result

const latestRun = await cronlet.runs.get(run.id);


console.log({
  status: latestRun.status,
  durationMs: latestRun.durationMs,
  output: latestRun.output,
  errorMessage: latestRun.errorMessage,
});

Create a tools-based task

Use tools handlers when you need hosted multi-step execution without exposing your own endpoint as the handler:

const task = await cronlet.tasks.create({
  name: "Weekly digest to Slack",
  handler: {
    type: "tools",
    steps: [
      {
        tool: "http.get",
        args: {
          url: "https://api.example.com/reports/weekly-summary",
        },
        outputKey: "summary",
      },
      {
        tool: "slack.post",
        args: {
          channel: "#ops",
          text: "Weekly digest: {{summary.body}}",
          secretName: "SLACK_TOKEN",
        },
      },
    ],
  },
  schedule: {
    type: "weekly",
    days: ["mon"],
    time: "09:00",
  },
  timezone: "America/New_York",
  retryAttempts: 1,
  retryBackoff: "linear",
  retryDelay: "1s",
  timeout: "30s",
  active: true,
});

Production checklist

Before using this in an application or agent workflow:

  • keep the API key server-side only
  • store task.id in your database
  • attach stable ownership metadata (userId, orgId, internal record IDs)
  • set a callbackUrl if your app needs to react to completed runs
  • use maxRuns or expiresAt when the schedule should self-terminate
  • name tasks clearly so the Cronlet dashboard remains understandable

Supported string schedules

The SDK accepts a constrained schedule grammar. Supported examples include:

schedule: "daily at 9am"
schedule: "weekdays at 5pm"
schedule: "every friday at 9am"
schedule: "monthly on the last friday at 9am"
schedule: "once at 2026-03-15 09:00"

You can still pass structured objects:

schedule: { type: "daily", times: ["09:00"] }

Next steps