Configuration reference

A docmeta.config.yaml file supplies default targets, excludes, the default schema set, and optional per-glob overrides, so CI can run a bare docmeta validate. The config is optional; every key has a default, and docmeta runs without a config when you pass paths and schemas on the command line.

Keys

Key	Type	Default	Description
paths	string[]	none	Default files, directories, or globs to process when no positional paths are given.
exclude	string[]	none	Globs to exclude from directory and glob walks. Merged with --exclude and the default ignores.
schemas	string[]	none	Default schema set applied to every file that no higher-precedence rule matches.
overrides	Override[]	none	Per-glob schema overrides. The first matching entry wins. See Overrides.
fill	Fill	none	Defaults for docmeta fill. See Fill.

The top level must be a YAML mapping. Each of paths, exclude, and schemas must be a list of strings; a non-list or a list containing a non-string value is an error (exit 2).

Fill

fill is a mapping of defaults for the fill command. Every key is optional, and every one is overridden by its CLI flag.

Key	Type	Default	Description
provider	string	auto	Inference provider: auto, anthropic, openai, claude-cli, llama-cpp, or mock. auto detects one. An unknown name is an error (exit 2).
model	string	provider default	Model override. Requires provider to be set to something other than auto, since a model name does not say which provider owns it (exit 2).
confidenceThreshold	number	0.7	Minimum self-reported confidence, from 0 to 1, needed to write a value.
maxCostUsd	number	none	Stop scheduling new files once this much has been spent.
concurrency	number	4	Files inferred in parallel. Between 1 and 64.

A numeric key outside its range, or one that is not a finite number such as YAML’s 1e999, is an error (exit 2).

docmeta.config.yaml

fill:
  provider: anthropic
  confidenceThreshold: 0.9
  maxCostUsd: 5

Pinning provider is worth doing in CI. Left on auto, a runner that loses its API key silently falls through to a local model and downloads gigabytes rather than failing the build.

Overrides

overrides is a list of mappings, each applying a schema set to files matching a glob.

Field	Type	Required	Description
files	string	yes	A glob matched against each file’s path.
schemas	string[]	yes	The schema set applied to matching files.

For a given file, docmeta uses the first override whose files glob matches (in list order); later matching overrides are ignored. See schema resolution for where overrides sit in the precedence chain.

Example

docmeta.config.yaml

paths:
  - "docs/**/*.md"
  - "docs/**/*.mdx"
exclude:
  - "docs/drafts/**"
schemas:
  - google:okf:0.1
overrides:
  - files: "docs/api/**"
    schemas:
      - ./schemas/api.schema.json
  - files: "docs/guides/**"
    schemas:
      - ./schemas/guide.schema.json

Discovery

When you do not pass -c/--config, docmeta looks in the current working directory for these files, in order, and uses the first one it finds:

1. docmeta.config.yaml
2. docmeta.config.yml

If neither exists, docmeta runs with no config. When you pass -c/--config <path> explicitly, that file must exist; a missing config file is an error (exit 2).

Note

Discovery only checks the current working directory; docmeta does not search parent directories. Run docmeta from your repo root, or point at the config with -c/--config.

How config merges with CLI flags

CLI flags and config values combine per setting. Some flags override the corresponding config value; others merge with it.

Setting	CLI flag	Config key	How they combine
Inputs	[paths...]	paths	CLI positional paths override config paths entirely. Config paths is used only when no positional paths are given.
Excludes	--exclude	exclude	Merged. The effective exclude set is config exclude plus every --exclude glob plus the default ignores.
Schemas	-s/--schema	schemas / overrides	CLI --schema overrides both schemas and overrides for every file. See precedence.
Fill settings	--confidence, --provider, --model, --max-cost-usd, --concurrency	fill.*	Each flag overrides its matching fill key. An unset flag falls back to config, then to the built-in default.

Caution

--schema is all-or-nothing: passing it once makes that schema set apply to every file in the run, bypassing config overrides and per-file $schema. Use config overrides when different folders need different schemas.