Scriven

Scriven is a small command-line tool for maintaining a single Markdown log and generating AI-written reports (weekly, monthly, incident) from selected time ranges.

It is designed to be simple, quick, and assist logging and documentation with AI-generated summaries.

---

What Scriven Does

Scriven supports exactly four actions:

1. Append entries to a log
2. Edit the log
3. View the log (paged)
4. Generate reports from the log

---

Commands

Add (default)

scriven "Configured VLAN and subnetting. +opnsense"

• Appends a timestamped entry to the log
• Log location is defined in the config
• “Tags” are plain text conventions (e.g. +homelab, +ansible) that can be used in the AI prompts.

---

Edit

scriven edit

• Opens the log file in $VISUAL, else $EDITOR
• Errors if neither is set

---

View

scriven view

Time filters:

scriven view --since 22-01-2026
scriven view --until 22-01-2026
scriven view --since 18-01-2026 --until 22-01-2026
scriven view --last 20     # last 20 entries
scriven view --last 7d     # last 7 days

---

Report

scriven report weekly

• weekly is a report type
• Other report types (e.g. monthly, incident) are defined in the config
• Each report type has:
  • a time window
  • a prompt
  • an output directory

Time selection:

scriven report weekly --since 15-01-2026
scriven report weekly --since 15-01-2026 --until 22-01-2026
scriven report weekly --last 7d

Options:

scriven report weekly --force   # ignore existing marker
scriven report weekly --print   # print to stdout only

Notes:

• Prompts live under /prompts in the repository
• Example weekly, monthly and incident prompts are versioned as part of Scriven
• Reports are written to the configured output_dir
• After generation, Scriven appends a marker to the log to avoid duplicates

Marker format:

SCRIVEN: <report-name> | range=<since>..<until>

---

Check

scriven check

Prints a full status summary:

• Config source
• Log path status
• Prompt availability
• Report configuration
• AI provider and credentials

Ends with:

RESULT: OK | WARN | ERR

No side effects.

---

Configuration

Scriven uses a single YAML configuration file.

Config discovery order

1. ./scriven.yaml
2. ~/.config/scriven.yaml

Only one file is used.

---

Config structure (v1)

log:
  path: /ABSOLUTE/PATH/TO/scriven.md
  date_format: "%d-%m-%Y"
  time_format: 24   # 24 or 12

reports:
  weekly:
    window_days: 7
    output_dir: /ABSOLUTE/PATH/TO/Reports/Weekly
    prompt: prompts/weekly.txt

provider:
  name: openai
  model: gpt-4.1-mini
  api_key_env: OPENAI_API_KEY

Notes:

• Exactly one log file is supported
• All paths must be absolute
• The log file is created automatically if it does not exist
• Prompts must live under the repository’s /prompts directory
• API keys are expected via environment variables

See scriven.example.yaml for a commented example.

---

Suggested cron usage

Scriven is designed to work well with cron.

Example: Weekly report (Sunday night):

55 23 * * 0 scriven report weekly

Monthly report (first day of month):

10 0 1 * * scriven report monthly

Notes:

• Ensure OPENAI_API_KEY is available in the cron environment
• Cron jobs should run on a machine where the log file is accessible
• Use scriven check to verify readiness before scheduling

---

Author

Created by Saar Yachin. Scriven is very simple! It records and it can summarize and that's pretty much it, yet this little tool proved very useful in organizing my homelab documentation. I hope you too will make good use of it.