xls_doc/docs/superpowers/specs/2026-06-18-docfill-p0-cli-design.md

Docfill P0 CLI Design

Goal

Make the MVP safe enough for a digital employee to call repeatedly from scripts.

CLI Contract

docfill run --config task.json --var date=2026-06-18
docfill run -c task.json --var date=2026-06-18 --var department=营销部

Exit codes:

• 0: success.
• 1: task execution or validation failed.
• 2: CLI usage error.

Output:

• Success writes a short generated-file summary to stdout.
• Errors write one clear line to stderr with the docfill: prefix.

Reserved for later:

• docfill validate.
• --json.

P0 Behavior

• Resolve relative paths in config from the config file directory.
• Support config vars and repeated CLI vars.
• CLI vars override config vars.
• Per-row data overrides vars during template rendering.
• Generated _row is always the 1-based row number.
• Support SQLite params for ? query placeholders.
• Support Excel header_row, 1-based, default 1.
• Do not overwrite existing output files unless output.overwrite is true.
• Sanitize placeholder values only when rendering output file paths.
• Fail if any template placeholder is missing from the current row context.
• Fail if any {{field}} remains after rendering.

Config Shape

{
  "vars": {
    "date": "2026-06-18"
  },
  "data": {
    "type": "sqlite",
    "path": "./data.db",
    "query": "select name, done from daily where date = ?",
    "params": ["{{date}}"]
  },
  "template": {
    "path": "./template.docx"
  },
  "output": {
    "path": "./out/report_{{date}}_{{name}}_{{_row}}.docx",
    "overwrite": false
  }
}