Installation

Runnel has an SDK for TypeScript, Python and Go, and a CLI that works with all three. Install the SDK in the project that defines your jobs. Install the CLI wherever you run runnel dev and runnel deploy, usually your laptop and your CI.

Requirements

All three SDKs follow the same version numbers as Runnel itself. This documentation describes 2.8.

Install the SDK

TypeScript

npm install @runnel/sdk
# or: pnpm add @runnel/sdk, yarn add @runnel/sdk, bun add @runnel/sdk

The package ships its own types and the CLI, so npx runnel --version works straight away. It is ESM and CommonJS.

Python

pip install runnel
# or: uv add runnel, poetry add runnel

The Python SDK is async-first and works with any asyncio application. Synchronous functions are run in a thread pool, so you can decorate them as well.

from runnel import Runnel, Retries

runnel = Runnel()

@runnel.job(name="send-welcome", retries=Retries(attempts=3))
async def send_welcome(payload: dict, ctx) -> dict:
    ctx.log.info("sending welcome email", email=payload["email"])
    return {"sent": True}

Go

go get github.example/runnel/runnel-go@v2.8.0

client := runnel.New() // reads RUNNEL_API_KEY

sendWelcome := runnel.NewJob("send-welcome",
	func(ctx runnel.Context, p Welcome) error {
		ctx.Log().Info("sending welcome email", "email", p.Email)
		return nil
	},
	runnel.WithRetries(3, runnel.Exponential),
)

The CLI

The TypeScript SDK includes the CLI. For Python and Go projects, or to have runnel on your path everywhere, install it on its own:

brew install runnel/tap/runnel
# Linux and Windows: curl -fsSL https://runnel.example/install.sh | sh
runnel --version
# runnel 2.8.0

Then sign in once per machine with runnel login. In CI, skip the login and set RUNNEL_API_KEY instead.

Environment variables

Note Under runnel dev none of these are needed: the SDK detects the local server and uses it.

Check the installation

runnel whoami
# Signed in as maya@example.com · project acme-billing · environment development

If that works, continue with the Quickstart or Defining jobs.