User Guide Configuration

Configuration

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

ReqPack uses Lua config files plus CLI overrides. This page covers where files live, how precedence works, and which similar-looking concepts are easy to confuse.

Config File Locations

ReqPack follows XDG paths.

Main config

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

Remote profiles and users

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

Data locations you will care about

• plugins: $XDG_DATA_HOME/reqpack/plugins
• registry: $XDG_DATA_HOME/reqpack/registry
• repository cache: $XDG_DATA_HOME/reqpack/repos
• history: $XDG_DATA_HOME/reqpack/history
• native rqp state: $XDG_DATA_HOME/reqpack/rqp/state
• self-update repo/build/bin: $XDG_DATA_HOME/reqpack/self/...
• OSV database: $XDG_DATA_HOME/reqpack/security/osv

Cache locations

• transactions: $XDG_CACHE_HOME/reqpack/transactions
• security cache: $XDG_CACHE_HOME/reqpack/security/cache
• host snapshot cache: $XDG_CACHE_HOME/reqpack/host/info.v1.json

Three Similar Concepts That Are Easy to Confuse

• registry: where ReqPack gets plugin wrappers and registry metadata.
• repositories: per-ecosystem package repositories passed into plugins such as Maven or internal wrappers.
• rqp.repositories: native package indexes used only by built-in rqp package manager.

If you are changing where plugins come from, use registry. If you are changing where a plugin looks for packages, use repositories. If you are changing where native rqp packages come from, use rqp.repositories.

Config Precedence

ReqPack applies configuration in this order:

1. built-in defaults,
2. config.lua,
3. CLI overrides such as --config, --registry, --jobs, --non-interactive, --archive-password, and security flags.

That means config.lua is your baseline, while CLI flags are best for ad-hoc runs, CI jobs, and local experiments.

Minimal Daily-use Example

return {
  interaction = {
    interactive = true,
  },
  execution = {
    jobs = 4,
    jobsMode = "fixed",
  },
  security = {
    onUnsafe = "prompt",
    severityThreshold = "critical",
  },
  registry = {
    remoteUrl = "https://github.com/Coditary/rqp-registry.git",
  },
  selfUpdate = {
    branch = "main",
    linkPath = "~/.local/bin/rqp",
  },
}

High-value Config Areas

Area	Important keys	Why it matters
interaction	interactive	Controls prompting and human-friendly runs
execution	jobs, jobsMode, dryRun, stopOnFirstFailure	Controls concurrency and failure behavior
security	onUnsafe, severityThreshold, scoreThreshold, osv*, ignoreVulnerabilityIds, allowVulnerabilityIds	Controls audit and install/update safety policy
registry	databasePath, remoteUrl, remoteBranch, remotePluginsPath, pluginDirectory, overlayPath, sources	Controls where plugins come from
planner	systemAliases, proxies, autoDownloadMissingPlugins, autoDownloadMissingDependencies	Controls aliasing, proxy resolution, and missing-plugin behavior
repositories	per-ecosystem repository entries	Lets plugins consume custom package repositories
rqp	repositories, statePath	Controls native ReqPack package repositories and installed state
remote	readonly, maxConnections	Baseline server behavior for serve --remote
selfUpdate	repoUrl, branch, repoPath, buildPath, binaryDirectory, linkPath	Controls self-update source and build locations
history	enabled, trackInstalled, historyPath	Needed for snapshots and installed-state tracking
logging	level, consoleOutput, fileOutput, structuredFileOutput, enabledCategories	Useful for debugging and CI logs
display	renderer, colors	Controls plain vs color display output

Planner Aliases and Proxies

Two planner features are especially useful when you want to adapt ReqPack behavior without changing plugin code.

System aliases

planner = {
  systemAliases = {
    brew = "apt",
  },
}

This maps one system name to another at request-resolution time.

Proxy targets

planner = {
  proxies = {
    java = {
      default = "maven",
      targets = { "maven", "gradle" },
      options = {
        strategy = "default-first",
      },
    },
  },
}

This is how proxy plugins such as plugins/java/java.lua choose their real target ecosystem.

You can override a proxy default from the CLI too:

ReqPack -Dproxy.java.default=gradle install java org.junit:junit:4.13.2

Registry and Plugin Source Config

ReqPack can use several plugin-source layers at once.

Important keys:

registry = {
  databasePath = "~/.local/share/reqpack/registry",
  remoteUrl = "https://github.com/Coditary/rqp-registry.git",
  remoteBranch = "main",
  remotePluginsPath = "registry",
  overlayPath = "~/reqpack/registry-overlay.lua",
  pluginDirectory = "~/.local/share/reqpack/plugins",
  autoLoadPlugins = true,
  shutDownPluginsOnExit = true,
  sources = {
    dnf = "https://example.test/dnf.lua",
  },
}

Notes:

• databasePath is local registry metadata store; it is not same thing as pluginDirectory.
• databasePath can point to a directory or directly to registry.lua.
• pluginDirectory is where refreshed Lua plugin scripts and bundle files are materialized and loaded from.
• when ReqPack runs inside a workspace that has a local plugins/ directory, that directory is auto-scanned too.
• overlayPath is useful when you want to patch or override upstream registry entries locally.

Ecosystem-specific Repositories

Plugins can consume repository definitions from config.repositories. Entries are grouped by ecosystem name, sorted by priority, and exposed to plugin code through context.repositories.

Example:

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

Notes:

• auth.type can be none, basic, token, or ssh.
• auth fields support environment-style references such as ${MY_REPO_TOKEN}.
• plugin-specific extra fields are allowed and passed through unchanged.

Advanced but Useful CLI Overrides

These are especially useful during development and CI.

ReqPack --config ~/reqpack/dev.lua list apt
ReqPack --registry ~/reqpack-dev/registry update --all
ReqPack --plugin-dir ./plugins list dnf
ReqPack --jobs 8 update --all
ReqPack --jobs-max update apt --all
ReqPack --no-proxy-expansion install java org.junit:junit:4.13.2
ReqPack --no-auto-load-plugins list dnf
ReqPack --archive-password secret install rqp ./artifact.rqp

Environment-sensitive Values

ReqPack expands ~ for many path-like config values. Environment-style expansion is supported in places where secrets are common, especially when whole value is a reference such as $REQPACK_ARCHIVE_PASSWORD or ${MY_REPO_TOKEN}:

• archives.password
• repository auth fields such as token, username, password, and sshKey

Example:

archives = {
  password = "$REQPACK_ARCHIVE_PASSWORD",
}

There is also a direct environment fallback for encrypted archives:

• REQPACK_ARCHIVE_PASSWORD

ReqPack does not do partial string interpolation here. Use full-value references rather than mixed literals.

Recommended Defaults

For local interactive use:

interaction = { interactive = true }
execution = { jobsMode = "max" }
security = { onUnsafe = "prompt", severityThreshold = "high" }
history = { enabled = true, trackInstalled = true }

For CI:

interaction = { interactive = false }
execution = { stopOnFirstFailure = true }
security = {
  onUnsafe = "abort",
  strictEcosystemMapping = true,
}
logging = {
  structuredFileOutput = true,
  structuredFilePath = "reqpack.jsonl",
}

Note:

• history.trackInstalled controls installed-state tracking used by snapshot and can stay useful even if append-only history logging is reduced.

Related Pages

• Getting Started
• Security, Audit, and SBOM
• Remote Mode
• Data, State, and Trust

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