User Guide Getting Started

Getting Started

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

This page covers first-run setup, command syntax, manifests, local targets, and day-one workflow.

What ReqPack Does

ReqPack gives you one CLI for:

• installing packages,
• removing packages,
• updating packages or plugin wrappers,
• listing and searching packages,
• auditing vulnerabilities,
• exporting SBOMs,
• snapshotting installed state into reqpack.lua.

The actual work is still done by plugins such as dnf, maven, sys, and the built-in rqp manager.

Install or Build ReqPack

Option 1: use a release binary

tar -xzf "rqp-vX.Y.Z-x86_64-linux.tar.gz"
chmod +x ReqPack
mkdir -p ~/.local/bin
ln -sf "$(pwd)/ReqPack" ~/.local/bin/rqp

If you prefer the binary name ReqPack, put the binary directly on PATH instead of symlinking it to rqp.

Option 2: build from source on Ubuntu or Debian

sudo apt-get update
sudo apt-get install -y --no-install-recommends \
  build-essential ca-certificates cmake curl git pkg-config \
  libboost-dev libcli11-dev libcurl4-openssl-dev libfmt-dev \
  liblua5.4-dev libspdlog-dev libssl-dev libzstd-dev

git clone https://github.com/Coditary/ReqPack.git
cd ReqPack
git clone --depth 1 -b v3.3.0 https://github.com/ThePhD/sol2.git /tmp/reqpack-sol2
cmake -S . -B build -DSOL2_INCLUDE_DIR=/tmp/reqpack-sol2/include
cmake --build build --parallel --target ReqPack reqpack_test_targets
ctest --test-dir build --output-on-failure

Option 3: build from source on macOS

brew install cli11 fmt spdlog boost zstd openssl@3 lua@5.4 ccache

git clone https://github.com/Coditary/ReqPack.git
cd ReqPack
git clone --depth 1 -b v3.3.0 https://github.com/ThePhD/sol2.git /tmp/reqpack-sol2

BREW_PREFIX="$(brew --prefix)"
OPENSSL_PREFIX="$(brew --prefix openssl@3)"
LUA_PREFIX="$(brew --prefix lua@5.4)"
ZSTD_PREFIX="$(brew --prefix zstd)"

cmake -S . -B build \
  -DSOL2_INCLUDE_DIR=/tmp/reqpack-sol2/include \
  -DCMAKE_PREFIX_PATH="${BREW_PREFIX};${OPENSSL_PREFIX};${LUA_PREFIX};${ZSTD_PREFIX}" \
  -DOPENSSL_ROOT_DIR="${OPENSSL_PREFIX}" \
  -DREQPACK_ZSTD_LIBRARY="${ZSTD_PREFIX}/lib/libzstd.dylib" \
  -DLUA_INCLUDE_DIR="${LUA_PREFIX}/include/lua" \
  -DLUA_LIBRARIES="${LUA_PREFIX}/lib/liblua.5.4.dylib"

cmake --build build --parallel --target ReqPack reqpack_test_targets
ctest --test-dir build --output-on-failure

Run it with:

./build/ReqPack --help

First Commands

ReqPack install apt curl git
ReqPack install npm express lodash brew jq
ReqPack install apt:curl npm:express

ReqPack remove apt curl
ReqPack update --all
ReqPack list apt
ReqPack search dnf python3
ReqPack info npm express
ReqPack outdated

Parsing rule:

• each bare system token starts a new group,
• packages after that token belong to that system until next system token appears.

So ReqPack install npm express lodash brew jq means: install express and lodash through npm, then install jq through brew.

For scripts and CI, scoped form such as apt:curl npm:express is usually clearest because it removes grouping ambiguity.

Core commands

• install: install packages, local targets, or manifest contents.
• remove: remove packages.
• update: update ReqPack itself, refresh plugin wrappers, or update packages.
• search: search available packages.
• list: list installed packages.
• info: show detailed package metadata.
• outdated: show newer versions.
• ensure: install plugin prerequisites.

Install From a Manifest

ReqPack supports project manifests named reqpack.lua. This file is project input. It is not plugin code, and it is not same reqpack.lua format used inside native .rqp packages.

Minimal example:

return {
  packages = {
    { system = "dnf", name = "curl" },
    { system = "npm", name = "express", version = "4.18.0" },
  }
}

Install from current directory or another project directory:

ReqPack install .
ReqPack install ./myproject
ReqPack install /absolute/path/to/project

Install Local Files and Archives

ReqPack can install local targets too. Within one system group, use either package names or one local target, not both.

Examples:

ReqPack install brew ./my-formula.rb
ReqPack install rqp ./my-tool.rqp

If a plugin declares file extensions, ReqPack can infer the system automatically for local files. Examples from current plugins:

• dnf claims .rpm
• rqp claims .rqp

If ReqPack cannot infer the system, use explicit form:

ReqPack install <system> <path>

Snapshot and Restore

ReqPack can snapshot installed state into a portable reqpack.lua manifest:

ReqPack snapshot --output reqpack.lua
ReqPack install .

Important:

• snapshot reads from ReqPack history state, not from arbitrary package-manager state.
• history.trackInstalled must be enabled for this to work well.

Automation Through Stdin

There are two useful stdin modes.

Install-only batch mode

printf 'install dnf curl\ninstall npm express\n' | ReqPack install --stdin

Use this when every stdin line is a full install command.

Mixed-command stdin server

printf 'install dnf curl\nlist dnf\n' | ReqPack serve --stdin

Use this when you want a local long-running command reader that accepts mixed commands, not just install lines.

Refresh Host Metadata

Plugins receive host information through context.host and reqpack.host. ReqPack caches that snapshot and can refresh it on demand:

ReqPack host refresh

This is useful after major OS or environment changes, or while developing plugins that branch on host details.

Useful Flags You Will Use Often

• --dry-run: plan only, no execution.
• --non-interactive: disable prompts.
• --stop-on-first-failure: stop after first failing system.
• --jobs <n>: fixed worker count.
• --jobs-max: use all logical CPU threads.
• --config <path>: custom config file.
• --registry <path>: custom registry source path.
• --archive-password <value>: password for encrypted archives.

Examples:

ReqPack --dry-run install apt curl git
ReqPack --config ~/.config/reqpack/dev.lua list apt
ReqPack --registry ~/reqpack-dev/registry update --all
ReqPack --jobs-max update apt --all

Self-update and Wrapper Refresh

ReqPack update has three different meanings.

ReqPack update
ReqPack update --all
ReqPack update dnf
ReqPack update dnf --all
ReqPack update sys pip

• ReqPack update rebuilds ReqPack itself from the configured Git repository.
• ReqPack update --all refreshes all known registry-backed plugin wrappers.
• ReqPack update <system> refreshes one registry-backed plugin wrapper.
• ReqPack update <system> --all updates all packages for that ecosystem.
• ReqPack update sys <tool> updates a package-manager binary through the sys plugin layer.

Self-update requires local Git and local build tooling. Release-binary users still need a working toolchain if they want self-update to succeed. Built-in rqp is not a registry-backed wrapper, so wrapper-refresh behavior mainly applies to Lua plugin systems.

Related Pages

• Configuration
• Security, Audit, and SBOM
• Remote Mode
• Using Native rqp Packages

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