CLI

The runnel CLI talks to the same API as the dashboard. It ships with the TypeScript SDK as npx runnel, and as a standalone binary for Python and Go projects. Every command reads RUNNEL_API_KEY and RUNNEL_ENV when they are set, and falls back to the credentials stored by runnel login.

# macOS and Linux
brew install runnel/tap/runnel

# or with the TypeScript SDK
npm install @runnel/sdk
npx runnel --version

Global flags

Account and local development

runnel login

Opens your browser, asks you to approve the CLI and stores a token in ~/.config/runnel/credentials. On a server without a browser, pass --no-browser and paste the code it prints.

runnel dev

Starts a local Runnel server and your worker side by side, and restarts the worker when a file changes. The dashboard runs on http://localhost:8288. Runs, schedules and logs stay on your machine and nothing is sent to Runnel Cloud.

npx runnel dev
# ▸ Runnel dev server   http://localhost:8288
# ▸ Worker              src/worker.ts (3 jobs, 1 workflow, 1 schedule)
# ▸ Watching            src/**

Tip Use runnel dev --port 9000 if 8288 is taken, and --no-schedules to stop schedules firing while you work.

Deploying

runnel deploy

Reads your worker entry point, collects every job, workflow and schedule it registers, and uploads their definitions as a new version of the project. Workers you start afterwards pick up the new version; runs already in progress finish on the version they started with.

runnel deploy --env production
# ✓ Registered 4 jobs, 2 workflows, 3 schedules
# ✓ Version v42 is live in production

--dry-run prints the changes without applying them. See Deploying workers for running deploys from CI.

Working with runs

runnel runs list

Lists recent runs, newest first. Filter with --job, --status (queued, running, retrying, succeeded, failed, cancelled) and --limit (default 20, at most 100).

runnel runs list --job send-invoice --status failed --limit 5

runnel runs retry

Queues a failed or cancelled run again, with the same payload and run id. The attempt counter starts over. For workflows, --from-step <name> replays the run from that step: the steps before it keep their stored results and the steps from it onwards run again.

runnel runs retry run_01JB7X2K9Q4MZ8 --from-step charge-card

runnel runs cancel

Cancels a queued or running run. A running attempt receives a cancellation signal through ctx.signal and has 30 seconds to stop before the worker abandons it.

runnel logs

Prints the logs of a run, or of every run of a job with --job. --follow keeps streaming new lines, and --since 1h limits how far back it reads.

runnel logs run_01JB7X2K9Q4MZ8 --follow
runnel logs --job send-invoice --since 30m

Environments and keys

Warning runnel keys create prints the secret only once. Store it in your secret manager straight away; Runnel keeps only a hash.