User Guide Configuration Reference

Configuration Reference

Prev: Configuration | Up: User Guide | Next: Security, Audit, and SBOM

This page is master config.lua reference. Use Configuration for practical guidance and this page for exact fields, defaults, override rules, runtime caveats, and feature discovery.

Capability Map

Goal	Main config areas	Commands / runtime	Caveats
Change plugin discovery and wrapper-source precedence	downloader, registry	normal plugin loads, update, wrapper refresh	workspace ./plugins can shadow configured plugins
Tune audit blocking and advisory matching	security, reports	install, update, audit	reports.* pipeline is still partial
Tune recovery, concurrency, and write-policy checks	execution	mutating commands	transaction DB applies to mutating runs only
Keep machine-readable logs	logging, display	all commands	display capture matters only for structured logs
Keep reproducible installed-state snapshots	history	mutating commands, snapshot	trackInstalled is independent from history.enabled
Control ReqPack self-update source and install path	selfUpdate	rqp update self-update mode	only rqp update with no system and no --all uses this section
Set remote-server defaults	remote	rqp serve --remote	explicit serve flags override config
Configure native rqp repositories	rqp	install rqp, update rqp, pack	not same thing as general repositories

File Discovery

Main config path:

• $XDG_CONFIG_HOME/reqpack/config.lua
• fallback: ~/.config/reqpack/config.lua

Related config file:

• remote.lua lives beside it and is separate from config.lua

ReqPack accepts either:

• Lua file returning root table
• Lua file that sets global config = { ... }

Resolution and Precedence

Config resolution order:

• built-in defaults
• config file selected by --config <path> or default config path
• CLI overrides

Behavior notes:

• if config file does not exist, cannot parse, or cannot execute, ReqPack keeps fallback defaults
• most CLI overrides are last-writer-wins
• repeated --log-category flags accumulate, normalize, and dedupe
• --jobs and --jobs-max are mutually exclusive
• -Dproxy.<name>.default=<target> lowercases both proxy name and target

Invoking-user XDG Behavior

ReqPack resolves default XDG roots and ~ against invoking user home in this order:

• SUDO_USER
• SUDO_UID
• HOME
• passwd entry for current UID
• current working directory fallback

Meaning:

• under sudo, default config, data, cache, plugin, history, and self-update paths can still resolve to original user instead of /root
• explicit XDG_CONFIG_HOME, XDG_DATA_HOME, and XDG_CACHE_HOME still win when set
• default self-update link path ~/.local/bin/rqp follows same invoking-user logic

Path and Env Expansion

Path-like values usually support ~ expansion to invoking user home. Supported env-reference expansion is full-value only, not partial interpolation.

Behavior notes:

• supported forms are $NAME and ${NAME}
• missing env references resolve to empty string
• mixed strings such as prefix-$TOKEN-suffix are not interpolated

Example:

archives = {
  password = "$REQPACK_ARCHIVE_PASSWORD",
}

Common places with env-reference expansion:

• archives.password
• repository auth username
• repository auth password
• repository auth token
• repository auth sshKey
• repository auth headerName

Direct environment fallback also exists for archive password:

• REQPACK_ARCHIVE_PASSWORD

Fixed Runtime Caches

Not every runtime state area has a config key.

Host snapshot cache:

• path: $XDG_CACHE_HOME/reqpack/host/info.v1.json fallback
• TTL: 24 hours
• used by plugin-visible context.host and reqpack.host
• rqp host refresh forces live refresh
• successful self-update invalidates this cache

Top-level Fields

Root sections are:

• applicationName
• version
• logging
• security
• reports
• execution
• planner
• downloader
• registry
• interaction
• remote
• sbom
• rqp
• selfUpdate
• archives
• repositories
• history
• display

Metadata fields:

Field	Type	Default	Notes
applicationName	string	"ReqPack"	currently affects rqp version output prefix
version	string	build release ID	accepted by config loader, but current rqp version still prints binary build release ID

logging

Purpose: logger sinks, format, categories, structured logs.

Field	Type	Default	Notes
level	string	"info"	trace, debug, info, warn, error, critical; parser also accepts warning
consoleOutput	bool	false	logger console sink
fileOutput	bool	false	text file sink enable
filePath	path	reqpack.log	~ expands
structuredFileOutput	bool	false	JSONL sink enable
structuredFilePath	path	reqpack.jsonl	~ expands
captureDisplayEvents	bool	true	mirrors display events into structured logs
enabledCategories	string[]	[]	normalized lowercase, deduped
enableBacktrace	bool	false	spdlog backtrace
backtraceSize	integer	32	backtrace depth
pattern	string	[%^%l%$] %v	spdlog text-sink pattern

Behavior notes:

• empty enabledCategories means no category filter
• common inferred categories are general, plugin, display, and stdout
• structuredFileOutput writes JSON Lines with fields such as timestamp, severity, category, event, summary, cause, recommendation, details, source, scope, and context
• captureDisplayEvents only affects structured logs; it decides whether display session/item/table events are mirrored into JSONL
• if enabledCategories excludes display, display events are still filtered even when captureDisplayEvents = true
• pattern applies to text logger sinks, not structured JSON or display renderer output
• with active display attached, raw console sink is suppressed; warning-and-higher log events still reach display, and consoleOutput = true also mirrors lower-level log messages there
• --verbose currently enables logger console output; it does not change log level by itself

security

Purpose: audit policy, vulnerability data, thin-layer policy.

Field	Type	Default
enabled	bool	true
autoFetch	bool	true
requireThinLayer	bool	false
severityThreshold	string	"critical"
scoreThreshold	number	0.0
onUnsafe	string	"continue"
promptOnUnsafe	bool	false
allowUnassigned	bool	true
defaultGateway	string	"security"
cachePath	path	$XDG_CACHE_HOME/reqpack/security/cache fallback
indexPath	path	$XDG_DATA_HOME/reqpack/security/index fallback
osvDatabasePath	path	$XDG_DATA_HOME/reqpack/security/osv fallback
osvFeedUrl	string	https://storage.googleapis.com/osv-vulnerabilities
osvRefreshMode	string	"manual"
osvRefreshIntervalSeconds	integer	86400
osvOverlayPath	path	empty
ignoreVulnerabilityIds	string[]	[]
allowVulnerabilityIds	string[]	[]
ecosystemMap	map	{}
osvEcosystemMap	map	{}
gateways	map	{}
backends	map	{}
onUnresolvedVersion	string	"continue"
strictEcosystemMapping	bool	false
includeWithdrawnInReport	bool	false

Enum values:

• severityThreshold: low, medium, high, critical
• onUnsafe: continue, prompt, abort; parser also accepts ask and fail
• onUnresolvedVersion: continue, prompt, abort; parser also accepts ask and fail
• osvRefreshMode: manual, periodic, always

Important interactions:

• if indexPath is still default and osvDatabasePath changes, ReqPack aligns indexPath to same OSV DB path
• ecosystemMap entries are copied into osvEcosystemMap too
• if backends.osv is absent, ReqPack synthesizes it from top-level osv* fields
• thin-layer runtime exec enforcement requires both security.requireThinLayer = true and execution.checkVirtualFileSystemWrite = true

Policy behavior:

• defaultGateway is normalized lowercase and used when a gateway name is omitted
• onUnsafe = "prompt" enables prompting even if promptOnUnsafe = false
• sync_error findings always block
• unsupported_ecosystem findings block only when strictEcosystemMapping = true
• unresolved_version findings block only when onUnresolvedVersion = abort and prompt when onUnresolvedVersion = prompt
• findings at or above severityThreshold or scoreThreshold also trigger block-or-prompt disposition
• if prompt is required while interaction.interactive = false, ReqPack aborts instead of continuing
• includeWithdrawnInReport = false skips withdrawn advisories during vulnerability matching

Current caveats:

• security.enabled is accepted by config loader, but current validator/executor path does not use it as a global off-switch
• allowUnassigned is accepted by config loader, but current source sweep found no active runtime consumer

security.gateways.<name>

Field	Type	Default
enabled	bool	true
backends	string[]	[]

Gateway names are normalized lowercase.

security.backends.<name>

Field	Type	Default
enabled	bool	true
feedUrl	string/path	empty
refreshMode	string	manual
refreshIntervalSeconds	integer	86400
overlayPath	path	empty

Paths are expanded. Backend names are normalized lowercase.

reports

Purpose: validator report-generation hook.

Field	Type	Default
enabled	bool	false
format	string	"none"
outputPath	path	reqpack-report.json
includeValidationFindings	bool	true
includeDependencyGraph	bool	true

Enum values:

• none
• json
• cyclonedx

Current state from source:

• this section is not same thing as explicit rqp audit --output or rqp sbom --output
• reports.enabled only tells validator to call generateReport() during validation path
• Validator::generateReport() is still skeleton hook
• reports.format, reports.outputPath, includeValidationFindings, and includeDependencyGraph are accepted config and CLI surface, but current generator does not emit finished report artifacts yet

execution

Purpose: transaction, concurrency, mutation behavior.

Field	Type	Default
useTransactionDb	bool	true
deleteCommittedTransactions	bool	true
checkVirtualFileSystemWrite	bool	true
stopOnFirstFailure	bool	false
dryRun	bool	false
jobs	integer	1
jobsMode	string	"fixed"
transactionDatabasePath	path	$XDG_CACHE_HOME/reqpack/transactions fallback

Enum values:

• jobsMode: fixed, max

Important interactions:

• jobsMode = "max" resolves to std::thread::hardware_concurrency() or 1 fallback
• jobs must be positive
• --jobs and --jobs-max are mutually exclusive
• transaction DB behavior applies to mutating runs such as install, ensure, remove, and update
• interrupted active run is recovered before a new active run starts
• a run becomes committed only when every recorded item reaches success or committed; otherwise run becomes failed
• deleteCommittedTransactions removes committed run state after commit path finishes
• checkVirtualFileSystemWrite is also a preflight writeability gate, not only thin-layer helper

planner

Purpose: aliases, proxies, graph building, auto-download behavior.

Field	Type	Default
enableProxyExpansion	bool	true
autoDownloadMissingPlugins	bool	true
autoDownloadMissingDependencies	bool	true
buildDependencyDag	bool	true
topologicallySortGraph	bool	true
systemAliases	map<string,string>	{}
proxies	map	{}

Alias names and targets are normalized lowercase.

planner.proxies.<name>

Field	Type	Default
default	string	empty
targets	string[]	[]
options	map<string,string>	{}

Notes:

• proxy names and targets are normalized lowercase
• enableProxyExpansion = false prevents proxy-request expansion step
• CLI override -Dproxy.<name>.default=<target> changes only default

downloader

Purpose: download behavior and earliest explicit plugin sources.

Field	Type	Default
enabled	bool	true
followRedirects	bool	true
connectTimeoutSeconds	integer	10
requestTimeoutSeconds	integer	60
userAgent	string	ReqPack build user-agent
pluginSources	map<string,string>	{}

Plugin source keys are normalized lowercase.

Important interactions:

• pluginSources is earliest explicit registry-source layer
• later registry.sources, on-disk registry source files, and registry.overlayPath can override same source names

registry

Purpose: registry database, remote registry sync, plugin loading, source trust metadata.

Field	Type	Default
databasePath	path	$XDG_DATA_HOME/reqpack/registry fallback
remoteUrl	string	empty in struct, set by app defaults for normal runs
remoteBranch	string	main
remotePluginsPath	string	registry
overlayPath	path	empty
sources	map	{}
pluginDirectory	path	$XDG_DATA_HOME/reqpack/plugins fallback
autoLoadPlugins	bool	true
shutDownPluginsOnExit	bool	true

Notes:

• databasePath may point to directory or direct registry.lua file
• when databasePath is directory, ReqPack loads registry source file from <databasePath>/registry.lua
• in normal app startup, main registry remote URL is defaulted to https://github.com/Coditary/rqp-registry.git
• registry-source merge order is downloader.pluginSources, then registry.sources, then source file loaded from databasePath, then registry.overlayPath; later layers win
• if workspace contains local plugins/, and startup still uses built-in default plugin directory with no explicit --config or --plugin-dir, ReqPack switches registry.pluginDirectory to workspace ./plugins
• even when configured plugin directory remains elsewhere, ReqPack still scans distinct workspace ./plugins at runtime
• if configured and workspace plugin dirs both contain same plugin ID, later workspace scan shadows earlier script path
• built-in rqp is reserved and cannot be replaced from scanned directories
• autoLoadPlugins = false prevents implicit plugin init() during command execution
• shutDownPluginsOnExit = false skips plugin shutdown() during registry teardown

registry.sources.<name>

Accepted short form:

registry = {
  sources = {
    demo = "https://example.test/demo.lua",
  },
}

Accepted full form fields:

Field	Type	Notes
source / url / path / target	string	first present field becomes source
alias	bool	aliases point to source name, not path
description	string	optional metadata
role	string	normalized lowercase
capabilities	string[]	normalized lowercase
ecosystemScopes	string[]	normalized lowercase
writeScopes	table[]	each entry needs kind, optional value
networkScopes	table[]	entries can contain host, scheme, pathPrefix
privilegeLevel	string	normalized lowercase
scriptSha256	string	normalized lowercase
bootstrapSha256	string	normalized lowercase

Source-file behavior:

• on-disk registry source files may return table or set global registry
• if returned or global table contains sources = { ... }, ReqPack uses that subtable
• otherwise ReqPack treats root table itself as source map
• non-alias path values get ~ expansion when loaded

interaction

Purpose: prompting behavior.

Field	Type	Default
interactive	bool	true
promptBeforeUnsafeActions	bool	false
promptBeforeMissingPluginDownload	bool	false
promptBeforeMissingDependencyDownload	bool	false

CLI --non-interactive overrides interactive to false.

Current behavior notes:

• interactive currently feeds security confirmation prompts and archive-extraction prompting
• promptBeforeUnsafeActions, promptBeforeMissingPluginDownload, and promptBeforeMissingDependencyDownload are accepted config fields, but current source sweep found no active runtime consumer beyond config loading

remote

Purpose: baseline remote-server defaults.

Field	Type	Default
readonly	bool	false
maxConnections	integer	16

serve --remote uses these unless explicit CLI flags override them.

sbom

Purpose: default SBOM export behavior.

Field	Type	Default
defaultFormat	string	"table"
defaultOutputPath	path	empty
prettyPrint	bool	true
includeDependencyEdges	bool	true
skipMissingPackages	bool	false

Enum values:

• table
• json
• cyclonedx-json
• cyclonedx

Important notes from source:

• defaultOutputPath is active and used by SBOM exporter
• includeDependencyEdges is active and controls JSON/CycloneDX dependency sections
• skipMissingPackages is active via CLI/config override path
• skipMissingPackages only suppresses unresolved packages without explicit version; explicitly versioned specifiers still remain hard missing-package failures
• prettyPrint is accepted by config loader and CLI override surface, but current exporter code does not read it
• explicit CLI format inference still wins over config defaults, for example --output without --format selects cyclonedx-json

rqp

Purpose: native ReqPack package repositories and state.

Field	Type	Default
repositories	string[]	[]
statePath	path	$XDG_DATA_HOME/reqpack/rqp/state fallback
systemAliases	map<string,string[]>	{}

Notes:

• systemAliases values must be strict string arrays or config load falls back
• do not confuse rqp.repositories with general repositories table

selfUpdate

Purpose: rqp update self-update source and install paths.

Field	Type	Default
repoUrl	string	https://github.com/Coditary/ReqPack.git
releaseApiBaseUrl	string	https://api.github.com
releaseTag	string	latest
binaryDirectory	path	$XDG_DATA_HOME/reqpack/self/bin fallback
linkPath	path	~/.local/bin/rqp

Current behavior:

• self-update mode is used only by rqp update with no system argument and no --all
• repoUrl must parse into release owner and repository name
• releaseApiBaseUrl is trimmed of trailing /
• releaseTag = "latest" uses latest-release API; any other tag uses tagged-release API path
• supported auto-selected release targets are currently x86_64-linux, aarch64-linux, x86_64-darwin, and aarch64-darwin
• expected release asset name is rqp-<tag>-<target>.tar.gz
• extraction currently shells out to tar
• installed bundle path becomes <binaryDirectory>/rqp-<sanitized-tag>-<target>
• linkPath is replaced atomically to point at installed rqp
• successful self-update invalidates host snapshot cache

archives

Purpose: encrypted archive password source.

Field	Type	Default
password	string	empty

If empty, ReqPack falls back to environment variable REQPACK_ARCHIVE_PASSWORD.

repositories

Purpose: plugin-consumed package repositories grouped by ecosystem.

Shape:

repositories = {
  maven = {
    {
      id = "central",
      url = "https://repo1.maven.org/maven2",
      priority = 10,
      enabled = true,
      type = "maven",
      auth = { type = "none" },
      validation = { checksum = "warn", tlsVerify = true },
      scope = { include = { "com.example:*" } },
      snapshots = false,
    },
  },
}

Repository entry fields

Field	Type	Default
id	string	required
url	string	required
priority	integer	100
enabled	bool	true
type	string	empty
auth	table	defaults to type = none
validation	table	checksum warn, TLS verify true
scope	table	empty include/exclude

Unknown extra fields are preserved as typed extras if they are:

• string
• bool
• number
• string array

auth

type values:

• none
• basic
• token
• ssh

Supported auth fields:

• username
• password
• token
• sshKey
• headerName

Validation rules:

• none rejects any extra auth credentials
• basic requires both username and password
• token requires token
• ssh requires sshKey

Repository-loading notes:

• auth fields username, password, token, and headerName support full-value env references
• sshKey supports env reference plus ~ expansion
• invalid auth config causes whole repository entry to be skipped
• duplicate repository id values inside same ecosystem keep first valid entry and skip later duplicates

validation

Field	Type	Default
checksum	string	warn
tlsVerify	bool	true

checksum values:

• fail
• warn
• ignore

Parser also accepts warning for warn.

scope

Field	Type	Default
include	string[]	[]
exclude	string[]	[]

ReqPack sorts repository entries by ascending priority before exposing them to plugin runtime.

history

Purpose: append-only history log and installed-state tracking.

Field	Type	Default
enabled	bool	true
trackInstalled	bool	true
historyPath	path	$XDG_DATA_HOME/reqpack/history fallback
maxLines	integer	0
maxSizeMb	number	0.0

Important behavior:

• historyPath is directory holding both history.jsonl and installed-state database files
• enabled controls append-only event log only
• trackInstalled controls current installed-state snapshot used by snapshot
• trackInstalled is independent from enabled
• installed-state tracking can stay on even if append-only history logging is reduced
• tracked state is updated from successful install, ensure, remove, and update actions
• after successful mutating runs, ReqPack may resync installed state per affected system by calling plugin list()
• security gateway systems are skipped during installed-state resync
• trimming affects only history.jsonl, not installed-state snapshot data
• maxLines = 0 and maxSizeMb = 0.0 disable trimming
• when both limits are set, ReqPack keeps newest entries and uses stricter active limit

display

Purpose: plain vs color rendering and color rules.

display

Field	Type	Default
renderer	string	plain
colors	table	default built-in scheme

renderer values:

• plain
• color
• colour

display.colors

Key	Default
rule	empty
header	bold
summaryOk	bold green
summaryFail	bold red
barFill	green
barEmpty	empty
barOuter	empty
step	cyan
successMarker	bold green
failureMarker	bold red
message	empty

Values are formatter/color spec strings consumed by color display layer. plain renderer ignores them.

CLI Override Summary

Override behavior:

• CLI overrides are last layer over file config
• repeated --log-category values accumulate; most other overrides replace previous value
• install --stdin applies per-line overrides cumulatively across later lines in same batch
• serve --stdin applies each line's overrides against startup config for that line only
• --config only changes which file is loaded during initial startup; later override application does not reload another config file

High-value CLI overrides include:

• --config
• --log-level
• --log-console
• --no-log-console
• --verbose
• --log-pattern
• --log-file
• --structured-log-file
• --log-capture-display
• --no-log-capture-display
• --log-category
• --backtrace
• --registry
• --registry-path
• --plugin-dir
• --no-auto-load-plugins
• --no-proxy-expansion
• --dry-run
• --jobs
• --jobs-max
• --stop-on-first-failure
• --no-transaction-db
• --non-interactive
• --archive-password
• --prompt-on-unsafe
• --abort-on-unsafe
• --severity-threshold
• --score-threshold
• --osv-db
• --osv-feed
• --osv-refresh
• --osv-refresh-interval
• --osv-overlay
• --ignore-vuln
• --allow-vuln
• --fail-on-unresolved-version
• --prompt-on-unresolved-version
• --strict-ecosystem-mapping
• --include-withdrawn-in-report
• --report
• --report-format
• --report-output
• --sbom-format
• --sbom-output
• --sbom-no-pretty
• --sbom-no-dependency-edges
• --sbom-skip-missing-packages
• --sbom-fail-on-missing-package
• -Dproxy.<name>.default=<target>

Related Pages

• Configuration
• Security, Audit, and SBOM
• Output and Report Formats
• Remote Protocol Reference
• Data, State, and Trust

Prev: Configuration | Up: User Guide | Next: Security, Audit, and SBOM