# CLI-SPEC.md ## Scope This document defines the command-line interface (CLI) specification for: * `krontab` (configuration manager) * `krond` (daemon control interface) * `kronctl` (optional Kubernetes helper) This specification defines: * Commands * Flags * Exit codes * Output formats * Determinism guarantees * Compatibility rules All CLI behavior must be stable within a major version. --- # krontab `krontab` manages local Kron configuration files for `krond`. MVP implementation status: * Implemented: `lint`, `explain`, `next` * Planned (not implemented in MVP): `add`, `remove` ## Configuration Location Default: ``` /etc/krond.d/ ``` Per-user mode (optional): ``` ~/.config/krond/ ``` Each file may contain one or more job entries. --- ## Command: `krontab lint` Validates configuration. ``` krontab lint [--file ] [--format text|json] ``` Behavior: * Parses configuration. * Validates syntax. * Validates distributions. * Validates constraints. * Validates durations. * Does not require daemon running. Exit codes: * `0` valid * `1` invalid * `2` system error MVP canonical stderr text: * missing file: `error: --file is required for MVP` * positional args provided: `error: lint does not accept positional arguments` Output (text): ``` OK: /etc/krond.d/backups.kron ``` Output (json): ``` { "file": "...", "valid": true, "errors": [] } ``` --- ## Command: `krontab explain` Explains decision for a specific job and period. ``` krontab explain --at [--file ] [--window ] [--mode after|before|center] [--dist uniform|skewEarly|skewLate] [--format text|json] ``` Behavior: * Loads job definition from `--file` when provided. * Resolves nominal period for `--at`. * Calls `kron-core`. * Outputs full decision explanation. * Does not execute job. * In MVP runtime, `--dist` and `@dist(...)` for `explain` support: `uniform`, `skewEarly`, `skewLate`. * `normal`/`exponential` distribution syntax can be linted but is not executed by MVP `explain`/`next`. Exit codes: * `0` success * `1` job not found * `2` invalid input MVP canonical stderr text: * missing timestamp: `error: --at is required` * missing job: `error: explain requires exactly one argument` * unknown job: `error: job not found: ` Text output example: ``` job: backup period_start: 2026-03-01T00:00:00Z window: [2026-03-01T00:00:00Z, 2026-03-01T03:00:00Z) mode: after distribution: uniform seed_hash: 9c85657760a63b4d925af6088cceb2bb4448380b2e6856b203915a0a51ab5101 chosen_time: 2026-03-01T02:32:20Z ``` JSON output is a single `core.Decision` object. --- ## Command: `krontab next` Shows next N scheduled decisions. ``` krontab next --file [--count N] [--at ] [--format text|json] ``` Default `N=1`. Behavior: * Loads job definition from `--file`. * Iteratively compute next periods using `kron-core`. * Runtime distribution execution is limited to `uniform`, `skewEarly`, `skewLate`. * `normal`/`exponential` distribution syntax can be linted but is not executed by MVP `next`. * Do not mutate state. * Deterministic output. Exit codes: * `0` success * `1` job not found * `2` invalid input/config MVP canonical stderr text: * missing file: `error: --file is required for MVP` * missing job: `error: next requires exactly one argument` * invalid count: `error: --count must be > 0` --- ## Command: `krontab add` Status: planned (not implemented in MVP CLI binary). Adds or updates job definition. ``` krontab add --file ``` Behavior: * Validates file. * Writes to config directory. * Does not restart daemon automatically. Exit codes: * `0` success * `1` validation error * `2` write error --- ## Command: `krontab remove` Status: planned (not implemented in MVP CLI binary). Removes job. ``` krontab remove ``` Behavior: * Removes configuration entry. * Does not delete state automatically. Exit codes: * `0` success * `1` job not found --- # krond `krond` is the daemon. Status: planned (not implemented in current MVP). --- ## Command: `krond start` ``` krond start [--config ] [--foreground] [--log-format text|json] ``` Behavior: * Starts daemon. * Acquires lock. * Loads configuration. * Enters scheduler loop. Exit codes: * `0` clean exit * `1` configuration error * `2` state error * `3` lock error * `4` fatal persistence error --- ## Command: `krond reload` ``` krond reload ``` Behavior: * Sends SIGHUP to running daemon. * Daemon reloads config. * Active executions unaffected. Exit codes: * `0` success * `1` daemon not running --- ## Command: `krond status` ``` krond status [--format text|json] ``` Outputs: * Running/not running * PID * Number of jobs * Next scheduled execution time (earliest) Exit codes: * `0` running * `1` not running --- ## Command: `krond stop` ``` krond stop [--graceful] ``` Behavior: * Sends SIGTERM. * If `--graceful`, waits for active jobs to complete. Exit codes: * `0` success * `1` daemon not running --- # kronctl (Kubernetes helper) Optional CLI for Kubernetes users. Status: planned (not implemented in current MVP). --- ## Command: `kronctl explain` ``` kronctl explain / [--at ] [--format text|json] ``` Behavior: * Fetch KronJob. * Compute decision using kron-core. * Does not create Job. * Does not mutate cluster. --- ## Command: `kronctl next` ``` kronctl next / [--count N] ``` Displays next N decisions. --- ## Command: `kronctl validate` ``` kronctl validate -f ``` Validates YAML manifests before applying. --- # Output Formats All CLI tools must support: * `text` * `json` Text: * Human readable. * Stable field labels. * Deterministic ordering. JSON: * Single JSON object per command. * Stable field names. * No extraneous fields. * Deterministic key order not required. --- # Exit Codes Global conventions: * `0` success * `1` user error (invalid input, not found) * `2` validation/config error * `3` state error * `4` runtime/fatal error Exit codes must not change within major version. --- # Determinism Requirements For identical: * Config * Version * Inputs Commands: * `explain` * `next` Must produce identical outputs. Output must not depend on: * Current system time (unless explicitly provided) * Environment variables * Host locale --- # Logging Interaction CLI tools: * Must not emit daemon logs. * Must print only command output. * Errors must go to stderr. * Structured JSON must go to stdout only. --- # Backward Compatibility Within major version: * Command names stable. * Flag names stable. * Output schema stable. * Exit codes stable. New commands may be added. Breaking CLI changes require major version increment. --- # Security Rules CLI must: * Validate file permissions when appropriate. * Refuse to operate on world-writable config. * Not expose sensitive environment variables. * Not execute jobs during explain or validation. --- # Non-Goals CLI does not: * Replace cron CLI exactly. * Emulate crontab interactive editor. * Automatically restart daemon on config change. * Provide workflow orchestration. CLI is a deterministic interface to Kron scheduling semantics.