qp.1

.\" Man page for qp
.TH qp 1 "@DATE@" "qp @VERSION@" "User Commands"
.SH NAME
qp \- query packages. A CLI utility for querying installed packages.

.SH SYNOPSIS
.B qp [command] [args] [options]

.SH DESCRIPTION
.B qp
is a fast, flexible, and standalone CLI utility for querying installed packages on Arch Linux and Arch-based distributions. It supports advanced querying, sorting, and formatting features including:

- Existence checks
- Field filtering
- Date and size range queries
- Reverse dependencies and provisions
- Conflicts, optional dependencies, and groups
- Sorting and output as table or JSON

.SH COMMANDS
.TP
.B select <list>, s <list>
Select fields to display (comma-separated). Use:
.RS
.IP \[bu] 
select all — show all fields
.IP \[bu] 
select default — show default fields
.IP \[bu] 
select default,version — add to default
.RE

.TP
.B where <query>, w <query>
Apply one or more queries. Supported:
.RS
.IP \[bu] 
String match — \fIfield=value\fR (fuzzy), \fIfield==value\fR (strict)
.IP \[bu] 
Range match — \fIfield=start:end\fR or \fIfield==start:end\fR (works with \fBdate\fR, \fBsize\fR)
.IP \[bu] 
Existence check — \fBhas:field\fR or \fBno:field\fR
.RE

.TP
.B order <field>:<direction>, o <..>
Sort results. Fields: \fBdate\fR, \fBbuild-date\fR, \fBname\fR, \fBsize\fR, \fBlicense\fR, \fBpkgbase\fR

.TP
.B limit <number>, l <number>
Limit number of displayed results. Use \fBlimit all\fR to show all.
Numbers can be prefixed with end:<number> or mid:<number> to display X amount from a specific part of the output.

.SH OPTIONS
.TP
.B \-\-no-headers
Omit column headers (useful in scripts).
.TP
.B \-\-json
Output results in JSON format.
.TP
.B \-\-full-timestamp
Show full date+time for install/build.
.TP
.B \-\-no-progress
Disable progress bar.
.TP
.B \-\-no-cache
Skip using cache, force fresh data load.
.TP
.B \-\-regen-cache
Reload package data and regenerate cache.
.TP
.B \-h, \-\-help
Show help message.

.SH QUERYING
Use \fBwhere\fR (or \fBw\fR) one or more times to filter results.

.TP
.B String Match
\fIfield=value\fR — fuzzy (substring, case-insensitive)  
\fIfield==value\fR — strict (exact, case-insensitive)

.TP
.B Range Match
\fIfield=start:end\fR — fuzzy  
\fIfield==start:end\fR — strict  
Applies to \fBdate\fR and \fBsize\fR.  
Supports full (e.g., 1GB:5GB), open-ended (e.g., 1GB:, :5GB), or exact values.

.TP
.B Existence Check
\fBhas:field\fR — must be non-empty  
\fBno:field\fR — must be empty or missing

.TP
.B Match Behavior Summary:
.TS
box, tab(:);
cb cb cb
l l l.
Field Type:Fuzzy Match:Strict Match
_
Strings / Relations:substring (case-insensitive):exact (case-insensitive)
Date:match by day:exact timestamp
Size:±0.3% tolerance:exact byte size
.TE

.TP
.B Logical Operators
Use to combine or negate queries:
.RS
.IP \[bu] 
\fBand\fR - require all conditions to match
.IP \[bu] 
\fBor\fR - match if any condition matches
.IP \[bu] 
\fBnot\fR - invert a single condition
.IP \[bu] 
\fBq\fR ... \fBp\fR - group conditions (equivalent to parentheses)
.RE

.TP
Group and combine logic:
.B qp where q name=vim or name=nvim p and not has:conflicts

.SH SUPPORTED QUERY FIELDS
.TP
.B Range:
date, build-date, size
.TP
.B String:
name, reason, arch, version, license, pkgbase, description, url, groups, validation, pkgtype, packager
.TP
.B Relations:
conflicts, replaces, depends, optdepends, required-by, optional-for, provides

.SH AVAILABLE FIELDS
Available for use with \fBselect\fR, \fBselect all\fR, etc:

date, build-date, size, name, reason, version, arch, license, pkgbase,  
description, url, validation, packager, pkgtype, groups, conflicts,  
replaces, depends, optdepends, required-by, optional-for, provides

.SH EXAMPLES
List 10 smallest explicitly installed packages:
.br
\fBqp w reason=explicit o size:asc l 10\fR

Query packages larger than 500MB:
.br
\fBqp w size=500MB:\fR

Search packages that depend on \fBgtk3\fR:
.br
\fBqp w required-by=gtk3\fR

Get all fields for \fBgtk3\fR in JSON:
.br
\fBqp s all w name==gtk3 --json\fR

Group and filter multiple conditions:
.br
\fBqp w q name=zoxide or name=yazi p and optdepends=fzf\fR

.SH TIPS
- Pipe long outputs:
  \fBqp s name,depends | less\fR
.br
- Use comma-separated values:
  \fBqp w arch=x86_64,any\fR
.br
- Omit headers for scripts:
  \fBqp --no-headers s name,size\fR

.SH FILES
Cache is stored in:
.br
\fB$XDG_CACHE_HOME/query-packages\fR or \fB~/.cache/query-packages\fR
.br
If \fBXDG_CACHE_HOME\fR is not set, fallback is \fB~/.cache/query-packages\fR

.SH AUTHOR
Written by Fernando Nunez <me@fernandonunez.io>

.SH LICENSE
GPLv3-only. For commercial licensing, see LICENSE.commercial.

.SH BUGS
Report issues at:
.UR https://github.com/Zweih/qp
.UE

.SH SEE ALSO
.BR pacman(8),
.BR yay(1),
.BR paru(1)