Captain

A lightweight, easy-to-use task scheduler for running TypeScript files and shell commands with cron expressions.

Quick Start

``bash


Install from npm


npm install -g captain
`

$3

Create a TypeScript task:

`typescript
// task.ts
console.log("Task running at:", new Date());
`

Create a task configuration:

`yaml


tasks.yaml


tasks:
simple:
description: "A simple job that runs every minute"
schedule: " *"
file: "./task.ts"
`

Run Captain:

`bash
captain ./tasks.yaml
`

$3

Create a task configuration with shell commands:

`yaml


tasks.yaml


tasks:
health_check:
description: "Check API health every minute"
schedule: " *"
command: "curl -s https://httpbin.org/get"
`

Run Captain:

`bash
captain ./tasks.yaml
`

Installation

`bash


Global installation (recommended for CLI usage)

npm install -g captain

Local installation (for project usage)

npm install --save captain
`

Usage Guide

$3

Create TypeScript files for your scheduled tasks:

`typescript
// tasks/log-metrics.ts
import fs from 'fs';

// Access environment variables from YAML config
const logPath = process.env.LOG_PATH || './metrics.log';

// Log system metrics
const metrics = {
timestamp: new Date().toISOString(),
memoryUsage: process.memoryUsage(),
uptime: process.uptime()
};

// Append to log file
fs.appendFileSync(logPath, JSON.stringify(metrics) + '\n');
console.log(Metrics logged to ${logPath});
`

$3

Create a YAML configuration file defining your tasks:

`yaml


scheduler.yaml

tasks:
metrics_logger:
description: "Log system metrics every 15 minutes"
schedule: "/15 *"
file: "./tasks/log-metrics.ts"
timeout: 30 # seconds
env:
LOG_PATH: "./logs/system-metrics.log"

cleanup_task:
description: "Clean up temp files daily at midnight"
schedule: "0 0 *"
file: "./tasks/cleanup.ts"
concurrency:
max: 1
allow_overlap: false

# Shell command example
health_check:
description: "Check API health every 5 minutes"
schedule: "/5 *"
command: "curl -s https://api.example.com/health"
timeout: 10

backup:
description: "Run backup script daily"
schedule: "0 2 *"
command: "./scripts/backup.sh"

config:
default_timeout: 60
log_level: "info"
`

$3

`bash


Start the scheduler

captain ./scheduler.yaml

List all configured tasks

captain ./scheduler.yaml --list

Run a specific task immediately

captain ./scheduler.yaml --run metrics_logger

Combine multiple configuration files

captain ./system-tasks.yaml ./app-tasks.yaml
`

Task Configuration Reference

Each task supports the following options:

| Option | Type | Required | Description |
|--------|------|----------|-------------|
| description | string | No | Human-readable description of the task |
| schedule | string | Yes | Cron expression (e.g. "/5 *") |
| file | string | No* | Path to TypeScript file to execute |
| command | string | No* | Shell command to execute (uses $SHELL or /bin/sh) |
| timeout | number | No | Maximum runtime in seconds before termination |
| concurrency | object | No | Concurrency settings |
| concurrency.max | number | No | Maximum instances (default: 1) |
| concurrency.allow_overlap | boolean | No | Allow task to overlap itself (default: false) |
| env | object | No | Environment variables to pass to task |
| retry | object | No | Retry settings for failed tasks |
| retry.attempts | number | No | Number of retry attempts |
| retry.backoff | string | No | Backoff strategy ("fixed" or "exponential") |
| retry.delay | number | No | Delay in seconds between retries |

\* Either file or command is required, but not both.

Common Use Cases

- Recurring database maintenance: Schedule database cleanup, backups, or migrations
- Application monitoring: Log metrics, check service health, or generate reports
- Data processing: Schedule batch processing of data at regular intervals
- Service coordination: Trigger API calls or service interactions on a schedule

Developing with Captain

For developers who want to modify or extend Captain:

`bash


Clone the repository

git clone
cd captain

Install dependencies

npm install

Run in development mode

npm run dev

Run tests

npm test
``

License

ISC