Captain

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

Quick Start

# Install from npm
npm install -g captain

TypeScript/JavaScript Tasks

Create a TypeScript task:

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

Create a task configuration:

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

Run Captain:

captain ./tasks.yaml

Shell Commands

Create a task configuration with shell commands:

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

Run Captain:

captain ./tasks.yaml

Installation

# Global installation (recommended for CLI usage)
npm install -g captain

# Local installation (for project usage)
npm install --save captain

Usage Guide

1. Create TypeScript Tasks

Create TypeScript files for your scheduled tasks:

// 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}`);

2. Configure Tasks with YAML

Create a YAML configuration file defining your tasks:

# 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. Run Captain

# 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:

# Clone the repository
git clone <repository-url>
cd captain

# Install dependencies 
npm install

# Run in development mode
npm run dev

# Run tests
npm test

License

ISC