Skip to content

User Guide Configuration

Jump to bottom
Leonard Ramminger edited this page May 10, 2026 · 5 revisions

Configuration

Prev: Command Reference | Up: User Guide | Next: Configuration Reference

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 binaries: $XDG_DATA_HOME/reqpack/self/bin
  • 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.

Important path detail:

  • default XDG paths and ~ expansion follow invoking user home, even under sudo, unless explicit XDG_* vars override them

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 = {
    releaseApiBaseUrl = "https://api.github.com",
    releaseTag = "latest",
    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, releaseApiBaseUrl, releaseTag, binaryDirectory, linkPath Controls self-update release source and install 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/run.lua choose their real target ecosystem.

You can override a proxy default from the CLI too:

rqp -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.
  • later source layers win: downloader.pluginSources, then registry.sources, then registry file from databasePath, then overlayPath
  • if both configured plugin dir and workspace ./plugins contain same plugin id, workspace scan wins at runtime
  • 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 Execution And Planner Toggles

Useful less-obvious keys and current defaults:

execution = {
  useTransactionDb = true,
  deleteCommittedTransactions = true,
  checkVirtualFileSystemWrite = true,
  stopOnFirstFailure = false,
  jobs = 1,
  jobsMode = "fixed",
}

planner = {
  enableProxyExpansion = true,
  autoDownloadMissingPlugins = true,
  autoDownloadMissingDependencies = true,
  topologicallySortGraph = true,
}

registry = {
  autoLoadPlugins = true,
  shutDownPluginsOnExit = true,
}

Meaning:

  • execution.useTransactionDb: persist active mutating runs for recovery after interruption
  • execution.deleteCommittedTransactions: remove fully committed runs after success
  • execution.checkVirtualFileSystemWrite: enables runtime write-policy checks used by thin-layer exec enforcement
  • planner.enableProxyExpansion: lets proxy plugins rewrite requests through resolveProxyRequest()
  • planner.autoDownloadMissingPlugins: fetch missing plugin wrappers during planning
  • planner.autoDownloadMissingDependencies: fetch missing plugin dependencies declared in bundles
  • planner.topologicallySortGraph: stabilize dependency execution order
  • registry.autoLoadPlugins: call loadPlugin() automatically when command needs plugin
  • registry.shutDownPluginsOnExit: call plugin shutdown() on registry teardown

Important thin-layer detail:

  • runtime exec policy is only enforced when both security.requireThinLayer = true and execution.checkVirtualFileSystemWrite = true

Transaction Database

Default transaction database path is:

  • $XDG_CACHE_HOME/reqpack/transactions

Mutating runs use transaction DB when execution.useTransactionDb = true.

High-level behavior:

  • run opens before execution begins
  • items move through statuses such as planned, running, success, failed, committed
  • interrupted run is recovered on next execution attempt before new active run starts
  • if every item succeeds, run becomes committed
  • otherwise run state becomes failed

This is why accurate getMissingPackages() implementation matters for plugin authors: recovery logic uses it to decide which recorded items still need work.

Advanced but Useful CLI Overrides

These are especially useful during development and CI.

rqp --config ~/reqpack/dev.lua list apt
rqp --registry ~/reqpack-dev/registry update --all
rqp --plugin-dir ./plugins list dnf
rqp --jobs 8 update --all
rqp --jobs-max update apt --all
rqp --no-proxy-expansion install java org.junit:junit:4.13.2
rqp --no-auto-load-plugins list dnf
rqp --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.
  • source-backed caveats such as load-only config fields, host-cache TTL, and self-update target rules are documented in Configuration Reference.

Related Pages

Prev: Command Reference | Up: User Guide | Next: Configuration Reference

Overview

User Guide

Extending ReqPack

Architecture

Clone this wiki locally