Skip to content

User Guide Command Reference

Jump to bottom
Leonard Ramminger edited this page May 10, 2026 · 1 revision

Command Reference

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

This page is source-backed CLI reference for ReqPack commands. Use it when you need exact syntax, parsing rules, defaults, or command-specific edge cases.

Global Syntax

Top-level usage is:

rqp <command> <system> [packages...] [additional systems/packages...] [flags...]

Global flags available across commands include:

  • -h, --help
  • -v, --verbose
  • --config <path>
  • --registry <path>
  • --archive-password <value>
  • logging flags such as --log-level, --log-file, --structured-log-file, --log-category, --backtrace

Shared Parsing Rules

Grouped systems

Bare system token starts new package group.

Example:

rqp install npm express lodash brew jq

Means:

  • install express and lodash through npm
  • install jq through brew

Scoped packages

Scoped form removes grouping ambiguity:

rqp install apt:curl npm:express

ReqPack treats system:package as package bound to explicit system if prefix matches known system.

Local files and URLs

install can target:

  • local regular files
  • local directories
  • URLs starting with http://, https://, or file://

Within one system group, local target and package names cannot be mixed.

Manifest paths

install and audit support manifest-path mode. If first non-flag argument after command resolves to directory or reqpack.lua path, ReqPack loads manifest entries instead of normal grouped package parsing.

Supported examples:

rqp install .
rqp install ./project
rqp audit ./reqpack.lua

Default systems when omitted

If no system is provided:

  • ensure targets all known primary systems
  • list targets all known primary systems
  • outdated targets all known primary systems
  • audit targets all known primary systems
  • sbom builds one aggregate request without explicit system filtering
  • snapshot runs without system argument

Output format inference

  • rqp sbom --output <file> without --format uses cyclonedx-json
  • rqp audit --output <file> without --format uses:
    • sarif when extension is .sarif
    • otherwise cyclonedx-vex-json

install

Syntax:

rqp install <system> [<package>...] [options]
rqp install <system> <local-path> [options]
rqp install <system1>:<package> <system2>:<package> [options]
rqp install <dir-path> [options]
rqp install --stdin [options]

What it does:

  • install packages through one or more plugins
  • install one local target through a plugin
  • install packages from reqpack.lua manifest
  • batch multiple install commands from stdin

Key flags:

  • --stdin
  • --dry-run
  • --prompt-on-unsafe
  • --abort-on-unsafe
  • --severity-threshold <low|medium|high|critical>
  • --score-threshold <0.0-10.0>
  • --fail-on-unresolved-version
  • --prompt-on-unresolved-version
  • --archive-password <value>
  • --jobs <n>
  • --jobs-max
  • --stop-on-first-failure
  • --non-interactive

Important behavior:

  • If first non-flag argument is manifest path, ReqPack groups manifest entries by system.
  • If system is omitted for local file or URL target, runtime tries to infer plugin from file extension.
  • rqp install --stdin accepts only install ... lines.
  • Empty lines and comment lines starting with # are ignored in stdin mode.

Examples:

rqp install apt curl git
rqp install apt:curl npm:express
rqp install rqp ./my-tool.rqp
rqp install .
printf 'install dnf curl\ninstall npm express\n' | rqp install --stdin

remove

Syntax:

rqp remove <system> [<package>...] [options]
rqp remove <system1>:<package> <system2>:<package> [options]

What it does:

  • remove packages from one or more systems

Key flags:

  • --dry-run
  • --stop-on-first-failure
  • --non-interactive

Examples:

rqp remove apt curl
rqp remove npm express brew jq
rqp remove apt:curl npm:lodash

update

Syntax:

rqp update [options]
rqp update <system> [<package>...] [options]
rqp update <system1>:<package> <system2>:<package> [options]

What it does:

update has four distinct modes.

  1. rqp update self-update ReqPack itself from configured release source.
  2. rqp update --all refresh all known non-builtin plugin wrappers.
  3. rqp update <system> refresh one plugin wrapper when no package list is given.
  4. rqp update <system> [packages...] or rqp update <system> --all update packages through that system.

Key flags:

  • --all
  • --dry-run
  • --prompt-on-unsafe
  • --abort-on-unsafe
  • --severity-threshold
  • --score-threshold
  • --stop-on-first-failure
  • --non-interactive

Important behavior:

  • rqp update with no non-flag arguments and no --all is treated as self-update.
  • rqp update --all is not self-update; it refreshes all known plugin wrappers.
  • rqp update sys <tool> updates package-manager binary through sys plugin layer.
  • rqp update <system> without packages can mean plugin wrapper refresh, not package update.
  • self-update currently auto-selects only x86_64-linux, aarch64-linux, x86_64-darwin, and aarch64-darwin release targets.
  • self-update expects release asset name rqp-<tag>-<target>.tar.gz and uses configured selfUpdate.linkPath symlink as final entrypoint.

Examples:

rqp update
rqp update --all
rqp update pip
rqp update pip --all
rqp update sys pip
rqp update apt:curl npm:express

search

Syntax:

rqp search <system> <query> [options]

Key flags:

  • --arch <value> repeatable
  • --type <value> repeatable
  • --non-interactive

Examples:

rqp search apt curl
rqp search brew "json tool"
rqp search dnf python3 --arch noarch --type doc

list

Syntax:

rqp list [<system>] [options]

What it does:

  • list installed packages for one system or all known primary systems

Key flags:

  • --arch <value> repeatable
  • --type <value> repeatable
  • --non-interactive

Examples:

rqp list
rqp list apt
rqp list dnf --arch x86_64

info

Syntax:

rqp info <system> <package> [options]

What it does:

  • show detailed package info through plugin info()

Key flags:

  • --non-interactive

Examples:

rqp info apt curl
rqp info npm express

ensure

Syntax:

rqp ensure [<system>...] [options]

What it does:

  • ensure plugin requirements are installed
  • with no systems, checks all known systems

Key flags:

  • --dry-run
  • --stop-on-first-failure
  • --non-interactive

Examples:

rqp ensure
rqp ensure apt brew

sbom

Syntax:

rqp sbom [<system>...] [options]

What it does:

  • export package inventory from installed packages and resolved package graph

Key flags:

  • --format <table|json|cyclonedx-json>
  • --output <path>
  • --wide
  • --no-wrap
  • --force
  • --sbom-skip-missing-packages
  • --non-interactive

Important behavior:

  • With no systems, exporter builds aggregate graph.
  • If --output is given without --format, format becomes cyclonedx-json.
  • If no explicit output path exists on request, exporter falls back to sbom.defaultOutputPath from config.

Examples:

rqp sbom
rqp sbom apt npm
rqp sbom --format json
rqp sbom --output sbom.json

audit

Syntax:

rqp audit [<system>...] [options]
rqp audit <system1>:<package> <system2>:<package> [options]
rqp audit <dir-path> [options]
rqp audit <manifest-path>/reqpack.lua [options]

What it does:

  • audit installed packages, explicit package specs, or manifest contents for findings

Key flags:

  • --format <table|json|cyclonedx-vex-json|sarif>
  • --output <path>
  • --wide
  • --no-wrap
  • --force
  • --non-interactive

Important behavior:

  • Without system, audits all known primary systems.
  • With system but no package list, audits installed packages reported by that system.
  • Manifest input is supported in same path-detection style as install.
  • Without --output, exit code is 1 when findings exist.
  • With --output, findings are exported but that condition does not change exit code by itself.
  • If --output is given without --format, .sarif selects SARIF, all other extensions select CycloneDX VEX JSON.

Examples:

rqp audit
rqp audit npm react
rqp audit npm:react maven:org.junit:junit
rqp audit .
rqp audit --format sarif --output audit.sarif

outdated

Syntax:

rqp outdated [<system>] [options]

What it does:

  • show packages with newer versions available
  • with no system, checks all known primary systems

Key flags:

  • --arch <value> repeatable
  • --type <value> repeatable
  • --non-interactive

Examples:

rqp outdated
rqp outdated dnf
rqp outdated dnf --type doc

host

Syntax:

rqp host refresh

What it does:

  • force live refresh of cached host snapshot used by plugins through context.host and reqpack.host

Current subcommand:

  • refresh

Output includes:

  • refresh confirmation
  • host OS family
  • host arch
  • cache file path

Host cache note:

  • normal host cache TTL is 24 hours; refresh bypasses it and rewrites cache immediately

version

Syntax:

rqp version
rqp --version

What it does:

  • print application name plus build release id

Important behavior:

  • handled as fast-path command outside normal Cli::parse_action() path

test-plugin

Syntax:

rqp test-plugin --plugin <path-or-id> --preset core [--report <file.json>]
rqp test-plugin --plugin <path-or-id> --case <file.lua> [--case <file.lua> ...]
rqp test-plugin --plugin <path-or-id> --cases <directory> [--report <file.json>]

What it does:

  • run hermetic plugin conformance cases without touching real package managers

Key flags:

  • --plugin <value>
  • --preset <name>
  • --case <file.lua> repeatable
  • --cases <directory> repeatable
  • --report <file.json>

Important behavior:

  • requires --plugin
  • requires at least one of --preset, --case, or --cases
  • known preset today is core
  • exits 0 when all cases pass, 1 when any case fails

snapshot

Syntax:

rqp snapshot [options]

What it does:

  • export installed packages tracked by ReqPack history into reqpack.lua

Key flags:

  • --output <path>
  • --force

Important behavior:

  • reads ReqPack installed-state history, not arbitrary direct package-manager state
  • output is sorted by system then name
  • empty installed-state still succeeds and emits reminder about history.trackInstalled

Examples:

rqp snapshot
rqp snapshot --output reqpack.lua

pack

Syntax:

rqp pack <project-dir> [options]
rqp pack <system> <project-dir> [options]

What it does:

  • build builtin .rqp packages from project dirs
  • dispatch to plugin-native pack() when system argument is given and plugin supports it

Key flags:

  • --output <path>
  • --payload-dir <path>
  • --force
  • --non-interactive

Important behavior:

  • one positional argument means builtin .rqp mode
  • two positional arguments mean plugin-native mode
  • system token must match discovered system in two-argument mode

Examples:

rqp pack ./my-package
rqp pack ./my-package --output ./dist/demo.rqp
rqp pack deb ./debian-project --output ./dist/demo.deb

serve

Syntax:

rqp serve --stdin [options]
rqp serve --remote [--json|--http|--https] [options]

What it does:

  • run local stdin command loop
  • or run remote TCP command server

Key flags:

  • --stdin
  • --remote
  • --json
  • --http
  • --https
  • --bind <addr>
  • --port <n>
  • --token <value>
  • --username <name>
  • --password <value>
  • --readonly
  • --max-connections <n>
  • --non-interactive

Important behavior:

  • command requires exactly one of --stdin or --remote
  • --http and --https are parsed but not implemented
  • remote-only flags are rejected in stdin mode
  • --token cannot be combined with --username/--password
  • --username and --password must appear together
  • stdin mode accepts mixed commands and skips blank/comment lines

Examples:

printf 'install dnf curl\nlist dnf\n' | rqp serve --stdin
rqp serve --remote --bind 127.0.0.1 --port 4545 --token secret

remote

Syntax:

rqp remote <profile> [<command>...]

What it does:

  • connect to remote profile from remote.lua
  • forward one command and exit
  • or start interactive text session with no forwarded command

Important behavior:

  • requires profile name
  • interactive mode uses text protocol behavior
  • JSON profiles require forwarded command
  • local file upload works only in text/auto mode and only for one regular file in install command

Examples:

rqp remote dev list apt
rqp remote dev
rqp remote dev install rqp ./my-tool.rqp

Related Pages

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

Overview

User Guide

Extending ReqPack

Architecture

Clone this wiki locally