Public API

PixlServer (from pixl-server)

import PixlServer = require('pixl-server');

const server = new PixlServer({
  __name: string;
  __version: string;
  configFile: string;
  components: any[];
});

server.startup(callback: () => void): void;

PixlServer is the core application container. Pass it a configuration object with a configFile path and an ordered array of component modules. Call startup() to boot all components in sequence. This is the exact pattern used in lib/main.js and should be your entry point if you are embedding or extending Cronicle.

Engine (lib/engine.js)

// Required as a PixlServer component
const CronicleEngine = require('./lib/engine.js');

// Registered on the PixlServer components array:
components: [
  require('pixl-server-storage'),
  require('pixl-server-web'),
  require('pixl-server-api'),
  require('pixl-server-user'),
  CronicleEngine
]

The engine is the central Cronicle component. It manages the scheduler loop, job dispatch, inter-server communication, and failover. It is not instantiated directly; PixlServer loads it as a component and calls its lifecycle hooks (startup, shutdown, etc.).

Storage CLI (bin/storage-cli.js)

// Invoked from the command line; not a programmatic API.
// Usage:
//   node bin/storage-cli.js list /jobs
//   node bin/storage-cli.js get /global/schedule
//   node bin/storage-cli.js put /global/schedule '{"items":[...]}'

storage-cli.js gives direct read/write access to the Cronicle storage backend from the shell. Use it to inspect or repair data, seed initial records in CI pipelines, or export snapshots. It reads the same conf/config.json as the main server.

Working examples

Scenario - Embedding Cronicle as a sidecar process

Your Express app needs to launch Cronicle in-process during integration tests or as a managed subprocess in development. The server is started the same way lib/main.js does it.

import { execSync, spawn } from 'child_process';
import path from 'path';

// Run setup once (idempotent after first run)
execSync('node bin/install.js', {
  cwd: path.resolve(__dirname, '../services/cronicle'),
  stdio: 'inherit',
});

const child = spawn('node', ['lib/main.js'], {
  cwd: path.resolve(__dirname, '../services/cronicle'),
  env: {
    ...process.env,
    CRONICLE_secret_key: process.env.CRONICLE_SECRET_KEY ?? 'dev-secret',
  },
  stdio: 'inherit',
});

child.on('exit', (code) => {
  console.log(`Cronicle exited with code ${code}`);
});

process.on('exit', () => child.kill());

Scenario - Triggering a job via the REST API

Cronicle exposes a JSON REST API. From your backend service, fire an event on demand using an API key.

import https from 'https';

interface CronicleRunEventResponse {
  code: number;
  description?: string;
  ids?: string[];
}

async function triggerCronicleEvent(
  baseUrl: string,
  apiKey: string,
  eventId: string
): Promise<CronicleRunEventResponse> {
  const url = `${baseUrl}/api/app/run_event/v1`;
  const body = JSON.stringify({ id: eventId });

  return new Promise((resolve, reject) => {
    const req = https.request(
      url,
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-API-Key': apiKey,
        },
      },
      (res) => {
        let data = '';
        res.on('data', (chunk) => (data += chunk));
        res.on('end', () => resolve(JSON.parse(data)));
      }
    );
    req.on('error', reject);
    req.write(body);
    req.end();
  });
}

// Usage
const result = await triggerCronicleEvent(
  'https://cronicle.example.com',
  process.env.CRONICLE_API_KEY!,
  'eXyZ1234abcd'
);
console.log(result);

Scenario - Writing a custom Plugin

Cronicle plugins communicate via JSON lines on stdin/stdout. Any language works; here is a Node.js plugin script you place in a path referenced by your event configuration.

// plugins/my-task.ts (compiled to JS and registered in Cronicle UI)
import * as readline from 'readline';

const rl = readline.createInterface({ input: process.stdin });

rl.on('line', (line) => {
  const params = JSON.parse(line);

  // params.event, params.job_id, params.params are available
  const myConfig = params.params as { target_url?: string };

  // Do your work here
  console.error(`Processing job ${params.job_id}`);

  // Report progress (0.0 - 1.0)
  process.stdout.write(JSON.stringify({ progress: 0.5 }) + '\n');

  // Final success response
  process.stdout.write(
    JSON.stringify({
      complete: 1,
      code: 0,
      description: 'Task completed successfully',
    }) + '\n'
  );
});

File walkthrough

• .github/ - CI/CD templates; not required at runtime.
• bin/build-tools.js, bin/build.js - Asset bundling tools for the front-end; run during development, not at runtime.
• bin/changelog.js - Parses CHANGELOG.md for release tooling.
• bin/control.sh - Shell wrapper for start, stop, restart, status operations using run-detached.js.
• bin/debug.sh - Starts the server in foreground with verbose logging.
• bin/install.js - One-time setup: initializes storage records, creates default admin user.
• bin/run-detached.js - Daemonizes the main server process.
• bin/shell-plugin.js - Built-in plugin that runs arbitrary shell commands as Cronicle jobs.
• bin/storage-cli.js - Interactive CLI for reading/writing the storage backend directly.
• bin/storage-migrate.js - Migrates storage data between backend adapters.
• bin/storage-repair.js - Repairs corrupted or inconsistent storage records.
• bin/test-plugin.js - Utility to test a plugin script outside the scheduler.
• bin/url-plugin.js - Built-in plugin that performs HTTP/HTTPS requests as jobs.
• docs/ - Authoritative documentation for all subsystems; read before customizing.
• htdocs/ - Static web assets for the browser UI; served by pixl-server-web.
• lib/api.js - Registers all REST API route handlers on the web server component.
• lib/api/ - Subdirectory with individual API endpoint modules.
• lib/comm.js - Inter-server communication layer (primary-to-worker messaging).
• lib/discovery.js - Automatic LAN-based server discovery via UDP broadcast.
• lib/engine.js - Core scheduler engine; the single PixlServer component that owns all Cronicle logic.
• sample_conf/ - Example config.json, log_columns.json, and other config files to seed a new deployment.

Common pitfalls and fixes

• Node.js version below 16: The server hard-exits. Fix: upgrade to Node 16+, or set CRONICLE_OLD=1 only for testing.
• Missing conf/config.json: The server crashes on startup with an unhelpful read error. Fix: copy sample_conf/ to conf/ before first run and populate required fields.
• secret_key left as default: Sessions signed with the sample key are insecure. Fix: always override via CRONICLE_secret_key environment variable or edit conf/config.json before deployment.
• Storage path permissions: Filesystem storage defaults to a path that may not be writable by your process user. Fix: set storage.base_dir in config to a directory owned by the runtime user.
• Port 3012 already in use: The web server fails silently or throws EADDRINUSE. Fix: change WebServer.http_port in conf/config.json and restart.
• CJS/ESM interop: All Cronicle source uses CommonJS require(). If your project uses "type": "module" in package.json, require Cronicle modules via createRequire or keep your wrapper files as .cjs. Do not attempt to import them directly.

Vibe-coding prompt template

I have a copy of the Cronicle multi-server task scheduler source in the `source/` directory of this project, and a USAGE.md file that describes its structure and APIs.

Please help me integrate Cronicle (upstream npm package: user@example.com) into my existing Node.js/TypeScript project by doing the following step by step:

1. Read USAGE.md and source/lib/main.js to understand how PixlServer is instantiated and started.
2. Create a wrapper module (e.g., services/cronicle.ts) that spawns or embeds Cronicle using the pattern from source/lib/main.js.
3. Wire in the configuration from source/sample_conf/ into a conf/ directory, substituting any secrets from environment variables using the CRONICLE_<key> convention.
4. Add a REST API client module that calls Cronicle's /api/app/* endpoints using the X-API-Key header.
5. Write a sample plugin in source/bin/ (following the shell-plugin.js pattern) that performs a task relevant to my application.
6. Make sure all imports use require() / CommonJS since Cronicle is not an ESM package.

Reference USAGE.md for all real export names and file paths. Do not invent APIs.

License and credit

Cronicle is released under the MIT License (see source/LICENSE.md). It was written by Joseph Huckaby. Upstream repository and package: https://www.npmjs.com/package/Cronicle / https://github.com/jhuckaby/Cronicle.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.