Agent Cron Truth Document

Generated: 2026-03-18 Source: agcron binary (cargo build) + Rust source code

CLI Command Reference

All help outputs captured verbatim from agcron binary built from rust/src/main.rs.

agcron --help

AI agent workflow scheduler

Usage: agcron <COMMAND>

Commands:
  daemon       Start the agent-cron daemon in the foreground
  status       Show daemon status including uptime, job counts, and queue depth
  stop         Stop the running daemon gracefully
  ps           Show job queue status and statistics
  watch        Watch live daemon activity
  jobs         Manage and inspect scheduled jobs
  stats        Show aggregate job execution statistics
  logs         View and tail job execution logs
  roots        Manage project roots
  completions  Generate shell completion scripts
  init         Initialize a project directory for agcron usage
  help         Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

agcron daemon --help

Start the agent-cron daemon in the foreground

Usage: agcron daemon [OPTIONS]

Options:
  -d, --daemon  Run in background (daemonize)
  -h, --help    Print help

agcron status --help

Show daemon status including uptime, job counts, and queue depth

Usage: agcron status

Options:
  -h, --help  Print help

agcron stop --help

Stop the running daemon gracefully

Usage: agcron stop

Options:
  -h, --help  Print help

agcron ps --help

Show job queue status and statistics

Usage: agcron ps

Options:
  -h, --help  Print help

agcron watch --help

Watch live daemon activity

Displays a continuously refreshing dashboard of running jobs, queue state, and recent completions. Refreshes every 1 second. Press Ctrl+C to exit.

Usage: agcron watch [OPTIONS]

Options:
      --once
          Print a single snapshot and exit (suitable for scripting)

  -j, --json
          Output as JSON (implies --once)

  -h, --help
          Print help (see a summary with '-h')

agcron stats --help

Show aggregate job execution statistics

Displays success rates, failure counts, and duration trends over configurable time windows. Use without arguments for a global summary table, or provide a job ID for detailed per-job breakdown.

Usage: agcron stats [OPTIONS] [JOB_ID]

Arguments:
  [JOB_ID]
          Job ID for single-job detailed view (omit for global summary)

Options:
  -d, --days <DAYS>
          Number of days to include (default: 7)

          [default: 7]

      --since <SINCE>
          Start date for range filter (YYYY-MM-DD)

      --until <UNTIL>
          End date for range filter (YYYY-MM-DD)

  -j, --json
          Output as JSON

  -h, --help
          Print help (see a summary with '-h')

agcron jobs --help

Manage and inspect scheduled jobs

Usage: agcron jobs <COMMAND>

Commands:
  list     List all loaded jobs with their schedules and next run times
  info     Show detailed information about a specific job
  trigger  Queue a job for immediate execution via the daemon
  history  Show execution history for a job
  run      Run a job immediately
  help     Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

agcron jobs list --help

List all loaded jobs with their schedules and next run times

Usage: agcron jobs list

Options:
  -h, --help  Print help

agcron jobs info --help

Show detailed information about a specific job

Usage: agcron jobs info <JOB_ID>

Arguments:
  <JOB_ID>  Job ID (filename without extension)

Options:
  -h, --help  Print help

agcron jobs trigger --help

Queue a job for immediate execution via the daemon

Usage: agcron jobs trigger <JOB_ID>

Arguments:
  <JOB_ID>  Job ID (filename without extension)

Options:
  -h, --help  Print help

agcron jobs history --help

Show execution history for a job

Displays a table of past execution results including status, adapter, model, duration, exit code, and start time. Failed runs show a truncated stderr line beneath the entry.

Use --all to show history across all jobs interleaved chronologically.

Usage: agcron jobs history [OPTIONS] [JOB_ID]

Arguments:
  [JOB_ID]
          Job ID (omit for --all mode)

Options:
      --all
          Show history across all jobs

  -n, --limit <LIMIT>
          Maximum number of entries to display

          [default: 25]

  -s, --sort <SORT>
          Sort by field (duration, status, started)

      --status <STATUS>
          Filter by status (completed, failed, timeout)

  -j, --json
          Output as JSON

  -h, --help
          Print help (see a summary with '-h')

agcron jobs run --help

Run a job immediately

In direct mode (--direct), executes the job without the daemon using a minimal adapter setup. No state files, history, or locks are created. This is useful for testing and one-off execution.

Without --direct, sends an RPC to the running daemon to queue the job for immediate execution (equivalent to `jobs trigger`).

Usage: agcron jobs run [OPTIONS] <JOB>

Arguments:
  <JOB>
          Job file path or ID

Options:
      --direct
          Bypass daemon, execute directly (ephemeral, no state/history/locks)

      --force
          Ignore existing lock and re-run (daemon mode only)

      --follow
          Tail stdout log during execution (daemon mode only)

      --no-record
          Skip state/history recording, no retries (daemon mode only)

  -h, --help
          Print help (see a summary with '-h')

agcron logs --help

View and tail job execution logs

Access stdout and stderr output from job executions. Use `show` for past logs or `tail` for live streaming.

Usage: agcron logs <COMMAND>

Commands:
  show  Show log output from a job's most recent execution
  tail  Tail real-time log output from a running job
  help  Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')

agcron logs show --help

Show log output from a job's most recent execution

Displays the complete stdout (or stderr with --stderr) from the most recent execution. Use --date to view logs from a specific past date.

Usage: agcron logs show [OPTIONS] <JOB_ID>

Arguments:
  <JOB_ID>
          Job ID (filename without extension)

Options:
      --stderr
          View stderr instead of stdout

      --date <DATE>
          View logs from a specific date (YYYY-MM-DD)

  -h, --help
          Print help (see a summary with '-h')

agcron logs tail --help

Tail real-time log output from a running job

Streams stdout (or stderr with --stderr) as the job executes. Automatically exits when the job reaches a terminal state. Waits up to 30 seconds for the log file to appear if the job hasn't started writing output yet.

Usage: agcron logs tail [OPTIONS] <JOB_ID>

Arguments:
  <JOB_ID>
          Job ID (filename without extension)

Options:
      --stderr
          Tail stderr instead of stdout

  -h, --help
          Print help (see a summary with '-h')

agcron roots --help

Manage project roots

Usage: agcron roots <COMMAND>

Commands:
  list  List managed project directories
  help  Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

agcron roots list --help

List managed project directories

Shows all project roots configured in the daemon's config file. Each root is shown with a check mark if the directory exists.

Usage: agcron roots list

Options:
  -h, --help
          Print help (see a summary with '-h')

agcron completions --help

Generate shell completion scripts

Output the completion script to stdout. Redirect to a file appropriate for your shell:

agcron completions bash > ~/.local/share/bash-completion/completions/agcron
agcron completions zsh > ~/.zfunc/_agcron
agcron completions fish > ~/.config/fish/completions/agcron.fish

Usage: agcron completions <SHELL>

Arguments:
  <SHELL>
          Shell to generate completions for

          [possible values: bash, elvish, fish, powershell, zsh]

Options:
  -h, --help
          Print help (see a summary with '-h')

agcron init --help

Initialize a project directory for agcron usage

Creates .cron/jobs/ directory and registers the project in the global config file (~/.config/agent-cron/config.toml).

Usage: agcron init [OPTIONS]

Options:
      --path <PATH>
          Project directory to initialize (defaults to current directory)

          [default: .]

  -h, --help
          Print help (see a summary with '-h')

Config Schema

Source: rust/src/config.rs -- Config struct with Default impl

Top-Level Fields (19)

Field	Type	Default	Description
`project_roots`	`Vec<PathBuf>`	`[]`	Directories to watch for job files
`concurrency_limit`	`usize`	`4`	Maximum concurrent job executions
`default_agent`	`String`	`"claude"`	Default agent to use when not specified in job
`default_model`	`String`	`"claude-3-5-sonnet"`	Default model to use when not specified in job
`log_retention_days`	`u32`	`30`	Days to retain execution logs
`socket_path`	`PathBuf`	`~/.config/agent-cron/agent-cron.sock`	Unix socket path for IPC
`default_timeout_secs`	`u64`	`300`	Default execution timeout in seconds
`adapter_timeouts`	`HashMap<String, u64>`	`{}`	Per-adapter timeout overrides (agent name -> seconds)
`max_retries`	`u32`	`2`	Maximum retry attempts for failed jobs
`retry_delay_secs`	`u64`	`5`	Delay between retries in seconds
`schema_strictness`	`SchemaStrictness`	`strict`	Schema validation strictness
`debounce_delay_ms`	`i64`	`2000`	Debounce delay for file system events in milliseconds (-1 to disable)
`invalid_file_handling`	`InvalidFileHandling`	`unload`	How to handle files that become invalid
`running_job_handling`	`RunningJobHandling`	`finish-current`	How to handle running jobs when file changes
`max_queue_depth`	`usize`	`10000`	Maximum number of jobs in queue
`queue_ttl_secs`	`u64`	`3600`	TTL in seconds before queued jobs expire (1 hour)
`shutdown_timeout_secs`	`u64`	`30`	Seconds to wait for in-flight jobs to complete during shutdown
`alerting`	`AlertingConfig`	(see below)	Alerting configuration for terminal job states
`adapters`	`Vec<CliAdapterConfig>`	`[]`	Custom adapter configurations from `[[adapters]]` sections in config.toml

AlertingConfig (4 fields)

Source: rust/src/config.rs -- AlertingConfig struct

Field	Type	Default	Description
`desktop_notifications`	`bool`	`true`	Enable macOS desktop notifications
`states`	`Vec<AlertState>`	`[failed, timeout, crashed]`	Terminal states that trigger alerts
`webhook_url`	`String`	`""`	Webhook endpoint URL for alert delivery (optional)
`webhook_timeout_secs`	`u64`	`10`	Webhook timeout in seconds

Enums

Source: rust/src/config.rs

SchemaStrictness (#[serde(rename_all = "kebab-case")])

Variant	Serialized	Description
`Strict`	`strict`	Reject jobs that don't match schema
`WarnButLoad`	`warn-but-load`	Log warnings but load jobs anyway
`BestEffort`	`best-effort`	Best effort parsing, ignore schema errors

InvalidFileHandling (#[serde(rename_all = "kebab-case")])

Variant	Serialized	Description
`Unload`	`unload`	Unload the job when file becomes invalid
`KeepLastValid`	`keep-last-valid`	Keep the last valid version of the job

RunningJobHandling (#[serde(rename_all = "kebab-case")])

Variant	Serialized	Description
`FinishCurrent`	`finish-current`	Let the current execution finish, then apply changes
`CancelOnChange`	`cancel-on-change`	Cancel the running job and apply changes immediately

AlertState (#[serde(rename_all = "kebab-case")])

Variant	Serialized
`Failed`	`failed`
`Timeout`	`timeout`
`Crashed`	`crashed`

Environment Variables

Variable	Purpose
`AGENT_CRON_CONFIG`	Override config file path
`AGENT_CRON_SOCKET`	Override socket path

Job Frontmatter Schema (13 fields)

Source: rust/src/job.rs -- JobFrontmatter struct

All fields are optional. Jobs can use defaults from config.toml. Template inheritance allows jobs to extend base templates.

Field	Type	Required	Description
`schedule`	`Option<String>`	No	Cron expression for scheduling (e.g., "0 * * * *")
`timezone`	`Option<String>`	No	Timezone for schedule interpretation (e.g., "America/Los_Angeles")
`agent`	`Option<String>`	No	Primary agent CLI to use (claude, opencode, gemini, etc.)
`model`	`Option<String>`	No	Model identifier for the agent
`fallback_agent`	`Option<String>`	No	Fallback agent if primary fails
`fallback_model`	`Option<String>`	No	Fallback model if primary fails
`timeout`	`Option<u64>`	No	Execution timeout in seconds (overrides config default)
`max_retries`	`Option<u32>`	No	Maximum retry attempts (overrides config default)
`auto_approve`	`Option<bool>`	No	Enable auto-approve/unattended mode for the agent CLI (default: false)
`extends`	`Option<String>`	No	Template file to extend (e.g., "template.md")
`id`	`Option<String>`	No	Slug-safe identifier for the job
`description`	`Option<String>`	No	Short description of the job's purpose
`tags`	`Option<Vec<String>>`	No	Classification tags

JSON-RPC 2.0 Methods (14 methods)

Source: rust/src/daemon.rs -- DaemonRpcHandler::handle() match arms (lines 724-744)

Method	Parameters	Description
`status`	None	Returns daemon status (uptime, job counts, queue depth)
`shutdown`	None	Initiates graceful daemon shutdown
`jobs.list`	None	Lists all loaded jobs with schedules and next run times
`jobs.info`	`{ "job_id": String }`	Returns detailed information about a specific job
`jobs.trigger`	`{ "job_id": String }`	Queues a job for immediate execution
`jobs.history`	`{ "job_id": String, "limit": usize?, "sort": String?, "status": String?, "json": bool? }`	Returns execution history for a specific job
`jobs.history_all`	`{ "limit": usize?, "sort": String?, "status": String?, "json": bool? }`	Returns execution history across all jobs
`stats`	`{ "days": u32?, "since": String?, "until": String?, "json": bool? }`	Returns aggregate execution statistics
`stats.job`	`{ "job_id": String, "days": u32?, "since": String?, "until": String?, "json": bool? }`	Returns detailed stats for a single job
`queue.stats`	None	Returns queue depth, capacity, and TTL info
`roots.list`	None	Lists all configured project root directories
`logs.show`	`{ "job_id": String, "stderr": bool?, "date": String? }`	Returns log content from a job execution
`logs.path`	`{ "job_id": String, "stderr": bool?, "date": String? }`	Returns the filesystem path to a job's log file
`watch.state`	`{ "since_version": u64? }`	Returns current daemon state for live dashboard

Adapter Configurations

Source: rust/src/adapter/generic.rs

Built-in Adapters (5 + mock)

Adapter	Binary	Prompt Delivery	Pre-args	Model Flag	Approve Flag
`claude`	`claude`	`stdin`	`["-p"]`	`--model`	`--dangerously-skip-permissions`
`opencode`	`opencode`	`positional`	`["run"]`	`-m`	None
`gemini`	`gemini`	`positional`	`["-p"]`	`-m`	`-y`
`codex`	`codex`	`positional`	`["exec"]`	`-m`	`--full-auto`
`copilot`	`copilot`	`positional`	`["-p"]`	`--model`	`--yolo`

Post-args: opencode uses ["--format", "default"], copilot uses ["-s"], others use [].

CliAdapterConfig Fields

Source: rust/src/adapter/generic.rs -- CliAdapterConfig struct

Field	Type	Default	Description
`id`	`String`	(required)	Unique identifier for this adapter
`binary`	`String`	(required)	Binary name or path
`prompt_delivery`	`PromptDeliveryMode`	`positional`	How the prompt is delivered to the CLI
`prompt_file_flag`	`String`	`"--file"`	Flag used when prompt_delivery is File
`pre_args`	`Vec<String>`	`[]`	Arguments placed before the prompt
`post_args`	`Vec<String>`	`[]`	Arguments placed after the prompt
`model_flag`	`Option<String>`	`None`	Flag name for passing the model
`approve_flag`	`Option<String>`	`None`	Flag for auto-approve/unattended mode (only included when job has auto_approve: true)
`args_template`	`Option<Vec<String>>`	`None`	Template-based args; {prompt}, {prompt_file}, {model} interpolated at execution time

PromptDeliveryMode

Source: rust/src/adapter/generic.rs -- enum with #[serde(rename_all = "lowercase")]

Variant	Serialized	Description
`Positional`	`positional`	Pass prompt text as a positional argument after pre_args
`File`	`file`	Write prompt to a temp file, then pass the file path via prompt_file_flag
`Stdin`	`stdin`	Pipe prompt text to the process's stdin

Last validated: 2026-03-21 (v1.9 documentation audit)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Agent Cron Truth Document

CLI Command Reference

agcron --help

agcron daemon --help

agcron status --help

agcron stop --help

agcron ps --help

agcron watch --help

agcron stats --help

agcron jobs --help

agcron jobs list --help

agcron jobs info --help

agcron jobs trigger --help

agcron jobs history --help

agcron jobs run --help

agcron logs --help

agcron logs show --help

agcron logs tail --help

agcron roots --help

agcron roots list --help

agcron completions --help

agcron init --help

Config Schema

Top-Level Fields (19)

AlertingConfig (4 fields)

Enums

Environment Variables

Job Frontmatter Schema (13 fields)

JSON-RPC 2.0 Methods (14 methods)

Adapter Configurations

Built-in Adapters (5 + mock)

CliAdapterConfig Fields

PromptDeliveryMode

FilesExpand file tree

truth-document.md

Latest commit

History

truth-document.md

File metadata and controls

Agent Cron Truth Document

CLI Command Reference

agcron --help

agcron daemon --help

agcron status --help

agcron stop --help

agcron ps --help

agcron watch --help

agcron stats --help

agcron jobs --help

agcron jobs list --help

agcron jobs info --help

agcron jobs trigger --help

agcron jobs history --help

agcron jobs run --help

agcron logs --help

agcron logs show --help

agcron logs tail --help

agcron roots --help

agcron roots list --help

agcron completions --help

agcron init --help

Config Schema

Top-Level Fields (19)

AlertingConfig (4 fields)

Enums

Environment Variables

Job Frontmatter Schema (13 fields)

JSON-RPC 2.0 Methods (14 methods)

Adapter Configurations

Built-in Adapters (5 + mock)

CliAdapterConfig Fields

PromptDeliveryMode