Binary reference

ai-scheduler

Kodachi Scheduler Daemon - Cron-based command scheduling with security whitelist

Version9.8.4Size9.5MBAuthorWarith Al MaawaliLicenseProprietaryWebsitehttps://www.digi77.com

File Information

Property	Value
Binary Name	ai-scheduler
Version	9.8.4
Build Date	Not disclosed
Rust Version	1.82.0
File Size	9.5MB
Author	Warith Al Maawali
License	Proprietary
Category	Kodachi Binary
Description	Kodachi Scheduler Daemon - Cron-based command scheduling with security whitelist
Git Commit	unknown
Metadata Generated	2026-08-10T13:22:53Z
Binary Timestamp	Unknown
JSON Data	View Raw JSON

SHA256 Checksum

a16e12e77609491e250f20be05309fe13c278f993d2e86f4a43949fcbbb10c70

Features

#	Feature
1	Cron expression parsing, 6 fields: second minute hour day month weekday ("0 0 * * * *" = hourly)
2	Event-driven triggers
3	Command whitelist validation
4	Execution history tracking

Security Features

Feature	Description
Input Validation	Argument parsing via clap; per-command validation is the consumer's responsibility
Rate Limiting	Not provided by cli-core
Authentication	Not provided by cli-core (see online-auth)
Encryption	Not provided by cli-core

System Requirements

Requirement	Value
OS	Linux (Debian-based)
Privileges	root/sudo for system operations
Dependencies	OpenSSL, libcurl

Global Options

Flag	Description
`-h, --help`	Print help information
`-v, --version`	Print version information
`-n, --info`	Display detailed information
`-e, --examples`	Show usage examples
`--json`	Output in JSON format
`-o, --output-format <FORMAT>`	Force output format (text\|json)
`--json-pretty`	Pretty-print JSON output with indentation
`--json-human`	Enhanced JSON output with improved formatting (like jq)
`--json-filter <FIELD1,FIELD2>`	Return only specified JSON fields (comma-separated)
`--fields <FIELD_LIST>`	Select specific fields to include in output (comma-separated)
`--limit <NUMBER>`	Limit number of results returned
`--offset <NUMBER>`	Skip first N results (for pagination)
`-d, --work-dir <PATH>`	Working directory (defaults to auto-detected base directory)
`--port <PORT>`	Set custom port number (1024-65535)
`--log-level <LEVEL>`	Set log level (error\|warn\|info\|debug)
`--verbose`	Enable verbose output
`--quiet`	Suppress non-essential output
`--no-color`	Disable colored output
`--config <FILE>`	Use custom configuration file
`--timeout <SECS>`	Set operation timeout in seconds (optional; no default applied)

Commands

Daemon Control

`start`

Start the scheduler daemon

Usage:

ai-scheduler start [OPTIONS]

Options:

-f, --foreground: Run the scheduler loop in this terminal instead of detaching (blocks until Ctrl+C)
--json: Emit status, mode, schedules_loaded, executions, pid and already_running as a JSON envelope

Examples:

sudo ai-scheduler start

sudo ai-scheduler start --foreground

sudo ai-scheduler start --json

Schedule Management

`add`

Add a new scheduled task

Usage:

ai-scheduler add [OPTIONS]

Options:

--name <NAME>: Unique name for the schedule
--command <COMMAND>: Command to execute. The binary must be whitelisted, a subcommand is required, and the subcommand plus arguments must pass the shared gateway policy validator
--cron <EXPRESSION>: Six mandatory fields: second minute hour day-of-month month day-of-week (optional 7th field is the year). Weekday ordinals are 1=Sunday through 7=Saturday. A five-field crontab string does not parse
--json: Emit schedule_id, name, command, cron_expression and schedule_description as a JSON envelope

Examples:

ai-scheduler add --name "hourly-tor" --command "tor-switch tor-status" --cron "0 0 * * * *"

ai-scheduler add --name "dns-check" --command "dns-leak test" --cron "0 */30 * * * *"

ai-scheduler add --name "daily-check" --command "health-control net-check" --cron "0 0 8 * * *" --json

ai-scheduler add --name "weekly-memory-clean" --command "health-control memory-clean" --cron "0 0 2 * * 1"

`list`

List all scheduled tasks

Usage:

ai-scheduler list [OPTIONS]

Options:

--json: Emit count and the schedules array as a JSON envelope

Examples:

ai-scheduler list

ai-scheduler list --json

`remove`

Remove a scheduled task

Usage:

ai-scheduler remove [OPTIONS]

Options:

<ID>: Numeric schedule ID to delete, as shown by `ai-scheduler list`. Irreversible
--json: Emit status, schedule_id and deleted as a JSON envelope

Examples:

ai-scheduler remove 1

ai-scheduler remove 2 --json

Operational Scenarios

Scenario-oriented workflows generated from the binary's built-in -e --json examples.

Scenario 1: Cron Syntax (read this first)

Every --cron expression takes SIX mandatory fields: second minute hour day-of-month month day-of-week (an optional seventh field is the year). A five-field crontab-style string does not parse. Weekday ordinals run 1 to 7 where 1 is Sunday and 7 is Saturday, and the names Sun through Sat are also accepted. `add` validates the expression before it writes anything, so a bad expression is rejected up front.

Step 1: Every hour, on the hour

ai-scheduler add --name "hourly-tor" --command "tor-switch tor-status" --cron "0 0 * * * *"

Expected Output: Schedule added successfully, with its ID, name, command, cron string and the next run times

Note

Requires a prior `online-auth` login. "0 0 * * * *" is second 0, minute 0, every hour.

Step 2: Every 30 minutes

ai-scheduler add --name "dns-check" --command "dns-leak test" --cron "0 */30 * * * *"

Expected Output: Schedule added successfully with the next run time roughly 30 minutes out

Note

Requires a prior `online-auth` login.

Step 3: Once a day at 08:00

ai-scheduler add --name "daily-check" --command "health-control net-check" --cron "0 0 8 * * *"

Expected Output: Schedule added successfully with tomorrow 08:00 as the next run

Note

Requires a prior `online-auth` login. Times are evaluated in UTC.

Step 4: Once a week, Sunday at 02:00

ai-scheduler add --name "weekly-memory-clean" --command "health-control memory-clean" --cron "0 0 2 * * 1"

Expected Output: Schedule added successfully with the coming Sunday 02:00 as the next run

Note

Requires a prior `online-auth` login. Weekday 1 IS Sunday in this cron dialect (1 to 7, Sunday through Saturday). Ordinal 0 is out of range and is rejected.

Scenario 2: Daemon Control

Run the scheduler loop that actually fires the tasks. Nothing you add with `add` runs until the daemon is running.

Step 1: Start the scheduler in the background

sudo ai-scheduler start

Expected Output: Scheduler daemon started successfully, with mode Background, schedules loaded, executions and the PID

Note

Requires a prior `online-auth` login (start is not on the read-only exempt list). Needs root: the PID file is written under the install directory.

Step 2: Run the scheduler loop in this terminal so you can watch tasks fire

sudo ai-scheduler start --foreground

Expected Output: The scheduler stays attached and prints each execution as it happens

Note

Requires a prior `online-auth` login. Blocks until Ctrl+C. -f is the short form.

Step 3: Start in the background and capture the result as JSON

sudo ai-scheduler start --json

Expected Output: Envelope with status, mode, schedules_loaded, executions, pid and already_running

Note

Requires a prior `online-auth` login.

Scenario 3: Schedule Management

Add, list and remove scheduled tasks. --name, --command and --cron are all required on `add`.

Step 1: Schedule a DNS leak test every 30 minutes and get the task ID back as JSON

ai-scheduler add --name "dns-check" --command "dns-leak test" --cron "0 */30 * * * *" --json

Expected Output: Envelope with schedule_id, name, command, cron_expression and schedule_description

Note

Requires a prior `online-auth` login.

Step 2: See every scheduled task and when it next runs

ai-scheduler list

Expected Output: One block per task: [ID] name, command, cron, next run, last run and execution count. 'No scheduled tasks found.' when the table is empty

Step 3: Machine-readable task list for the dashboard

ai-scheduler list --json

Expected Output: Envelope with count and the schedules array

Step 4: Delete the task with ID 1

ai-scheduler remove 1

Expected Output: 'Schedule 1 removed successfully', or 'Schedule 1 not found' if the ID does not exist

Note

Requires a prior `online-auth` login. Irreversible: the schedule row is deleted. Get the ID from `ai-scheduler list`.

Step 5: Delete a task and confirm the result in JSON

ai-scheduler remove 2 --json

Expected Output: Envelope with status, schedule_id and deleted (true or false)

Note

Requires a prior `online-auth` login. Irreversible.

Scenario 4: Command Whitelist

A scheduled command must name an allowlisted Kodachi service, include a subcommand, pass argument sanitization, and be allowed by the shared ai-gateway policy before the schedule is written.

Step 1: An allowlisted service and policy-approved subcommand are accepted

ai-scheduler add --name "tor-health" --command "tor-switch tor-status" --cron "0 */15 * * * *" --json

Expected Output: Envelope with the new schedule_id

Note

Requires a prior `online-auth` login. Unknown or policy-blocked subcommands are rejected before the schedule is saved.

Step 2: A binary that is not on the whitelist is refused before anything is written

ai-scheduler add --name "blocked-test" --command "malicious-binary run" --cron "0 0 * * * *" --json

Expected Output: An error envelope saying the command is not whitelisted, and no schedule is created

Note

Requires a prior `online-auth` login.

Environment Variables

Variable	Description	Default	Values
`NO_COLOR`	Disable all colored output when set	unset	1\|true\|yes (any value disables color)

Exit Codes

Code	Description
5	File not found
2	Invalid arguments
0	Success
1	General error
3	Permission denied
4	Network error