CLI Reference

cronbase start

Start the scheduler and web dashboard.

cronbase start [--port 7433] [--db ./cronbase.db] [--config cronbase.yaml]

Flag	Default	Description
--port	7433	Port for the web dashboard and REST API
--db	./cronbase.db	Path to the SQLite database
--config	—	YAML or JSON config file to load on startup
--prune-days	90	Delete execution history older than N days on startup (0 to disable)

The scheduler polls every second for due jobs and executes them. The web dashboard is served on the same port.

Stops gracefully on SIGINT (Ctrl+C) or SIGTERM.

cronbase add

Add a new cron job.

cronbase add --name <name> --schedule <cron> --command <cmd> [options]

Flag	Required	Default	Description
--name	Yes	—	Unique job name
--schedule	Yes	—	Cron expression or preset (@daily, @hourly, etc.)
--command	Yes	—	Shell command to execute (passed to sh -c)
--cwd	No	.	Working directory
--timeout	No	No limit	Kill after N seconds
--retries	No	0	Max retry attempts on failure
--retry-delay	No	30	Base delay (seconds) for exponential backoff
--description	No	—	Human-readable description
--disabled	No	false	Create in disabled state

Example:

cronbase add \
  --name "backup-db" \
  --schedule "0 2 * * *" \
  --command "pg_dump mydb > /backups/db.sql" \
  --timeout 300 \
  --retries 2 \
  --description "Nightly database backup"

cronbase edit

Update an existing job's properties without removing and re-adding it. Only the flags you specify are changed — everything else stays the same. Execution history is preserved.

cronbase edit <name> [options]

Flag	Description
--schedule	New cron expression or preset
--command	New shell command
--cwd	New working directory
--timeout	New timeout in seconds (0 to remove)
--retries	New max retry count
--retry-delay	New backoff base delay in seconds
--description	New description
--timezone	New IANA timezone
--enabled	Enable the job
--disabled	Disable the job

Examples:

# Change a job's schedule
cronbase edit backup-db --schedule "0 3 * * *"

# Update the command and increase timeout
cronbase edit health-check --command "curl -sf https://myapp.com/ready" --timeout 60

# Disable a job temporarily
cronbase edit cleanup-logs --disabled

cronbase show

Show full details of a single job — schedule, command, next/last run, timeout, retries, tags, and environment variables.

cronbase show <name>

Example output:

$ cronbase show backup-db
Job: backup-db
Description: Nightly database backup
Enabled: yes

Schedule: 0 2 * * * (At 02:00)
Command: pg_dump mydb > /backups/db-$(date +%Y%m%d).sql
Working dir: .

Next run: 3/30/2026, 2:00:00 AM
Last run: 3/29/2026, 2:00:05 AM
Last status: ✓ success

Timeout: 300s
Retries: 2 (delay: 60s)
Tags: database, production

Created: 3/15/2026, 9:30:00 AM

Supports --json for machine-readable output.

cronbase list

List all jobs with their current status.

cronbase list

Output columns: Name, Schedule, Status (last execution), Last Run, Next Run.

cronbase history

Show execution history.

cronbase history [--job <name>] [--limit 20]

Flag	Default	Description
--job	—	Filter by job name
--limit	20	Maximum number of entries

cronbase logs

Show stdout/stderr output from a job's recent executions.

cronbase logs <name> [--limit 1]

Flag	Default	Description
--limit	1	Number of recent executions to show

By default shows the most recent execution. Use --limit 5 to see the last 5 runs. Useful for quickly checking why a job failed without opening the dashboard.

# Check the latest output from backup-db
cronbase logs backup-db

# Show the last 3 runs
cronbase logs backup-db --limit 3

# Machine-readable output
cronbase logs backup-db --json

cronbase run

Manually trigger a job and wait for completion.

cronbase run <name>

Shows stdout/stderr output and exits with the job's exit code (0 for success, 1 for failure).

cronbase remove

Delete a job and its execution history.

cronbase remove <name>

cronbase enable

Enable a disabled job so it runs on schedule.

cronbase enable <name>

cronbase disable

Disable a job without deleting it. Disabled jobs don't execute on schedule but can still be triggered manually with cronbase run.

cronbase disable <name>

cronbase pause

Pause all scheduled job execution. Jobs will not run until resumed. Useful for maintenance windows.

cronbase pause [--until <datetime>]

Flag	Required	Default	Description
--until	No	Indefinite	ISO 8601 datetime to auto-resume (e.g. "2025-01-15T06:00:00")

Examples:

# Pause indefinitely
cronbase pause

# Pause until 6 AM
cronbase pause --until "2025-01-15T06:00:00"

When --until is set, the scheduler automatically resumes at that time. Without it, use cronbase resume to resume manually.

cronbase resume

Resume scheduled job execution after a pause.

cronbase resume

If the scheduler is not paused, this is a no-op.

cronbase prune

Delete execution history older than a given number of days.

cronbase prune [--days 90]

Flag	Default	Description
--days	90	Delete executions older than N days

Prints the number of deleted records and exits. Safe to run while the scheduler is running.

# Prune history older than 30 days
cronbase prune --days 30

# Prune using default (90 days)
cronbase prune

See the Maintenance guide for recommended retention periods and the self-pruning job pattern.

cronbase stats

Show summary statistics.

cronbase stats

Output:

Jobs:      5 total, 4 enabled
Last 24h:  23 successes, 1 failures
Success:   95.8%

cronbase doctor

Check the runtime environment and configuration. Validates that all prerequisites are in place before starting cronbase.

cronbase doctor [--config cronbase.yaml]

Flag	Default	Description
--config	—	Also validate a config file
--json	—	Output structured JSON

Checks performed:

• Bun runtime — detects the Bun version
• Database — verifies the SQLite database can be opened and reports job count
• Port — checks if the default port (7433) is available
• Timezone — validates CRONBASE_TIMEZONE if set
• Authentication — warns if CRONBASE_API_TOKEN is not configured
• SMTP — reports SMTP configuration if email alerting is set up
• Config file — validates the config file if --config is provided

Exits with code 0 if no failures are found, 1 if any critical issues exist.

$ cronbase doctor
cronbase v0.4.0 — environment check

  ✓ Bun runtime: v1.2.0
  ✓ Database: ./cronbase.db (5 jobs)
  ✓ Port: 7433 is available
  ✓ Timezone: America/New_York
  ⚠ Authentication: no CRONBASE_API_TOKEN set — dashboard and API are unauthenticated
  ✓ SMTP: smtp.gmail.com:465 (from: alerts@example.com)

All checks passed (1 warning).

cronbase validate

Validate a config file without making any database changes. Useful as a pre-deploy check in CI pipelines or before running cronbase start --config.

cronbase validate [--path cronbase.yaml]

Flag	Default	Description
--path	cronbase.yaml	Path to the config file to validate

Exits with code 0 if the config is valid, 1 if any errors are found.

Example:

$ cronbase validate --path my-jobs.yaml
✓ my-jobs.yaml is valid (3 jobs)

$ cronbase validate --path bad-config.yaml
✗   my-job [schedule]: Invalid schedule: Expected 5 fields
1 error found in bad-config.yaml

Global flags

--json

Output in JSON format instead of the default human-readable table. Supported by: list, show, history, logs, stats, run, export, doctor.

cronbase list --json
cronbase history --json --job backup-db
cronbase stats --json
cronbase run my-job --json
cronbase export --json

This is useful for piping into jq, scripting, and integration with monitoring tools:

# Get the name of all failing jobs in the last 24h
cronbase history --json | jq -r '.[] | select(.status == "failed") | .jobName'

# Check if success rate is above threshold
cronbase stats --json | jq '.successRate > 95'

# Export as JSON config
cronbase export --json > cronbase.json

Alternatively, use --output json for the same effect.

Environment variables

Variable	Default	Description
CRONBASE_DB	./cronbase.db	Database path (used by all commands)