xls_doc/docs/digital-employee-runbook.md

Digital Employee Runbook

This file is the minimal operating contract for calling docfill from a digital employee, scheduler, or shell script.

Inputs

Each run needs:

• A task.json config file.
• A data source: .xlsx or SQLite .db.
• A template: .docx or .xlsx.
• An output path pattern in task.json.

Paths inside task.json are resolved from the config file directory.

Command

docfill run -c /path/to/task.json --var date=2026-06-18

Use repeated --var key=value arguments for runtime values:

docfill run -c task.json --var date=2026-06-18 --var batch=早班

CLI variables override vars in task.json. Row data overrides both.

Success

Exit code 0.

Stdout contains generated files:

generated 2 file(s)
- /path/to/out/report_张三.xlsx
- /path/to/out/report_李四.xlsx

Failure

Exit code 1 means the task ran but failed.

Exit code 2 means the command line was invalid.

Errors are written to stderr with the docfill: prefix:

docfill: render row 1: missing template field "done"

Common Errors

missing template field

The template contains a {{field}} that is not present in data, vars, or CLI --var.

output already exists

The output file exists and output.overwrite is not true.

missing sqlite params field

A SQLite query parameter such as {{date}} was not provided.

unresolved placeholder

The rendered document still contains {{field}}. Check the source data value and the template.

Build

bash scripts/build.sh

The local build output is:

dist/docfill-darwin-arm64

Smoke Test

bash scripts/smoke.sh

Smoke test builds a temporary binary, generates temporary example files, runs both example configs, and checks generated outputs.