User Guide Getting Started

Getting Started

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

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

curl -fsSL https://raw.githubusercontent.com/Coditary/ReqPack/main/install.sh | sh

install.sh detects host target, downloads matching release binary, installs it to ~/.local/bin/rqp, writes default self-update config if missing, then runs initial wrapper refresh and host refresh.

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/rqp --help

First Commands

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

rqp remove apt curl
rqp update --all
rqp list apt
rqp search dnf python3
rqp info npm express
rqp 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 rqp 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:

rqp install .
rqp install ./myproject
rqp 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:

rqp install brew ./my-formula.rb
rqp 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:

rqp install <system> <path>

Snapshot and Restore

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

rqp snapshot --output reqpack.lua
rqp install .

Important:

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

Build Native .rqp Packages

If you want ReqPack-native package artifact instead of installing through external manager:

rqp pack ./my-package
rqp pack ./my-package --output ./dist/my-package.rqp

Builtin pack expects package project directory with metadata.json, reqpack.lua, and hook scripts. For full layout and payload options, see Building rqp Packages and Repositories.

Automation Through Stdin

There are two useful stdin modes.

Install-only batch mode

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

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

Mixed-command stdin server

printf 'install dnf curl\nlist dnf\n' | rqp 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:

rqp 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:

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

Self-update and Wrapper Refresh

rqp update has three different meanings.

rqp update
rqp update --all
rqp update dnf
rqp update dnf --all
rqp update sys pip

• rqp update downloads ReqPack release binary for current host from configured release source.
• rqp update --all refreshes all known registry-backed plugin wrappers.
• rqp update <system> refreshes one registry-backed plugin wrapper.
• rqp update <system> --all updates all packages for that ecosystem.
• rqp update sys <tool> updates a package-manager binary through the sys plugin layer.

Built-in rqp is not a registry-backed wrapper, so wrapper-refresh behavior mainly applies to Lua plugin systems.

Related Pages

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

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