# CommandSection

title: SYNOPSIS
content:
<b>pr</b> [<i>OPTION</i>]... [<i>FILE</i>]...<br>Common options:<br><b>pr</b> [<i>-a</i>] [<i>-c N</i>] [<i>-d</i>] [<i>-h HEADER</i>] [<i>-l PAGESIZE</i>] [<i>-m</i>] [<i>-n</i>] [<i>-o OFFSET</i>] [<i>-s[CHAR]</i>] [<i>-t</i>] [<i>-w WIDTH</i>] [<i>+FIRST_PAGE[:LAST_PAGE]</i>] [<i>FILE</i>]...


title: PARAMETERS
content:
<b><i>+FIRST_PAGE[:LAST_PAGE]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Start printing output on <i>FIRST_PAGE</i> and optionally stop after <i>LAST_PAGE</i>.<br><br><b><i>-N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Format the output into <i>N</i> columns. Default is 1.<br><br><b><i>-a</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print columns across the page, then down (multi-column output).<br><br><b><i>-d</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Double-space the output.<br><br><b><i>-e[CHAR][GAP]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Expand input tabs (or <i>CHAR</i>) to spaces. <i>GAP</i> specifies tab width (default 8).<br><br><b><i>-F</i>, <i>--form-feed</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Separate pages with form feeds (instead of newlines).<br><br><b><i>-h HEADER</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use <i>HEADER</i> as the page header instead of the filename and date/time.<br><br><b><i>-i[CHAR][GAP]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Replace spaces with tabs (or <i>CHAR</i>) on output. <i>GAP</i> specifies tab width (default 8).<br><br><b><i>-l PAGESIZE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the page length to <i>PAGESIZE</i> lines (default 66).<br><br><b><i>-m</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print all specified files in parallel, one file per column.<br><br><b><i>-n[CHAR][WIDTH]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Number lines, using <i>CHAR</i> (default TAB) to separate the number from the line, and setting the number's <i>WIDTH</i> (default 5).<br><br><b><i>-o OFFSET</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Indent each line by <i>OFFSET</i> spaces.<br><br><b><i>-p</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pause before each page and prompt for <I>RETURN</I> (interactive paging).<br><br><b><i>-s[CHAR]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Separate columns by a single character <i>CHAR</i> (default TAB).<br><br><b><i>-t</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Omit page headers and footers (no top/bottom margins).<br><br><b><i>-w WIDTH</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the page width to <i>WIDTH</i> characters (default 72 for multi-column, 132 for single).<br><br>


title: DESCRIPTION
content:
The <b>pr</b> command is a fundamental Unix/Linux utility designed to <b>format</b> and <b>paginate</b> text files, preparing them for printing. Its primary function is to transform raw text into a more readable layout by adding headers, page numbers, and optionally dividing content into multiple columns. The default output includes the filename, last modification date, time, and page number in a header, along with a footer of blank lines. <br><br>Users have extensive control over the output format, including specifying the number of columns (single or multi-column layouts), setting page length and width, enabling line numbering, and defining custom page headers. It can also merge multiple files into parallel columns, which is useful for side-by-side comparison or consolidated reports. While physical printing is less common today, <b>pr</b> remains valuable for command-line text processing, creating formatted output for viewing in a terminal, or piping to other tools.


title: CAVEATS
content:
The <b>pr</b> command is primarily designed for <i>plain text files</i> and assumes fixed-width character output, typical of historical line printers or terminal displays. It is not suitable for formatting binary files or producing rich text/PDF output directly. For complex document formatting or graphical output, modern tools like word processors, desktop publishing software, or PDF generation utilities are more appropriate. While still useful for command-line text manipulation, its direct relevance to physical printing has diminished with the rise of GUI-based printing systems.


title: STANDARD INPUT/OUTPUT
content:
When no <i>FILE</i> arguments are provided, or when a <i>FILE</i> is specified as a single hyphen (<b>-</b>), <b>pr</b> reads its input from <i>standard input</i>. The formatted output is always written to <i>standard output</i>, making it highly suitable for use in command-line pipelines with other utilities like <b>lp</b> or <b>lpr</b>.


title: PAGING VS. COLUMNATING
content:
<b>pr</b> distinguishes between <i>paging</i> (breaking output into discrete pages with headers) and <i>columnating</i> (arranging text into multiple vertical columns). By default, it paginates a single column. Options like <b>-N</b> (for N columns) and <b>-m</b> (for merging files into columns) enable its columnating capabilities.


title: HISTORY
content:
The <b>pr</b> command is one of the earliest and most enduring utilities in the Unix ecosystem, dating back to the original AT&T Unix releases. Its design reflects the computing environment of the time, where physical printers were the primary means of output and command-line text processing was standard. It was standardized by <i>POSIX.1</i>, ensuring its consistent behavior across various Unix-like operating systems. The GNU Core Utilities project provides the widely used implementation found in most Linux distributions. <br><br>While its original purpose of preparing files for dot-matrix or line printers has evolved, <b>pr</b> remains a valuable tool for quick text formatting, especially when piping output to other command-line tools or for simple readability enhancements in a terminal.


title: PARAMETERS
content:
<b><b>install</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Installs the Git hooks scripts into the <i>.git/hooks/pre-commit</i> directory, allowing <b>pre-commit</b> to run automatically before each commit.<br><br><b><b>run</b> [<i>&lt;hook-id&gt;</i> ...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manually runs the configured hooks against the current staged files or specified files. Useful for testing hooks or running them outside of a commit.<br><br><b><b>autoupdate</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Automatically updates the versions of the hooks defined in <i>.pre-commit-config.yaml</i> to their latest stable versions.<br><br><b><b>uninstall</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes the <b>pre-commit</b> Git hook scripts from the repository, restoring the default Git hook behavior.<br><br><b><b>clean</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Clears the <b>pre-commit</b> cache, which can resolve issues with stale hook installations or corrupted environments.<br><br><b><b>try-repo</b> <i>&lt;repository&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Tests a single hook from a specified repository without needing to add it to your configuration file.<br><br><b><b>--config</b> <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative path to the <b>pre-commit</b> configuration file (default is <i>.pre-commit-config.yaml</i>).<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the installed version of the <b>pre-commit</b> framework.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows help message for the <b>pre-commit</b> command or a specific subcommand.<br><br>


title: DESCRIPTION
content:
The <b>pre-commit</b> command, more accurately described as the <b>pre-commit</b> framework, is a powerful and extensible Python-based tool designed to standardize and manage Git pre-commit hooks in repositories. It helps developers enforce code quality, consistency, and style guidelines before code is committed, preventing common errors and ensuring a cleaner codebase.<br><br>Instead of manually setting up individual Git hooks, <b>pre-commit</b> allows you to define a list of hooks (often linters, formatters, or security checks) in a central configuration file (typically <i>.pre-commit-config.yaml</i>). When <b>pre-commit</b> is installed in a repository, it automatically runs these defined hooks against the staged files every time a developer attempts to commit changes. If any hook fails, the commit is aborted, prompting the developer to fix the issues.<br><br>This framework significantly reduces the overhead of maintaining consistent development practices across teams, automates tedious checks, and helps maintain a high standard of code quality throughout the project lifecycle. It supports hooks written in various languages and can be easily integrated into any Git repository.


title: CAVEATS
content:
The <b>pre-commit</b> framework requires Python to be installed on the system to function. It relies heavily on the <i>.pre-commit-config.yaml</i> file for its configuration; without this file, or if it's malformed, <b>pre-commit</b> will not know which hooks to run. Overly complex or slow hooks can significantly delay the commit process, impacting developer experience. Initial setup is per-repository and requires running `pre-commit install` once.


title: CONFIGURATION FILE (<I>.PRE-COMMIT-CONFIG.YAML</I>)
content:
The core of <b>pre-commit</b>'s functionality is defined in the <i>.pre-commit-config.yaml</i> file, located at the root of your Git repository. This YAML file specifies which hook repositories to use, the version of those repositories, and the specific hooks to run. It allows for detailed configuration of individual hooks, including arguments, file types to include or exclude, and more. This centralized configuration ensures that all developers working on the repository use the same set of quality checks.


title: HOOK TYPES
content:
While named 'pre-commit', the framework can manage hooks for various Git stages. Although its primary use case is the <i>pre-commit</i> hook, it can also support other hook types like <i>pre-push</i> (run before `git push`), <i>pre-merge-commit</i>, and <i>commit-msg</i>, allowing for a broader range of automated checks and validations throughout the Git workflow. This flexibility makes it a versatile tool for maintaining repository hygiene beyond just staged files.


title: HISTORY
content:
The <b>pre-commit</b> framework was created by Anthony Sottile and first released in 2014. It emerged as a solution to the common problem of manually managing Git hooks and ensuring consistent code quality across development teams. Before <b>pre-commit</b>, developers would often share scripts or rely on ad-hoc solutions, leading to inconsistencies and maintenance challenges. Since its inception, <b>pre-commit</b> has gained significant popularity within the Python community and beyond, becoming a de facto standard for automating code quality checks in Git repositories due to its ease of use, extensibility, and robust ecosystem of pre-built hooks.


title: PARAMETERS
content:
<b><b>-n</b>, <b>--no-act</b>, <b>--dry-run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a dry run, printing the names of the files that would be renamed and their new names without actually changing anything. This is highly recommended for testing your expression.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the names of files successfully renamed.<br><br><b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces overwriting of existing target files. Use with caution.<br><br><b><b>-i</b>, <b>--interactive</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prompts before overwriting an existing target file.<br><br><b><b>-s</b>, <b>--symlinks</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Operates on the targets of symbolic links, rather than the symlinks themselves.<br><br><b><b>-p</b>, <b>--path</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Operates on the full path of each file, not just its basename. By default, only the basename is modified.<br><br><b><b>-k</b>, <b>--keep-last</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;With <b>-p</b>, this option prevents the final path component from being changed.<br><br><b><b>-u</b>, <b>--nocheck-target</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not check for target existence before renaming. This can be slightly faster but less safe.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief help message and exits.<br><br><b><b>-V</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays version information and exits.<br><br>


title: DESCRIPTION
content:
<b>prename</b> is a command-line utility commonly found on Unix-like systems, often a symbolic link or alias to the Perl <b>rename</b> command. Its primary function is to batch rename multiple files based on a specified Perl regular expression substitution.<br><br>Unlike simpler <b>rename</b> utilities that might only support <b>sed</b>-like string replacements, <b>prename</b> harnesses the full power of Perl's regular expression engine. This allows for highly flexible and complex renaming operations, such as changing file extensions, inserting or deleting characters, reordering parts of filenames, or converting case.<br><br>The command takes a Perl expression (typically in the <i>s/original/replacement/[flags]</i> format) and a list of files or directories as arguments. It processes each filename through the expression, calculates the new name, and then performs the rename operation. It's crucial to understand the regex syntax to use <b>prename</b> effectively. For safety, it's highly recommended to use the <b>-n</b> (dry-run) option first to see what changes will be made before actually executing the rename.


title: CAVEATS
content:
The biggest caveat is the existence of multiple <b>rename</b> implementations on Linux systems. <b>prename</b> typically refers to the Perl <b>rename</b> utility, which is distinct from the <b>util-linux</b> <b>rename</b> (sometimes aliased as <b>rename.ul</b>). The Perl version uses Perl-compatible regular expressions (PCREs) for substitution (e.g., <i>s/old/new/</i>), while the <b>util-linux</b> version uses <b>sed</b>-like arguments (e.g., <i>old new</i>). Always verify which <b>rename</b> version <b>prename</b> points to on your system (e.g., <i>readlink -f $(which prename)</i>) to avoid unexpected behavior.<br><br>Always test your <i>perl_expression</i> with the <b>-n</b> (dry-run) option first, especially when dealing with complex regular expressions, to prevent accidental data loss or unwanted renames.


title: EXAMPLES
content:
<i>1. Change file extensions from .txt to .log:</i><br><i>prename 's/\.txt$/\.log/' *.txt</i><br><i>2. Remove spaces from filenames and replace with underscores:</i><br><i>prename 's/ /_/g' *</i><br><i>3. Convert filenames to lowercase:</i><br><i>prename 's/(.*)/\L$1/' *</i><br><i>4. Add a prefix &quot;new_&quot; to all .jpg files:</i><br><i>prename 's/(.*)/new_$1/' *.jpg</i><br><i>5. Reorder parts of a filename (e.g., &quot;YYYY-MM-DD_title.txt&quot; to &quot;title_YYYY-MM-DD.txt&quot;):</i><br><i>prename 's/^(\d{4}-\d{2}-\d{2})_(.*)\.txt$/$2_$1.txt/' *</i><br><br>Always remember to test these commands with <b>-n</b> (dry-run) first!


title: HISTORY
content:
The Perl <b>rename</b> script, which <b>prename</b> often embodies, was written by Larry Wall, the creator of Perl. It emerged as a powerful solution for batch renaming files, leveraging Perl's strengths in text processing and regular expressions. Its flexibility quickly made it a preferred tool for complex renaming tasks over simpler, often less feature-rich <b>rename</b> implementations. Over time, it has become a standard utility in many Linux distributions, sometimes aliased as <b>prename</b> to differentiate it from other <b>rename</b> versions, or simply as the default <b>rename</b> command.


title: PARAMETERS
content:
<b>--write, -w</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Formats specified files in place, overwriting them. This is one of the most common options.<br><br><b>--check</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Checks if files are formatted according to Prettier's rules without writing to disk. Exits with a non-zero code if unformatted files are found.<br><br><b>--list-different, -l</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists files that are not formatted according to Prettier's rules, without writing to disk.<br><br><b>--stdin</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads code from standard input (<I>stdin</I>) and prints the formatted output to <I>stdout</I>. Useful for piping content.<br><br><b>--config <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to a Prettier configuration file (e.g., <I>.prettierrc</I>) to use. By default, Prettier searches for one.<br><br><b>--ignore-path <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a path to a file containing patterns of files/directories to ignore, similar to <I>.gitignore</I> (default is <I>.prettierignore</I>).<br><br><b>--print-width <int></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the line length at which Prettier will wrap code (default: 80 characters).<br><br><b>--tab-width <int></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the number of spaces per indentation level (default: 2 spaces).<br><br><b>--use-tabs</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Indents with tabs instead of spaces.<br><br><b>--single-quote</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses single quotes instead of double quotes for strings.<br><br><b>--trailing-comma <none|es5|all></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls the printing of trailing commas (e.g., 'es5' for objects, arrays, etc., where valid in ES5).<br><br><b>--semi, --no-semi</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls whether to print semicolons at the end of statements (default: <I>--semi</I>).<br><br><b>--parser <string></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the parser to use. Prettier typically infers this from the file extension, but it can be overridden (e.g., 'typescript', 'json').<br><br><b>--version, -v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the installed Prettier version.<br><br><b>--help, -h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the command.<br><br>


title: DESCRIPTION
content:
Prettier is an <I>opinionated code formatter</I> that supports a wide range of programming languages including JavaScript, TypeScript, JSX, HTML, CSS, JSON, Markdown, and more.<br><br>Its primary goal is to ensure consistent code style across an entire codebase by parsing your code and reprinting it with its own rules, rather than applying a diff. This eliminates debates over style, as Prettier takes care of all formatting, making code reviews focused on logic rather than aesthetics.<br><br>It's commonly used in modern web development workflows, often integrated into Git pre-commit hooks, IDEs, and build processes to automatically format code upon saving or committing.


title: CAVEATS
content:
Prettier is not a native Linux command; it requires <B>Node.js</B> and <B>npm</B> (or Yarn) to be installed on the system. It is an opinionated formatter, meaning it enforces a specific style which might not always align with every developer's personal preferences without specific configuration. Using <I>--write</I> can overwrite files, so it's advisable to use it with version control. Initial adoption in large, unformatted codebases might lead to significant diffs upon first application.


title: CONFIGURATION FILES
content:
Prettier automatically looks for configuration files like <I>.prettierrc</I> (in JSON, YAML, or JS format) or a <I>prettier</I> key in <I>package.json</I> in the project root. These files allow users to define specific formatting rules that override Prettier's defaults, ensuring project-specific style consistency.


title: EDITOR AND IDE INTEGRATION
content:
Prettier is widely integrated into popular text editors and IDEs (e.g., VS Code, WebStorm, Sublime Text, Atom) via plugins. These integrations allow for automatic formatting on save, or on command, making it a seamless part of the development workflow and instantly applying formatting rules.


title: GIT HOOKS INTEGRATION
content:
It's common practice to integrate Prettier into <I>Git pre-commit hooks</I> using tools like <I>lint-staged</I> and <I>husky</I>. This ensures that all code committed to a repository is automatically formatted before it's pushed, maintaining a consistent style across all contributions and preventing unformatted code from entering the codebase.


title: HISTORY
content:
Prettier was created by <I>James Kyle</I> and first released in 2017. It quickly gained popularity within the JavaScript ecosystem due to its 'opinionated' nature, which removed the need for endless debates over code style by automating formatting entirely. Its declarative approach to code formatting, where it parses code into an Abstract Syntax Tree (AST) and then re-prints it, set it apart from traditional linters that often just checked for style violations. Over time, it expanded its support to many other languages, becoming a ubiquitous tool in modern development.


title: SYNOPSIS
content:
<b>pretty-bytes</b> [<i>OPTIONS</i>] <i>NUMBER_OF_BYTES</i><br><i>COMMAND</i> | <b>pretty-bytes</b> [<i>OPTIONS</i>]


title: PARAMETERS
content:
<b>-p, --precision &lt;num&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the number of decimal places to include in the output. For example, <i>--precision 2</i> would display <i>1.23 MB</i>.<br><br><b>-s, --si</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses SI units (powers of 1000, e.g., KB, MB) instead of IEC units (powers of 1024, e.g., KiB, MiB). By default, many implementations use IEC units.<br><br><b>-f, --force-unit &lt;unit&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output to be in a specific unit (e.g., <i>KB</i>, <i>MB</i>, <i>GB</i>), regardless of the automatic determination. This can be useful for consistent display across multiple values.<br><br><b>-0, --no-decimals-if-whole</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Omits decimal places if the value is a whole number (e.g., outputs <i>2 MB</i> instead of <i>2.00 MB</i>).<br><br><b>-c, --compact</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses a more compact notation, often omitting spaces (e.g., <i>1MB</i> instead of <i>1 MB</i>) or using shorter unit names (e.g., <i>1M</i>).<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message and exits.<br><br><b>-v, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the command's version information and exits.<br><br>


title: DESCRIPTION
content:
The <b>pretty-bytes</b> command, often implemented as a standalone script or utility, is designed to transform a raw number of bytes into a more human-readable format. Instead of displaying a large, raw number like <i>1048576</i>, it intelligently converts it to a more intuitive representation such as <i>1 MB</i> or <i>1.00 MiB</i>. This conversion makes byte sizes much easier to comprehend quickly, which is crucial when dealing with file sizes, disk usage reports, or network transfer speeds where large byte counts would otherwise be cumbersome to interpret. It automatically determines the most appropriate unit (bytes, KB, MB, GB, TB, PB, etc.) to represent the given size, and typically offers options to control precision and unit systems (binary IEC vs. decimal SI prefixes).


title: CAVEATS
content:
The <b>pretty-bytes</b> command is not a standard, pre-installed utility universally found on all Linux distributions. Its functionality is commonly provided by programming libraries (like Node.js's <i>pretty-bytes</i>) or can be found in other command-line tools such as <i>numfmt</i>. If you intend to use a specific `pretty-bytes` utility, you might need to install a particular package, use a custom script, or compile it from source. Implementations may vary in available options, default behaviors, and the exact set of supported units.


title: USAGE EXAMPLES
content:
To demonstrate its common utility:<br><br><i>pretty-bytes 123456789</i><br><i># Output: 123.46 MB</i><br><br><i>pretty-bytes --si 1000000000</i><br><i># Output: 1.00 GB</i><br><br><i>echo 2048 | pretty-bytes --force-unit KB</i><br><i># Output: 2.00 KB</i><br><br><i>du -b my_file.txt | cut -f1 | pretty-bytes</i><br><i># Output: (e.g., 5.34 KB)</i>


title: UNIT SYSTEMS
content:
There are two primary systems for byte prefixes that <b>pretty-bytes</b> often differentiates:<br><b>1. Binary (IEC)</b>: Uses 1024 as the base (2^10). Units are KiB (kibibyte), MiB (mebibyte), GiB (gibibyte), TiB (tebibyte). This system is commonly used for measuring RAM, file sizes, and disk space by operating systems.<br><b>2. Decimal (SI)</b>: Uses 1000 as the base (10^3). Units are KB (kilobyte), MB (megabyte), GB (gigabyte), TB (terabyte). This system is typically used by hard drive manufacturers for advertised capacities and for network speeds (e.g., Mbps).


title: PARAMETERS
content:
<b>-i, --inplace</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Modifies the input file in place. Creates a backup of the original file if applicable.<br><br><b>-o <file>, --output=<file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output file. If not specified, output goes to standard output (stdout).<br><br><b>-s, --sort</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a sorting algorithm to the data (e.g., line-by-line for text) to group similar content, enhancing compressibility.<br><br><b>-d, --delta</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies delta encoding to suitable data streams to reduce redundancy in sequential or incremental values.<br><br><b>--dict-size=<size></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the dictionary size for preprocessing, if a dictionary-based method is applied. A larger dictionary can improve compression for highly repetitive data.<br><br><b>-f, --force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces overwrite of existing output files without prompting for confirmation.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, showing progress and details of the preprocessing steps being performed.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message with command usage and options, then exits.<br><br>


title: DESCRIPTION
content:
The <b>prezip</b> command refers to a conceptual or specialized utility designed to perform preprocessing operations on data <br> <i>before</i> it is subjected to standard compression algorithms (such as those used by <b>zip</b>, <b>gzip</b>, <b>bzip2</b>, or <b>xz</b>). Its primary goal is to transform the input data in a way that increases its compressibility, leading to better compression ratios and potentially faster compression times for the subsequent archiving step. <br><br> While not a widely distributed standard Linux utility, the idea behind <b>prezip</b> is to apply various data optimization techniques. These might include, but are not limited to: <br> <b>Data Sorting:</b> Reordering data blocks or lines to bring similar patterns closer together.<br> <b>Delta Encoding:</b> Transforming sequences of data into differences from previous values, especially useful for numerical or time-series data.<br> <b>Dictionary Building:</b> Identifying common phrases or byte sequences and replacing them with shorter references.<br> <b>Redundancy Removal:</b> Stripping extraneous information or normalizing data formats. <br><br> The output of <b>prezip</b> would typically be a modified version of the original data, which is then piped or saved to a file for a subsequent compression utility to process. This two-stage approach aims to leverage the strengths of specialized preprocessing with general-purpose compression algorithms.


title: CAVEATS
content:
It is important to note that <b>prezip</b> is <i>not</i> a standard, widely distributed Linux utility found in common core packages or official repositories. Its specific implementation and availability would depend on custom scripts, specialized software distributions, or internal tools of certain compression libraries (e.g., related to some LZMA SDKs). <br><br> The behavior described here is based on the conceptual role suggested by its name ('pre-zip') and general data preprocessing techniques used to enhance compression. Actual <b>prezip</b> utilities, if they exist for specific purposes, may vary significantly in functionality, syntax, and options from this conceptual overview.


title: INTEGRATION WITH COMPRESSION PIPELINES
content:
A conceptual <b>prezip</b> command is best utilized in a pipeline fashion. For example, `<b>prezip</b> <i>input.log</i> | <b>gzip</b> > <i>output.log.gz</i>` would preprocess `input.log` and then compress the optimized output using <b>gzip</b>. This allows for a modular approach where the preprocessing logic can be separated from the compression algorithm itself, potentially allowing for custom optimization strategies.


title: WHEN TO USE (CONCEPTUALLY)
content:
The theoretical benefit of using a <b>prezip</b> utility arises when standard compression algorithms are not achieving optimal results, especially with highly repetitive, structured, or predictable data. By transforming the data into a more 'compressible' form (e.g., by making long runs of identical bytes, or by grouping similar lines), <b>prezip</b> aims to give the subsequent compressor an easier task, potentially yielding smaller archive sizes or faster compression for specific data types. Its effectiveness would depend heavily on the nature of the data and the preprocessing methods applied.


title: HISTORY
content:
The concept of data preprocessing to enhance compression efficiency is fundamental to many advanced compression algorithms. Techniques such as statistical modeling, dictionary coding (e.g., LZW, LZ77/LZ78), and various forms of data transformation (like the Burrows-Wheeler Transform used in <b>bzip2</b>) are internal steps within modern compressors. While a standalone, general-purpose <b>prezip</b> command is not a common fixture in standard Linux distributions, the underlying principles it embodies have been integral to the development and evolution of data compression science since its inception in the mid-20th century. Specialized 'pre-processing' tools might exist within specific domains (e.g., bioinformatics, database compression) to optimize very particular data types before standard archiving.


title: SYNOPSIS
content:
<b>prezip-bin</b> [<i>OPTIONS</i>] &lt;<i>INPUT_FILE</i> &gt;<i>OUTPUT_FILE</i><br><b>prezip-bin</b> [<i>OPTIONS</i>] <i>FILE</i>


title: PARAMETERS
content:
<b><b>-d</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs the reverse operation, decompressing or 'un-prezipping' a previously processed file back to its original layout. This is typically used to revert the structural changes made for compression.<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, providing more detailed information about the processing steps, such as file parsing, section reordering, and any errors encountered during the operation.<br><br>


title: DESCRIPTION
content:
<i>prezip-bin</i> is a specialized Linux command-line utility designed to preprocess executable binaries, such as ELF, PE, and Mach-O formats, before they are compressed using algorithms like LZMA or XZ. Its primary function is to improve the compression ratio by rearranging the internal sections of these binary files.<br><br>The tool works by grouping similar data types together, such as code sections, data sections, and debug information, making it easier for block-based compressors to find and exploit redundancies. This reordering process helps reduce the overall size of the compressed binary significantly.<br><br>While not typically invoked directly by end-users, <i>prezip-bin</i> is an essential backend component for tools like <i>RPM</i> (Red Hat Package Manager), where it's used to optimize the compression of package payloads, especially for debuginfo files and other executables within RPM packages. It acts as a filter, taking an unoptimized binary as input and producing an optimized binary stream for subsequent compression.


title: CAVEATS
content:
<i>prezip-bin</i> is primarily an internal utility, largely used by higher-level tools like <i>RPM</i> for specific binary optimization tasks. It is not intended for general-purpose file compression or as a standalone user-facing tool like <i>gzip</i> or <i>bzip2</i>. Direct manual invocation is rare and its full capabilities or limitations are often undocumented outside of its source code or the projects it's integrated with.


title: HISTORY
content:
<i>prezip-bin</i> emerged as part of efforts to optimize the storage and distribution of software packages, particularly within the <i>RPM</i> ecosystem. Its development was driven by the need to achieve better compression ratios for executable binaries and debug information, which often contain repetitive patterns that are not easily compressed by standard algorithms without prior structural optimization. It addresses the challenge of making ELF, PE, and Mach-O files more amenable to LZMA/XZ compression by intelligently reordering their internal components.


title: PARAMETERS
content:
<b>FILE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more files to concatenate and display. If no FILE, or when FILE is -, read standard input.<br><br><b>-A, --show-all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Equivalent to -vET. Displays non-printing characters (except LFD and TAB), line endings ($), and tabs (^I).<br><br><b>-b, --number-nonblank</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Number non-blank output lines, starting at 1.<br><br><b>-E, --show-ends</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a '$' at the end of each line.<br><br><b>-n, --number</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Number all output lines, starting at 1.<br><br><b>-s, --squeeze-blank</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress repeated empty output lines, reducing multiple blank lines to a single blank line.<br><br><b>-T, --show-tabs</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display TAB characters as '^I'.<br><br><b>-v, --show-nonprinting</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use '^' and 'M-' notation for non-printing characters (except LFD and TAB).<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output version information and exit.<br><br>


title: DESCRIPTION
content:
<b>pridecat</b> is a non-standard, community-driven utility that functions as a colorful variation of the traditional <b>cat</b> command. Its primary purpose is to read one or more files sequentially and display their contents to standard output, but with an added vibrant rainbow color effect. Often implemented as a shell script wrapping <b>cat</b> and a text colorizing tool like <b>lolcat</b>, <b>pridecat</b> brings a festive and celebratory visual flair to terminal output. While not a native system command, it is widely recognized and used within Linux communities for displaying text in an eye-catching, often pride-themed, manner. It is particularly popular for presenting code snippets, log files, or any text-based content in an engaging and visually distinct way. The command typically retains most of the file-handling capabilities of <b>cat</b>, making it a drop-in replacement for basic text viewing when a splash of color is desired.


title: CAVEATS
content:
<b>pridecat</b> is not a standard Linux command and does not come pre-installed with most distributions. Its availability depends on user-defined aliases, custom shell scripts, or third-party installations (e.g., <b>lolcat</b>, which is often used as the coloring engine).<br><br>The exact behavior and supported options may vary significantly depending on the specific implementation of the <b>pridecat</b> script. Some simple wrappers might only pass file arguments, while more robust versions might support all <b>cat</b> options or even options from the underlying coloring tool.<br><br>For very large files, the additional processing for coloring might introduce a slight overhead compared to a plain <b>cat</b>.


title: INSTALLATION AND USAGE EXAMPLE
content:
Since <b>pridecat</b> is often a custom script or alias, there isn't a single installation method. A common approach involves ensuring a suitable text colorizing tool, such as <b>lolcat</b>, is installed on your system. You can often install <b>lolcat</b> via your distribution's package manager (e.g., <i><pre>sudo apt-get install lolcat</pre></i> on Debian/Ubuntu, or <i><pre>sudo yum install lolcat</pre></i> on Fedora), or sometimes via RubyGems (<i><pre>sudo gem install lolcat</pre></i>).<br><br>Once <b>lolcat</b> (or a similar tool) is available, a simple <b>pridecat</b> script can be created. A common implementation looks like this:<br><i><pre>#!/bin/bash<br>cat "$@" | lolcat</pre></i><br>Save this content to a file named <i>pridecat</i>, place it in a directory included in your system's <b>$PATH</b> (e.g., <i>/usr/local/bin/</i> or a custom <i>~/bin/</i> directory), and make it executable: <i><pre>chmod +x /path/to/pridecat</pre></i>.<br><br><b>Usage Example:</b><br>To display the content of <i>myfile.txt</i> with rainbow colors:<br><i><pre>pridecat myfile.txt</pre></i><br>To display the output of another command with rainbow colors (piping):<br><i><pre>ls -l | pridecat</pre></i>


title: HISTORY
content:
<b>pridecat</b> does not have a formal development history as a standalone project or official command. It emerged organically within the Linux and open-source communities as a creative and fun way to augment the ubiquitous <b>cat</b> command. Its rise in popularity is closely tied to the development and adoption of text colorizing tools like <b>lolcat</b>, which made adding vibrant, animated rainbow colors to terminal output simple and accessible. The concept gained traction as a lighthearted tribute to Pride Month and LGBTQ+ inclusivity, showcasing how command-line utilities can be customized for personal expression and community messaging beyond their utilitarian functions. Its evolution has been driven by individual users sharing simple shell scripts or aliases, rather than a centralized development effort.


title: PARAMETERS
content:
<b><i>&lt;command&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The executable command or script to be run on the discrete NVIDIA GPU.<br><br><b><i>&lt;arguments...&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional arguments to be passed to the specified <i>&lt;command&gt;</i>.<br><br>


title: DESCRIPTION
content:
`prime-run` is a utility command used on Linux systems equipped with NVIDIA Optimus or similar hybrid graphics configurations. Its primary purpose is to launch applications using the discrete NVIDIA GPU, rather than the integrated graphics processor (iGPU) that the system typically defaults to for power efficiency. This allows users to leverage the more powerful dedicated GPU for demanding tasks like gaming, video editing, or scientific computing, while still benefiting from the iGPU's power savings for less intensive workloads. Essentially, `prime-run` acts as a convenient wrapper, setting the necessary environment variables (`__NV_PRIME_RENDER_OFFLOAD`, `__GLX_VENDOR_LIBRARY_NAME`, etc.) that instruct the graphics stack to use the NVIDIA GPU for the specified command.


title: CAVEATS
content:
<b>Requires NVIDIA PRIME setup:</b> `prime-run` relies on a properly configured NVIDIA PRIME render offload setup, which involves NVIDIA drivers and a compatible Xorg/Wayland environment. It may not work out-of-the-box on all distributions without specific configuration.<br><b>Power Consumption:</b> Running applications with the discrete GPU consumes significantly more power and generates more heat compared to using the integrated GPU, which can reduce battery life on laptops.<br><b>Application Compatibility:</b> While generally effective, some older or specific applications might not fully utilize the discrete GPU or may require additional environment variables for optimal performance.<br><b>No Direct Options:</b> `prime-run` itself does not have command-line options; it simply wraps the execution of another command.


title: HOW IT WORKS
content:
When you execute a command with `prime-run`, it typically sets environment variables like `<b>__NV_PRIME_RENDER_OFFLOAD=1</b>` and `<b>__GLX_VENDOR_LIBRARY_NAME=nvidia</b>` (for OpenGL) or `<b>__VK_LAYER_NV_optimus=NVIDIA_only</b>` (for Vulkan) before launching the application. These variables signal to the NVIDIA driver and graphics stack that the specific application should utilize the discrete GPU for rendering. The output is then passed back to the integrated GPU for display.


title: VERIFYING GPU USAGE
content:
To confirm that an application is running on the discrete GPU, you can monitor its usage using `<b>nvidia-smi</b>` in another terminal. Look for the process name and its associated GPU memory usage. For OpenGL applications, you can also run `<b>glxinfo | grep -i "vendor\|renderer"</b>` from within the `prime-run` context (e.g., `prime-run sh -c 'glxinfo | grep -i "vendor\|renderer"'`) to see if the NVIDIA renderer is listed.


title: HISTORY
content:
`prime-run` emerged as part of the broader adoption and standardization of NVIDIA's PRIME render offload capabilities on Linux. It succeeded older, less officially supported solutions like `optirun` (from the Bumblebee project), which aimed to provide similar hybrid graphics functionality. The development of `prime-run` aligns with NVIDIA's efforts to integrate Optimus-like features more seamlessly into the Linux ecosystem, leveraging direct driver support rather than third-party wrappers. Its usage became prominent with desktop environments and display servers (Xorg/Wayland) better supporting GPU offloading.


title: PARAMETERS
content:
<b>FIRST_NUMBER</b><br>&nbsp;&nbsp;&nbsp;&nbsp;An optional starting number for the prime sequence. If provided, primes will be listed from this number onwards (inclusive). If omitted, the sequence starts from 2.<br><br><b>LAST_NUMBER</b><br>&nbsp;&nbsp;&nbsp;&nbsp;An optional ending number for the prime sequence. If provided along with <i>FIRST_NUMBER</i>, primes will be listed up to this number (inclusive) within the specified range. If only <i>LAST_NUMBER</i> is given, it acts as the upper limit for primes starting from 2. If omitted, the sequence continues indefinitely.<br><br>


title: DESCRIPTION
content:
The <i>primes</i> command is a utility designed to output a sequence of prime numbers. When invoked without arguments, it generates primes starting from 2 and continues indefinitely. If a single numeric argument <i>N</i> is provided, it lists all prime numbers up to and including <i>N</i>. When two numeric arguments, <i>FIRST</i> and <i>LAST</i>, are supplied, <i>primes</i> outputs all prime numbers within that specified range, inclusive.<br><br>This tool is useful for mathematical computations, number theory explorations, or generating test data requiring prime numbers.


title: CAVEATS
content:
The <i>primes</i> command is not a standard utility found on all Linux distributions by default. It is often provided by less common packages (e.g., <i>miscutils</i>, <i>bsd-games</i>, or specific math tools) or might be a standalone script. Its exact behavior and available command-line options (which are typically none, beyond positional arguments) can vary depending on the specific implementation. For prime factorization, the more commonly available <i>factor</i>(1) command is used.


title: PERFORMANCE CONSIDERATIONS
content:
For very large numbers or extensive ranges, the <i>primes</i> command can be computationally intensive and may take a significant amount of time and resources. The efficiency depends on the underlying primality testing algorithm used by the specific implementation (e.g., trial division, Sieve of Eratosthenes, Miller-Rabin).


title: OUTPUT FORMAT
content:
By default, <i>primes</i> typically outputs one prime number per line, facilitating piping its output to other commands or scripts for further processing.


title: HISTORY
content:
The concept of a dedicated 'primes' utility for generating sequences dates back to early Unix systems. While not a core GNU utility, simple <i>primes</i> implementations have existed in various forms across different Unix-like environments, often as part of specialized math libraries or educational packages. Its continued existence in some distributions reflects its niche utility for direct prime generation.


title: PARAMETERS
content:
<b>-n</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not output the trailing newline character.<br><br><b>-r</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Raw mode. Do not interpret backslash escape sequences (e.g., \n, \t) in the arguments.<br><br><b>-R</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enhanced raw/formatted mode. Its specific behavior varies between shells; in ksh, it treats subsequent arguments as options to print itself, while in zsh, it interprets backslash escapes and printf-style format specifiers (e.g., \%). Consult your shell's manual for details.<br><br><b>-s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Write arguments to the shell's history file instead of standard output.<br><br><b>-u <I>fd</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Write arguments to the specified file descriptor <I>fd</I> (default is 1 for standard output).<br><br><b>--</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Marks the end of options. Treats all subsequent arguments as non-option arguments, even if they start with a hyphen.<br><br>


title: DESCRIPTION
content:
The <b>print</b> command is a versatile <I>shell built-in</I> utility, primarily available in shells like <I>ksh</I> (KornShell) and <I>zsh</I> (Z shell). Its main function is to write arguments to the standard output, similar to the <b>echo</b> command, but often providing more control over escape sequences and output formatting. Depending on the shell, <b>print</b> may not automatically add a newline character, requiring explicit inclusion of <I>\n</I> if a line break is desired. It is frequently used in shell scripts for displaying messages, debugging output, or presenting formatted data. While <b>printf</b> (a different command) offers more complex C-style formatting, <b>print</b> provides a simpler, yet powerful, mechanism for text output directly within the shell environment.


title: CAVEATS
content:
The <b>print</b> command is a <I>shell built-in</I>, meaning its availability and exact behavior (especially regarding options) can vary significantly between different shells. It is commonly found in <I>ksh</I> and <I>zsh</I>, but is <I>not a standard external utility</I> like <b>ls</b> or <b>grep</b>, nor is it a built-in in <I>bash</I> by default (where <b>printf</b> or <b>echo</b> are used instead). Users should consult their shell's documentation (e.g., <I>man zshbuiltins</I> or <I>man ksh</I>) for precise details.


title: HISTORY
content:
The <b>print</b> command originated in the <I>KornShell (ksh)</I>, developed by David Korn at Bell Labs, as a more robust and flexible alternative to the traditional <b>echo</b> command. It was later adopted by other shells, notably <I>zsh</I>, providing shell scripting with better control over output streams and escape sequence interpretation. Its design often aimed to address portability issues and inconsistent behaviors observed with <b>echo</b> across different Unix systems.


title: SYNOPSIS
content:
<I>runmailcap</I> <B>--action=print</B> [options] <I>MIME_TYPE</I> <I>FILE</I> [<I>ARGUMENTS</I>...]


title: PARAMETERS
content:
<b><B>--action=print</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly specifies the action to be performed, which in this context is 'print'. Other possible actions include 'view', 'compose', or 'edit'.<br><br><b><I>MIME_TYPE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The MIME type of the file to be processed (e.g., <I>application/pdf</I>, <I>image/png</I>).<br><br><b><I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the file that needs to be printed.<br><br><b><I>ARGUMENTS</I>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Additional arguments to be passed to the command defined in the mailcap entry.<br><br><b><B>--debug</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints extensive debugging information to standard error, useful for troubleshooting mailcap configuration issues.<br><br><b><B>--status</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints status messages indicating success or failure of the operation.<br><br><b><B>--noroot</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents <I>runmailcap</I> from considering mailcap entries that are designated for root-only execution.<br><br><b><B>--no-fallback</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables the fallback mechanism to default handlers if no specific mailcap entry is found for the given MIME type and action.<br><br>


title: DESCRIPTION
content:
<br>The command `print.runmailcap` refers to the specific use of the <I>runmailcap</I> utility to handle files for printing based on their MIME type and the system's <I>mailcap</I> configuration.<br><br><I>runmailcap</I> is a utility that interprets <I>mailcap</I> files (typically located at <I>/etc/mailcap</I> and <I>~/.mailcap</I>). These files serve as a database that maps various MIME (Multipurpose Internet Mail Extensions) types (e.g., <I>application/pdf</I>, <I>image/jpeg</I>, <I>text/plain</I>) to external programs capable of viewing, editing, or, in this case, printing them.<br><br>When invoked with the "print" action, <I>runmailcap</I> searches the <I>mailcap</I> configuration for an entry matching the given MIME type and the requested "print" action. If a suitable entry is found, it executes the associated command, passing the specified file to it. This mechanism allows applications to delegate the printing of diverse file formats to specialized helper programs, without needing to know the specifics of each file type's handling.


title: CAVEATS
content:
<ul><li><b>Dependency on Mailcap Configuration</b>: The functionality heavily relies on correctly configured <I>mailcap</I> files. Incorrect or missing entries can lead to errors or files not being handled as expected.</li><li><b>Security Risks</b>: Commands specified in <I>mailcap</I> entries are executed with the user's permissions. Care must be taken to ensure that <I>mailcap</I> files are trusted and do not contain malicious entries, as this could pose a security risk.</li><li><b>No Universal Print Command</b>: There is no single universal command for printing all file types. <I>runmailcap</I> delegates to various external programs (e.g., <I>lpr</I>, <I>evince</I>, <I>gv</I>), which must be installed and configured correctly.</li><li><b>Graphical Environment Requirement</b>: Many printing helpers require a graphical environment to function, even if the printing process itself is to a physical printer.</li></ul>


title: MAILCAP FILE STRUCTURE
content:
A <I>mailcap</I> file consists of one or more entries, each defining how to handle a specific MIME type. A typical entry follows the format: <br><br><I>MIME_type</I>; <I>command</I>; <I>field1</I>; <I>field2</I>; ...<br><br>For instance: <I>application/pdf; evince %s; test=test -n "$(which evince)"; print=lpr %s</I><br><br>Common fields include:<br><ul><li><I>test</I>: A shell command that must exit successfully for the entry to be used.</li><li><I>print</I>: The command to be executed for printing the file (this is what <B>--action=print</B> looks for).</li><li><I>copiousoutput</I>: Indicates the command produces a lot of output, which should be redirected to a pager.</li></ul><br>Placeholders like <I>%s</I> (filename), <I>%t</I> (MIME type), and <I>%{param}</I> (header parameter) are used within the command string.


title: COMMON MAILCAP LOCATIONS
content:
Mailcap files are typically read in a specific order:<br><ul><li><I>~/.mailcap</I>: User-specific overrides.</li><li><I>/etc/mailcap</I>: System-wide default configurations.</li><li>Other locations specified by the <I>MAILCAPS</I> environment variable.</li></ul><br>This hierarchy allows users to customize behavior without modifying system-wide settings.


title: HISTORY
content:
<I>Mailcap</I> files originated as part of the MIME (Multipurpose Internet Mail Extensions) standards in the early 1990s. They were designed to provide a standardized way for applications, particularly mail user agents (MUAs), to determine how to handle arbitrary media types (attachments) received via email. <I>runmailcap</I> emerged as a common utility to interpret these files, allowing systems to flexibly launch external viewers, editors, or printers for different MIME-typed data. While more integrated desktop environment mechanisms (like XDG MIME applications or GIO) have evolved, <I>mailcap</I> and <I>runmailcap</I> remain a fundamental, lightweight, and robust method for defining application associations on Unix-like systems, especially for command-line driven environments and older applications.


title: PARAMETERS
content:
<b><i>-r</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not interpret backslash escapes. Print arguments as raw strings.<br><br><b><i>-R</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Interpret common backslash escapes (e.g., <b><i>\n</i></b>, <b><i>\t</i></b>) but otherwise print raw.<br><br><b><i>-n</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not print a trailing newline character after the arguments.<br><br><b><i>-s</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Push the arguments onto the shell's history stack instead of printing.<br><br><b><i>-z</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Push the arguments onto the Zsh Line Editor (ZLE) stack.<br><br><b><i>-P</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Interpret prompt-style escape sequences (e.g., <b><i>%d</i></b> for current directory, <b><i>%n</i></b> for username) within arguments.<br><br><b><i>-l</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print arguments separated by newlines, each on a new line.<br><br><b><i>-o</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print arguments separated by spaces, each on a new line.<br><br><b><i>-c</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print arguments in columns, automatically determining the number of columns.<br><br><b><i>-C cols</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print arguments in <b><i>cols</i></b> columns.<br><br><b><i>-v</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print arguments visibly, showing non-printable characters as <b><i>^X</i></b> or <b><i>M-X</i></b> notation.<br><br><b><i>-u fd</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Write output to the specified file descriptor <b><i>fd</i></b> instead of standard output.<br><br><b><i>-t</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Write output to the terminal, even if standard output is redirected.<br><br><b><i>--</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Marks the end of options. Subsequent arguments are treated as non-option arguments.<br><br>


title: DESCRIPTION
content:
The <b><i>print</i></b> builtin in <b><i>zsh</i></b> writes its arguments to the standard output.<br>It offers a versatile and controlled way to display information within shell scripts or interactive sessions, distinguishing itself from the simpler <b><i>echo</i></b> command by providing more explicit options for handling output. Users can control newline suppression, backslash escape interpretation, and output formatting.<br>Key features include the ability to output raw strings, interpret prompt-style escape sequences (like <b><i>%d</i></b> for current directory), and direct output to specific file descriptors or the terminal regardless of stdout redirection.<br>This makes <b><i>print</i></b> a powerful tool for debugging, generating formatted logs, or interacting with the Zsh Line Editor (ZLE) and history stack. Its precise control over output behavior helps ensure consistent results across different Zsh environments, addressing some ambiguities present in older <b><i>echo</i></b> implementations.


title: CAVEATS
content:
The command <b><i>print.zsh</i></b> is interpreted here as referring to the <b><i>print</i></b> builtin command of the <b><i>zsh</i></b> shell.<br>If <b><i>print.zsh</i></b> refers to an actual script file with that name, its functionality would depend entirely on the script's content, which cannot be determined here.<br>The behavior of <b><i>print</i></b>, especially regarding backslash escapes, can be influenced by shell options such as <b><i>bsd_echo</i></b> or <b><i>sh_word_split</i></b>.


title: ESCAPE SEQUENCES
content:
By default (or with <b><i>-R</i></b>), <b><i>print</i></b> recognizes common C-style backslash escape sequences such as <b><i>\n</i></b> (newline), <b><i>\t</i></b> (tab), <b><i>\a</i></b> (alert/bell), <b><i>\b</i></b> (backspace), <b><i>\f</i></b> (form feed), <b><i>\v</i></b> (vertical tab), <b><i>\r</i></b> (carriage return), and <b><i>\\</i></b> (backslash). Octal (e.g., <b><i>\0NNN</i></b>) and hexadecimal (e.g., <b><i>\xNN</i></b>) character escapes are also supported.


title: PROMPT EXPANSION
content:
When the <b><i>-P</i></b> option is used, <b><i>print</i></b> supports expansion of prompt sequences similar to those used in the <b><i>PS1</i></b> variable. This allows for dynamic values like the current working directory (<b><i>%d</i></b>), username (<b><i>%n</i></b>), host (<b><i>%m</i></b>), time (<b><i>%T</i></b>), and many others to be included directly in the output string.


title: HISTORY
content:
The <b><i>print</i></b> command has been a long-standing builtin in the <b><i>zsh</i></b> shell, offering a more robust and feature-rich alternative to the traditional <b><i>echo</i></b> command. Historically, <b><i>echo</i></b>'s behavior, particularly concerning backslash escape interpretation and trailing newlines, varied significantly across different Unix shells, leading to portability issues.<br><b><i>zsh</i></b>'s <b><i>print</i></b> was developed to provide more predictable and explicit control over output, making it a preferred choice for scripting within <b><i>zsh</i></b> environments where consistent behavior is crucial.


title: PARAMETERS
content:
<b><i>VARIABLE</i>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more names of environment variables to display. If no <i>VARIABLE</i> is specified, all environment variables are printed.<br><br><b><i>--help</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br><b><i>--version</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output version information and exit.<br><br>


title: DESCRIPTION
content:
<i>printenv</i> is a simple yet powerful command-line utility used to display the values of environment variables. When invoked without any arguments, it prints a list of all environment variables and their corresponding values, one per line. This is useful for inspecting the current execution environment of a shell or script.<br><br>If one or more variable names are provided as arguments, <i>printenv</i> will only display the values of those specific variables. If a requested variable is not found in the environment, nothing is printed for that variable, and the command exits with a non-zero status. This behavior makes it suitable for use in shell scripts to check for the existence and value of particular environment variables.<br><br>While similar to the <i>env</i> command (when used without arguments) and the shell built-in <i>set</i> command, <i>printenv</i> specifically focuses on environment variables, which are inherited by child processes. It does not display shell-specific variables or functions that are not exported to the environment.


title: CAVEATS
content:
<i>printenv</i> only displays environment variables that have been exported. It does not show shell-specific variables or functions that are not part of the environment (e.g., local shell variables set with <i>VAR=value</i> without <i>export</i>). For a comprehensive list of shell variables, aliases, and functions, consult your shell's built-in commands like <i>set</i> or <i>declare</i>.


title: EXIT STATUS
content:
<i>printenv</i> exits with status 0 (success) if all specified <i>VARIABLE</i>s were found and printed, or if no <i>VARIABLE</i>s were specified. It exits with a non-zero status (failure) if at least one specified <i>VARIABLE</i> was not found in the environment.


title: DISTINCTION FROM ENV AND SET
content:
While often used interchangeably, <i>printenv</i>, <i>env</i>, and <i>set</i> have subtle differences:<br><br><i><b>printenv</b></i>: Displays only the environment variables. Cannot modify the environment or execute a command.<br><br><i><b>env</b></i>: Can display environment variables (when used without arguments) or run a command with a modified environment.<br><br><i><b>set</b></i> (shell built-in): Displays all shell variables (including environment variables), shell functions, and positional parameters. Its primary purpose is to set or unset shell options.


title: COMMON USAGE
content:
To list all environment variables:<br><i>printenv</i><br><br>To display a specific variable, for example, <i>HOME</i>:<br><i>printenv HOME</i><br><br>To check if a variable exists in a script:<br><i>if printenv MY_VAR &gt; /dev/null; then<br>&nbsp;&nbsp;echo "MY_VAR is set to: $(printenv MY_VAR)"<br>else<br>&nbsp;&nbsp;echo "MY_VAR is not set."<br>fi</i>


title: HISTORY
content:
The <i>printenv</i> utility is a standard component of the GNU Core Utilities, a collection of essential command-line tools for Unix-like operating systems. Its functionality is fundamental to understanding and managing the process environment, and similar capabilities have been present in various forms across Unix systems since early days. Its development follows the general evolution of standard Unix commands towards the GNU/Linux ecosystem.


title: PARAMETERS
content:
<b><I>printer_name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the CUPS printer to which the PPD file will be applied. This printer must already be configured in CUPS.<br><br><b><I>PPD_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The full path to the PostScript Printer Description (PPD) file that contains the printer's capabilities and settings. This file will be used to update the printer's driver.<br><br><b>[<I>IPP_options</I>...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional Internet Printing Protocol (IPP) options to pass to the CUPS backend during the printer update. These are typically specified as key=value pairs (e.g., 'PageSize=A4', 'ColorMode=Grayscale') and allow for additional printer configuration.<br><br>


title: DESCRIPTION
content:
<i>printer-profile</i> is a command-line utility, typically part of the <i>cups-pk-helper</i> package, designed to apply a specified PostScript Printer Description (PPD) file to an existing printer configured in the CUPS (Common Unix Printing System) environment. It acts as an authentication agent that leverages PolicyKit to allow unprivileged users to perform operations that would otherwise require root privileges, such as changing a printer's driver. This command is often invoked by graphical frontends or system scripts when a user selects a new PPD file for their printer. Its primary purpose is to simplify printer configuration updates by handling the necessary permissions through a secure, authenticated process.


title: CAVEATS
content:
<b>PolicyKit Dependency:</b> The command relies heavily on PolicyKit for privilege escalation and authentication. If PolicyKit is not installed or properly configured, or if the user lacks the necessary permissions, the operation will fail or require authentication.<br><br><b>CUPS Environment:</b> This utility is specific to CUPS and will not function in environments without a running CUPS daemon.<br><br><b>Existing Printer Requirement:</b> The specified printer must already exist and be configured in CUPS; <i>printer-profile</i> does not create new printers.<br><br><b>Valid PPD File:</b> The provided PPD file must be a valid and well-formed PostScript Printer Description file for the printer model.<br><br><b>Backend Usage:</b> While runnable from the command line, it's most commonly used by graphical user interfaces (GUIs) or scripts as a backend tool for printer management.


title: ROLE IN DESKTOP ENVIRONMENTS
content:
Many desktop environments (e.g., GNOME, KDE) integrate <i>cups-pk-helper</i> and, by extension, <i>printer-profile</i>, into their printer configuration utilities. When users update a printer's driver or change its PPD through the graphical interface, <i>printer-profile</i> is frequently invoked behind the scenes to securely and efficiently apply these changes to the CUPS system, handling the necessary PolicyKit authentication.


title: HISTORY
content:
<i>printer-profile</i> is a component of the <i>cups-pk-helper</i> project, which emerged to facilitate secure printer administration within modern Linux desktop environments. Its development was driven by the need to integrate CUPS operations with PolicyKit, allowing unprivileged users to perform administrative tasks related to printers (like changing drivers) after successful authentication, without granting them full root access. This tool bridges the gap between user-friendly graphical interfaces and the underlying CUPS administrative commands that typically require elevated privileges.


title: SYNOPSIS
content:
<b>printerbanner</b> [ <i>-d</i> ] [ <i>-w width</i> ] [ <i>-l</i> ] [ <i>-t</i> ] [ <i>header</i> ]


title: PARAMETERS
content:
<b><i>-d</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables debug mode. Depending on the implementation, this might send output to standard output or provide verbose diagnostic information.<br><br><b><i>-w width</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the output width of the banner in characters. This determines how many characters wide the banner can be. Common defaults are often 80 or 132.<br><br><b><i>-l</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the banner page in landscape orientation. This option effectively rotates the text, making it suitable for wider banners.<br><br><b><i>-t</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the banner page to the standard output (terminal) instead of directing it to a printer. This is useful for previewing banners or generating ASCII art for other purposes.<br><br><b><i>header</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The text string to be printed in large characters on the banner page. If omitted, a default value like the username, job name, or 'Banner Page' might be used, depending on how <i><b>printerbanner</b></i> is invoked by the printing system.<br><br>


title: DESCRIPTION
content:
<i><b>printerbanner</b></i> is a utility designed to generate and print large-format banner pages, typically composed of ASCII art. Its primary purpose is to create separator pages for print jobs on shared printers, making it easy to identify the owner and details of a printout. The banner usually contains a large representation of a specified header text, often the username, job title, or other identifying information.<br><br>While historically used for physical printers as part of printing systems like CUPS (Common Unix Printing System), it can also output to standard output (the terminal) for viewing, making it useful for generating large text art for various purposes.


title: CAVEATS
content:
The exact behavior and default options of <i><b>printerbanner</b></i> can vary significantly depending on the specific printing system (e.g., CUPS, LPD, or derivatives) and its configuration.<br><br>Direct usage by users is less common; it is primarily invoked internally by print spoolers like <i><b>lpr</b></i> or <i><b>lp</b></i> when banner pages are enabled for a print queue or requested as part of a job.


title: USAGE IN PRINT QUEUES
content:
While <i><b>printerbanner</b></i> can be run directly, its primary function is as a backend program for print spoolers. When a print job is submitted with options to include a banner page (e.g., `lpr -J "My Important Job" myfile.txt`), the printing system internally calls <i><b>printerbanner</b></i> with relevant arguments to generate and queue the banner alongside the actual document, ensuring proper job separation.


title: ASCII ART GENERATION
content:
Beyond its role in printer job separation, <i><b>printerbanner -t</b></i> serves as a versatile tool for generating large ASCII text. This capability can be leveraged in shell scripts, for creating decorative terminal art, or for enhancing documentation examples with prominent text, transforming a simple string into a visually striking large-character representation.


title: HISTORY
content:
The concept of banner pages originated in early computing environments to provide clear job separation and identification on shared mainframe or minicomputer printers. Utilities like <i><b>printerbanner</b></i> became standard components of Unix-like operating systems' print spooling systems (initially LPD, and later integrated into modern systems like CUPS). Its usage has evolved from purely physical print separation to also being a tool for generating large ASCII art for digital display or unique print jobs, especially when used with the <i>-t</i> option.


title: PARAMETERS
content:
<b><b>FORMAT</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The primary control string that defines the output format. It can include literal characters, escape sequences (e.g., <I>\n</I>, <I>\t</I>), and format specifiers (e.g., <I>%s</I>, <I>%d</I>) that indicate where and how the subsequent <I>ARGUMENT</I>s should be inserted and formatted.<br><br><b><b>ARGUMENT...</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more values (numbers, strings) that correspond to the format specifiers in the <I>FORMAT</I> string. These arguments are formatted and printed in the order they appear, according to their respective specifiers. If there are more arguments than specifiers, the <I>FORMAT</I> string is reused. If there are fewer, missing arguments for numeric specifiers typically result in 0 or an empty string for string specifiers.<br><br><b><b>Common Format Specifiers:</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;These are placed within the <I>FORMAT</I> string and begin with a percent sign (<I>%</I>), indicating the type and formatting of the corresponding argument.<br><br><b>  <I>%s</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints a string.<br><br><b>  <I>%d</I>, <I>%i</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints a signed decimal integer.<br><br><b>  <I>%u</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints an unsigned decimal integer.<br><br><b>  <I>%o</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints an unsigned octal integer.<br><br><b>  <I>%x</I>, <I>%X</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints an unsigned hexadecimal integer (lowercase and uppercase respectively).<br><br><b>  <I>%f</I>, <I>%F</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints a floating-point number in decimal notation.<br><br><b>  <I>%e</I>, <I>%E</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints a floating-point number in scientific (exponential) notation.<br><br><b>  <I>%g</I>, <I>%G</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints a floating-point number using either <I>%f</I>/<I>%F</I> or <I>%e</I>/<I>%E</I> format, whichever is more compact.<br><br><b>  <I>%c</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints a single character.<br><br><b>  <I>%%</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints a literal percent sign.<br><br><b><b>Common Escape Sequences:</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;These special character sequences are used within the <I>FORMAT</I> string to represent non-printable or special characters.<br><br><b>  <I>\n</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Newline character.<br><br><b>  <I>\t</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Horizontal tab character.<br><br><b>  <I>\\</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Literal backslash character.<br><br><b>  <I>\b</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Backspace character.<br><br><b>  <I>\r</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Carriage return character.<br><br><b>  <I>\f</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Form feed character.<br><br><b>  <I>\v</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Vertical tab character.<br><br><b>  <I>\a</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Alert (bell) character.<br><br><b>  <I>\0nnn</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Character whose ASCII code is the one- to three-digit octal value <I>nnn</I>.<br><br><b>  <I>\xhh</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Character whose ASCII code is the one- or two-digit hexadecimal value <I>hh</I>.<br><br>


title: DESCRIPTION
content:
The <I>printf</I> command is a powerful utility in Linux and Unix-like systems, widely used for precise formatting and printing of text and data. It emulates the behavior of the <I>printf</I> function from the C programming language, providing extensive control over how output is displayed.<br><br>Unlike <I>echo</I>, <I>printf</I> does not automatically append a newline character to the output, requiring explicit use of <I>\n</I>. This fine-grained control makes it invaluable in shell scripting for generating structured reports, custom messages, or data files with specific alignments, padding, and numerical representations (e.g., decimal, hexadecimal, scientific notation). It interprets a <I>FORMAT</I> string that contains literal text, escape sequences, and format specifiers, substituting corresponding <I>ARGUMENT</I>s into the output based on these specifiers.


title: CAVEATS
content:
Unlike <I>echo</I>, <B>printf</B> does not automatically add a newline character at the end of its output. A <I>\n</I> escape sequence must be explicitly included in the <I>FORMAT</I> string for a newline to be printed.<br><br>The behavior of <B>printf</B> can vary slightly depending on whether it's a shell built-in (e.g., in Bash, Zsh) or an external utility, though core functionality remains consistent.<br><br>If there are more arguments than format specifiers in the <I>FORMAT</I> string, <B>printf</B> will reuse the <I>FORMAT</I> string from the beginning for the remaining arguments. If there are fewer arguments, any unspecified format specifiers for numbers typically print 0, and for strings, an empty string.


title: FIELD WIDTH AND PRECISION
content:
<B>printf</B> offers advanced formatting options through modifiers within format specifiers. For example, <I>%10s</I> allocates a minimum width of 10 characters for a string, padding with spaces if necessary. <I>%-10s</I> left-justifies the string within that width. For numbers, <I>%.2f</I> formats a floating-point number to two decimal places, while <I>%05d</I> pads an integer with leading zeros to a width of 5 digits. Combined, <I>%width.precisiontype</I> offers fine-grained control over output appearance.


title: HISTORY
content:
The <B>printf</B> command originated from the <I>printf()</I> function in the C programming language, which has been a fundamental part of C since its early development. Its powerful and flexible text formatting capabilities made it an essential addition to Unix-like operating systems and later to shell scripting languages. It provides a more robust and controllable alternative to simpler print commands, especially when precise output alignment, numerical precision, or specific data representations are required. Its inclusion as a standard utility and shell built-in reflects its widespread utility in system administration and scripting.


title: SYNOPSIS
content:
Given that `<b>pro</b>` is <I>not</I> a standard Linux command, a universal synopsis demonstrating its invocation, options, and arguments cannot be provided. Its syntax would be entirely dependent on the specific application or script it belongs to, if it exists at all.


title: DESCRIPTION
content:
The command `<b>pro</b>` is <I>not</I> a standard or widely recognized utility found in typical Linux distributions or core utility packages. Unlike common commands such as `ls`, `grep`, or `awk`, `<b>pro</b>` does not have a universal manual page entry on most systems, indicating its absence as a default system tool. Its presence usually signifies a highly specialized application, a component of a specific software suite (e.g., the <I>Progress OpenEdge ABL</I> client, where 'pro' launches the client environment), or a custom script developed for a particular environment. It could also be a typo for other standard commands like `ps` (process status) or a reference to concepts like the `/proc` filesystem. Without specific contextual information, a general analysis of `<b>pro</b>` as a universal Linux command is not feasible.


title: CAVEATS
content:
Execution of `<b>pro</b>` on a standard Linux system will almost certainly result in a 'command not found' error. Users encountering `<b>pro</b>` in documentation or scripts should investigate its context thoroughly to determine if it refers to a specific, non-standard application or a custom-defined alias/function. Its behavior and availability are entirely contingent on a non-default software installation.


title: HISTORY
content:
There is <I>no</I> documented history of `<b>pro</b>` as a widely adopted or standard Linux command within the general Linux ecosystem. Its development and usage would be confined to niche applications or specific proprietary software systems, rather than being part of the common set of Linux utilities.


title: PARAMETERS
content:
<b>--tree</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display processes in a tree structure. Also available as <i>-t</i>.<br><br><b>--sort <COLUMN></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sort processes by a specific column (e.g., "pid", "cpu", "mem", "comm"). Also available as <i>-s <COLUMN></i>.<br><br><b>--watch</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable watch mode, refreshing output periodically like <i>top</i>. Also available as <i>-w</i>.<br><br><b>--filter <PATTERN></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filter processes by PID or name pattern. Also available as <i>-f <PATTERN></i>.<br><br><b>--group</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Group processes by command name. Also available as <i>-g</i>.<br><br><b>--color <WHEN></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Control color output (e.g., "always", "auto", "never"). Also available as <i>-C <WHEN></i>.<br><br><b>--theme <THEME></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Apply a predefined color theme (e.g., "dracula", "dark").<br><br><b>--no-header</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress the header row in the output.<br><br><b>--pid <PID></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show only processes matching the given PID. Also available as <i>-p <PID></i>.<br><br><b>--name <NAME></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show only processes matching the given name pattern. Also available as <i>-n <NAME></i>.<br><br><b>--format <FORMAT></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify output columns using a comma-separated list of column names. Also available as <i>-F <FORMAT></i>.<br><br><b>--hide-thread</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Hide kernel threads from the process list.<br><br><b>--width <NUM></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the screen width for column truncation.<br><br>


title: DESCRIPTION
content:
<i>procs</i> is a modern, user-friendly replacement for traditional Linux process viewers like <i>ps</i> and <i>top</i>. Built with Rust, it offers a visually enhanced and interactive experience for monitoring system processes. Key features include a colorful, customizable output, a process tree view, smart searching/filtering, and real-time watching capabilities. Unlike older tools, <i>procs</i> aims to provide more relevant information by default, such as CPU usage per core, GPU utilization, and network activity, presented in an easy-to-read format. It supports various output formats, theming, and allows for sorting and grouping processes, making it highly adaptable for both quick checks and detailed system analysis. Its intuitive interface and rich feature set streamline process management and troubleshooting on Unix-like systems.


title: CAVEATS
content:
<i>procs</i> is not a standard utility distributed with all Linux distributions and generally requires manual installation. While feature-rich, it might not provide the same level of granular customization for obscure process attributes as <i>ps</i> for highly specialized scripting needs. Its interactive features are best experienced in a compatible terminal emulator.


title: INTERACTIVE MODE & KEYBINDINGS
content:
When run without the <i>--watch</i> option, <i>procs</i> enters an interactive mode enabling dynamic sorting, filtering, and searching directly within the terminal using keyboard shortcuts. This allows for quick exploration of process data without re-executing the command.


title: CONFIGURATION FILE
content:
<i>procs</i> supports persistent configuration via a TOML file (e.g., <i>~/.config/procs/config.toml</i>). Users can customize default columns, sorting order, themes, and other preferences, allowing for a highly personalized experience across sessions.


title: HISTORY
content:
<i>procs</i> emerged as a modern alternative to traditional process monitoring tools, written in Rust. Its development aimed to address the shortcomings of older commands by integrating modern UI/UX principles, better default information, and interactive features. It quickly gained traction in the open-source community for its performance, visual appeal, and ease of use, becoming a popular choice for developers and system administrators seeking an upgrade to their command-line toolkit.


title: SYNOPSIS
content:
A standard synopsis for a generic 'proctl' command does not exist due to its non-standard nature.<br>If this command exists in a specific environment, its syntax and options would be unique to that particular implementation.


title: DESCRIPTION
content:
The command <i>proctl</i> is not a standard or widely recognized command-line utility found in most mainstream Linux distributions. Unlike common and well-documented tools such as <i>ps</i>, <i>top</i>, or <i>kill</i>, there is no official man page, widely distributed executable, or standard definition for a command named <i>proctl</i> across different Linux environments.<br><br>It is highly probable that 'proctl' is either a typographical error, potentially intended to refer to the <i>prctl(2)</i> system call (a system call for process-specific operations), or a very specific utility developed within a particular project, custom system, or niche environment. Without additional context about the specific system or software where this command is encountered, it is impossible to provide a definitive description of its purpose, syntax, or functionality for a generic 'proctl' command.


title: CAVEATS
content:
<b>Non-Standard Command:</b> The primary caveat is that <i>proctl</i> is not a standard Linux command. Users looking for process control should generally refer to well-documented utilities like <i>ps</i>, <i>top</i>, <i>htop</i>, <i>kill</i>, <i>nice</i>, or system calls like <i>prctl(2)</i>.<br><b>Potential Confusion:</b> It is often confused with the <i>prctl(2)</i> system call or might be a shorthand for 'process control utility' in a specialized context.<br><b>Lack of Documentation:</b> There is no general documentation (man pages, official guides) for a command named <i>proctl</i>, making its usage and behavior unpredictable outside of a specific, defined system.


title: POSSIBLE IMPLEMENTATIONS
content:
If encountered, a utility named <i>proctl</i> would likely be a specialized wrapper, script, or tool designed for very specific process management tasks unique to its environment. This could include managing particular daemon sets, custom resource control mechanisms, or inter-process communication within a closed or proprietary system.


title: HISTORY
content:
Given that <i>proctl</i> is not a standard Linux command, there is no general history of its development or widespread usage. Any command named <i>proctl</i> would have a history specific to the project or custom system where it was introduced and used.


title: SYNOPSIS
content:
N/A - As <b>profiles</b> is not a standard standalone command, there is no universal syntax. <br>Context-specific tools manage different types of profiles.


title: PARAMETERS
content:
<b>N/A</b><br>&nbsp;&nbsp;&nbsp;&nbsp;No standard command options exist for 'profiles' as a standalone utility. Parameters would be specific to context-dependent tools (e.g., <i>nmcli</i>, <i>firewall-cmd</i>).<br><br>


title: DESCRIPTION
content:
The <b>profiles</b> command is not a standard, standalone utility widely distributed across mainstream Linux distributions. While the term 'profiles' is extensively used within the Linux ecosystem to describe various configurations (e.g., user environment profiles like <i>.bashrc</i>, network connection profiles managed by <i>NetworkManager</i>, security profiles for <i>AppArmor</i> or <i>SELinux</i>, or systemd unit activation profiles), there isn't a single, unified <b>profiles</b> command to manage all of them. Users typically interact with specific tools relevant to the type of profile they are dealing with. For instance, <i>nmcli</i> for network profiles, <i>systemd-analyze</i> for systemd profiles, or direct editing of configuration files for user shell profiles. This entry describes what a hypothetical or context-specific 'profiles' command might encompass, or refers to the general concept of profile management in Linux.


title: CAVEATS
content:
The primary caveat is that <b>profiles</b> is <i>not</i> a standard, universal command in Linux. Users searching for this command may be looking for specific utilities that manage a particular type of profile (e.g., network, security, user environment). Relying on a non-existent generic 'profiles' command will lead to 'command not found' errors. Always refer to the documentation for specific software packages or subsystems (like <i>NetworkManager</i>, <i>firewalld</i>, <i>AppArmor</i>, <i>systemd</i>) when dealing with their respective 'profiles'.


title: TYPES OF PROFILES IN LINUX
content:
The term 'profile' in Linux refers to various configuration sets tailored for specific purposes:<br><b>User Environment Profiles</b>: Files like <i>.bashrc</i>, <i>.profile</i>, <i>.bash_profile</i> in a user's home directory that define shell settings, aliases, and environment variables.<br><b>Network Connection Profiles</b>: Configurations managed by tools like <i>NetworkManager</i> (e.g., stored in <i>/etc/NetworkManager/system-connections/</i>) defining how network interfaces connect to networks.<br><b>Security Profiles</b>: Rulesets for Mandatory Access Control (MAC) systems like <i>AppArmor</i> or <i>SELinux</i> that define what processes can and cannot do.<br><b>Firewall Zones/Profiles</b>: In <i>firewalld</i>, zones act as profiles defining trusted levels for network connections.<br><b>Systemd Unit Activation Profiles</b>: While not explicitly called 'profiles', <i>systemd</i> units are configured to activate under certain conditions, effectively acting as operational profiles.


title: HISTORY
content:
The concept of 'profiles' in Unix-like systems dates back to early days with user-specific configuration files like <i>.profile</i> and <i>.login</i>, which defined user environments. Over time, as Linux grew more complex, different subsystems introduced their own 'profile' mechanisms: network configurations, security policies, and system services. There's no single historical development of a 'profiles' command because the concept evolved independently within various components. The closest general concept is the the evolution of environment configuration and system-wide policy management.


title: PARAMETERS
content:
<b><i>paths...</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more paths (files or directories) to the source code that Progpilot should analyze.<br><br><b><b>--config</b> <i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to a JSON configuration file. This file can define analysis settings, includes/excludes, and custom rules. Defaults to <code>config.json</code> if not specified.<br><br><b><b>--output</b> <i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the file path where the analysis report will be saved. Defaults to <code>results.json</code>.<br><br><b><b>--output-format</b> <i>&lt;format&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the format for the output report. Common formats include <i>json</i> and <i>sarif</i>. Defaults to <i>json</i>.<br><br><b><b>--add-rules</b> <i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Loads additional custom rules defined in a separate configuration file, extending Progpilot's detection capabilities.<br><br><b><b>--skip-default-rules</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents Progpilot from loading its built-in, default security rules.<br><br><b><b>--disable-builtin-rules</b> <i>&lt;rules&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables specific built-in rules, provided as a comma-separated list of rule IDs.<br><br><b><b>--dev</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables development mode, often providing more verbose output or debugging information useful during tool development.<br><br><b><b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases the verbosity of Progpilot's output, showing more details about the analysis process.<br><br><b><b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Activates debug mode, providing even more detailed internal information for troubleshooting.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message, listing available options and their usage.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the current version of the Progpilot application.<br><br>


title: DESCRIPTION
content:
Progpilot is an open-source static analysis tool primarily designed for detecting security vulnerabilities in PHP, Twig, and Drupal code. It analyzes the source code without execution, identifying potential flaws such as Cross-Site Scripting (XSS), SQL Injection (SQLi), Remote Code Execution (RCE), Insecure Deserialization, and various other common web application vulnerabilities. <br><br>It functions by building an Abstract Syntax Tree (AST) of the analyzed code and then applying a set of predefined rules and data-flow analysis to trace potentially malicious data flows from sources (user inputs) to sinks (dangerous functions). Progpilot is particularly useful for integrating into Continuous Integration/Continuous Deployment (CI/CD) pipelines to catch security issues early in the development lifecycle, thereby improving code quality and reducing the risk of exploitable vulnerabilities in production systems. It supports various output formats, including JSON and SARIF, for easy integration with other tools.


title: CAVEATS
content:
As a static analysis tool, Progpilot may produce <i>false positives</i> (reporting vulnerabilities that aren't real) or <i>false negatives</i> (failing to detect actual vulnerabilities), requiring manual review. <br><br>Performance can be an issue on very large codebases due to the deep code analysis performed. It primarily supports PHP, Twig, and Drupal, so it's not suitable for other programming languages. <br><br>Running Progpilot itself requires a PHP runtime environment. Configuring complex custom rules can also have a learning curve.


title: CONFIGURATION FILE
content:
Progpilot's behavior is highly customizable via a JSON configuration file. This file allows users to define paths to include/exclude, specify custom rules, manage dependencies, and set various analysis options. This provides fine-grained control over the analysis scope and depth.


title: RULE DEFINITION
content:
Progpilot uses a rule engine that identifies vulnerabilities by tracing data flows from 'sources' (e.g., user inputs) to 'sinks' (e.g., dangerous functions like <code>eval()</code> or database queries) and checking if the data is properly 'sanitized' along the way. Rules can be defined to identify specific types of vulnerabilities based on these data flow patterns.


title: CI/CD INTEGRATION
content:
Due to its command-line interface and structured output formats (like JSON and SARIF), Progpilot is well-suited for integration into Continuous Integration/Continuous Delivery (CI/CD) pipelines. This enables automated security checks with every code commit or build, allowing developers to identify and fix security flaws early in the development lifecycle.


title: HISTORY
content:
Progpilot was created by Christophe Dumez and is an open-source project hosted on GitHub, with initial development activity starting around 2017-2018. It has seen continuous development since its inception, regularly receiving updates to improve its analysis capabilities, add new rules, enhance performance, and broaden its support for different PHP frameworks and versions. Its development has been driven by the need for a dedicated, robust static analysis tool for PHP security, integrated into modern development workflows.


title: PARAMETERS
content:
<b>-p &lt;PID&gt;, --pid=&lt;PID&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Monitor specific process ID(s).</i><br>Can be a comma-separated list of PIDs.<br><br><b>-w, --wait</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Wait for a supported command to start.</i><br>Exits only after the detected process has completed.<br><br><b>-m, --monitor</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Continuously monitor matching processes.</i><br>Updates the display until interrupted or processes complete.<br><br><b>-c &lt;CMD&gt;, --command=&lt;CMD&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Monitor specific command name(s).</i><br>Can be a comma-separated list of command names.<br><br><b>-q, --quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Suppress header and footer.</i><br>Shows only the progress line(s).<br><br><b>-o &lt;FILE&gt;, --output-file=&lt;FILE&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Redirect output to a specified file.</i><br><br><b>-s &lt;FIELD&gt;, --sort=&lt;FIELD&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Sort output by a specific field.</i><br>Fields include <b>pid</b>, <b>command</b>, <b>speed</b>, <b>done</b>, <b>left</b>, <b>eta</b>.<br><br><b>--full-path</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Display the full path of commands.</i><br><br><b>--no-op</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Only list supported processes, do not monitor.</i><br>Useful for checking which commands are detectable.<br><br><b>-v, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Display version information and exit.</i><br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Display help message and exit.</i><br><br>


title: DESCRIPTION
content:
<i>progress</i> is a lightweight C command that monitors the progress of currently running Linux commands, specifically those that perform file I/O operations. It's often referred to as <i>coreutils-progress-indicator</i> or <i>cp-progress</i>. It can attach to commands like <b>cp</b>, <b>mv</b>, <b>dd</b>, <b>tar</b>, <b>gzip</b>, <b>cat</b>, <b>rsync</b>, and certain package managers (<b>dpkg</b>, <b>rpm</b>).<br><br>Unlike <b>pv</b> which requires piping, <i>progress</i> works by inspecting the <i>/proc</i> filesystem. It scans for open file descriptors pointing to regular files and determines their current offset. This allows it to calculate the percentage completed, throughput, and estimated time of arrival (ETA) for long-running operations. It provides a real-time, user-friendly display of progress without needing to modify the original command invocation. This utility is invaluable for tasks where the native commands lack progress indicators, preventing users from waiting blindly during large file transfers or archival processes. It's an external utility, not part of coreutils, typically installed via your system's package manager.


title: CAVEATS
content:
The <i>progress</i> command relies heavily on the Linux <i>/proc</i> filesystem, making it a Linux-specific utility and generally not available on other Unix-like systems. It operates by analyzing file descriptors and offsets within <i>/proc/&lt;PID&gt;/fdinfo/</i>, which may not always perfectly reflect the true progress, especially for complex operations or those involving caching. <br><br>It can only monitor processes that are accessible to the user running <i>progress</i> (usually requires root privileges for processes owned by other users to be fully effective). It identifies processes based on heuristics for file I/O, meaning it might not detect all types of progress (e.g., network-based transfers like <b>wget</b> directly to stdout, or <b>scp</b> where the source/destination is remote). Short-lived operations might complete before <i>progress</i> can attach and report. Its accuracy can also be influenced by system load and kernel optimizations. It's a "best-effort" tool designed for convenience, not guaranteed precision.


title: HOW IT WORKS
content:
<i>progress</i> operates by scanning the <i>/proc</i> filesystem. For each running process, it inspects <i>/proc/&lt;PID&gt;/fd/</i> to identify open file descriptors that correspond to regular files. It then reads <i>/proc/&lt;PID&gt;/fdinfo/&lt;FD_NUMBER&gt;</i> to obtain the current <b>pos</b> (file offset) and <b>size</b> (file size) for the underlying file. By comparing these values, it calculates the percentage complete, current speed, and estimated time remaining. It constantly refreshes this information to provide a real-time update.


title: SUPPORTED COMMANDS
content:
<i>progress</i> aims to detect any running command performing significant file I/O. Commonly supported commands include: <b>cp</b>, <b>mv</b>, <b>dd</b>, <b>tar</b>, <b>gzip</b>, <b>gunzip</b>, <b>cat</b> (when copying), <b>rsync</b> (local operations), <b>dpkg</b>, <b>rpm</b>, and various archivers like <b>zip</b>, <b>unzip</b>, <b>xz</b>, <b>bzip2</b>, <b>bunzip2</b>. Its effectiveness depends on how the command performs its I/O and if it keeps file descriptors open predictably.


title: HISTORY
content:
The <i>progress</i> command originated from a patch for the <b>pv</b> (Pipe Viewer) utility. Initially, it was known as <b>pv -d</b> (disk mode), which allowed <b>pv</b> to monitor I/O operations directly on disk without requiring data to be piped through it. <br><br>Due to its distinct functionality and different author (Andrej Zverev), it eventually branched off into a standalone project. The motivation was to provide a simple, on-demand progress indicator for common <i>coreutils</i> commands like <b>cp</b>, <b>mv</b>, <b>dd</b>, <b>tar</b>, and <b>gzip</b>, which historically lacked built-in progress displays. <i>progress</i> filled this crucial gap, becoming a popular choice for users who needed to estimate completion times for long-running file operations without modifying the original command syntax. Its development has focused on robustness in identifying and monitoring relevant processes via the <i>/proc</i> filesystem.


title: PARAMETERS
content:
<b>[<i>project_file.jucer</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;An optional path to a JUCE project file (ending with <i>.jucer</i>). If provided, <b>Projucer</b> will attempt to open this project directly upon launch. If omitted, it will start with its welcome screen, allowing the user to create a new project or open an existing one through the GUI.<br><br>


title: DESCRIPTION
content:
The <b>Projucer</b> is a cross-platform application developed by JUCE, a comprehensive C++ framework primarily for audio, graphics, and desktop applications. It serves as an integrated development environment (IDE) and project management tool, central to the JUCE workflow. Developers use Projucer to create new JUCE projects, manage source files, add or remove JUCE modules (essential code libraries), configure build settings (such as compiler flags, preprocessor macros, and linker settings), and generate project files for various target IDEs and build systems.<br><br>It supports a wide range of export targets, including Visual Studio (Windows), Xcode (macOS/iOS), Linux Makefiles, CMake, Android Studio, and more. While <b>Projucer</b> can be launched from the command line, its core functionality and project manipulation capabilities are exclusively accessed through its rich graphical user interface (GUI), making it an indispensable tool for efficient JUCE framework development.


title: CAVEATS
content:
The <b>Projucer</b> is primarily a graphical user interface (GUI) application; it is not designed for command-line scripting or automated build processes. Its primary utility lies in interactive project setup and configuration. It is an integral part of the JUCE framework and is specific to managing JUCE projects, not general C++ projects. Installation typically involves downloading the JUCE framework, and the <b>projucer</b> executable may not be in standard system PATHs by default on all Linux distributions.


title: CROSS-PLATFORM PROJECT GENERATION
content:
A key strength of the <b>Projucer</b> is its ability to generate native project files for a multitude of operating systems and IDEs from a single, unified <i>.jucer</i> project definition. This streamlines cross-platform development, allowing developers to abstract away many platform-specific build configurations and ensuring consistent project structure across Windows, macOS, Linux, iOS, and Android.


title: MODULE MANAGEMENT
content:
One of the <b>Projucer</b>'s core features is its intuitive system for managing JUCE modules. Developers can easily add or remove official JUCE modules (e.g., <i>juce_audio_basics</i>, <i>juce_gui_basics</i>) and even custom modules. The <b>Projucer</b> automatically handles the necessary header paths, source file inclusions, and compiler flags within the generated project files, significantly simplifying dependency management for JUCE projects.


title: HISTORY
content:
The <b>Projucer</b> was initially developed by ROLI as an essential component of the JUCE C++ framework. Its development has consistently focused on simplifying the complex cross-platform project setup and maintenance workflows inherent in modern C++ development, particularly for audio and GUI applications. It has evolved alongside the JUCE framework, adapting to new platforms and build systems, becoming an indispensable tool for managing module dependencies and project configurations. In 2024, the JUCE framework and <b>Projucer</b> development were acquired by PACE Anti-Piracy, Inc.


title: SEE ALSO
content:
juce_framework (framework), cmake(1), make(1), visual_studio (IDE), xcode (IDE), android_studio (IDE)


title: SYNOPSIS
content:
promtool <I>command</I> [options] [arguments]<br><br>Common commands:<br><I>tsdb</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Tools for the Prometheus TSDB<br><I>check</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Check Prometheus configuration and rules<br><I>rule</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Tools for Prometheus rules<br><I>debug</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Tools for debugging<br><I>version</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print promtool version<br><I>help</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Help about any command


title: PARAMETERS
content:
<b><B>--help</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for <I>promtool</I> or a specific subcommand.<br><br><b><B>--version</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the <I>promtool</I> version and build information.<br><br><b><B>--log.level</B>=<I>level</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the logging verbosity level (e.g., <I>debug</I>, <I>info</I>).<br><br><b><B>--log.format</B>=<I>format</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the log output format (e.g., <I>logfmt</I>, <I>json</I>).<br><br><b><B>tsdb analyze</B> <B>--data-dir</B>=<I>path</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Analyzes and reports statistics about the Prometheus TSDB data in the specified directory.<br><br><b><B>tsdb compact</B> <B>--data-dir</B>=<I>path</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manually triggers compaction of TSDB blocks within the given data directory.<br><br><b><B>check config</B> <I>config_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Validates the syntax and semantics of a Prometheus configuration file.<br><br><b><B>check rules</B> <I>rule_files</I>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Validates the syntax and semantics of Prometheus recording and alert rule files.<br><br><b><B>rule convert</B> <B>--input</B>=<I>file</I> <B>--output</B>=<I>file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Converts Prometheus rule files between different formats (e.g., from JSON to YAML).<br><br>


title: DESCRIPTION
content:
promtool is a versatile command-line utility bundled with Prometheus, designed to assist administrators and developers in various tasks related to Prometheus deployments. It provides robust subcommands for managing and inspecting the underlying Time Series Database (TSDB), including operations like analyzing data integrity, forcing block compaction, and repairing metadata. Furthermore, it's indispensable for validating Prometheus configuration files and Alertmanager/recording rule files for syntax and semantic correctness before deployment, thus preventing potential runtime issues. It also includes tools for debugging Prometheus instances and converting rule formats between different specifications. Its comprehensive functionality makes it an essential tool for maintaining the health, integrity, and operational efficiency of any Prometheus monitoring system.


title: CAVEATS
content:
When using <I>tsdb</I> commands, especially <B>compact</B> or <B>repair</B>, it is critical to stop the Prometheus server first to prevent data corruption. <I>promtool</I> operates on files and directories, so ensure correct permissions. The <I>check</I> subcommands perform static analysis; they cannot guarantee runtime behavior or performance.


title: OFFLINE DATA MANAGEMENT
content:
<I>promtool</I> is crucial for offline maintenance tasks, allowing administrators to interact directly with the TSDB data files without the Prometheus server running, which is vital for recovery or analysis of large datasets.


title: PRE-DEPLOYMENT VALIDATION
content:
Utilizing <I>promtool check config</I> and <I>promtool check rules</I> in CI/CD pipelines ensures that configuration changes and rule updates are syntactically and semantically correct before deployment, preventing runtime errors.


title: HISTORY
content:
<I>promtool</I> emerged as a dedicated utility alongside the Prometheus server. As Prometheus's TSDB matured and configuration complexities grew, the need for specialized tools to manage data, validate configurations, and aid debugging became apparent. It consolidated various scripts and internal tools into a single, comprehensive binary, evolving with Prometheus to support new features like TSDB block operations and improved rule management.


title: PARAMETERS
content:
<b>login</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Authenticates the CLI tool with your PropelAuth account, typically by prompting for credentials or an API key.<br><br><b>users</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manages user accounts within your PropelAuth tenant. Common subcommands include <i>create</i>, <i>get</i>, <i>update</i>, and <i>delete</i>. For example, <i>propelauth users create --email example@domain.com --password <password></i>.<br><br><b>organizations</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Administers organizations and their members. Subcommands could include <i>create</i>, <i>get</i>, <i>update</i>, <i>delete</i>, and <i>add-user</i>. For instance, <i>propelauth organizations add-user --org-id <org_id> --user-id <user_id> --role Member</i>.<br><br><b>api-keys</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manages API keys for various services and integrations within your PropelAuth tenant, allowing for creation, listing, and revocation.<br><br><b>config</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays and manages the local PropelAuth CLI configuration, such as API endpoints and default credentials for different tenants or environments.<br><br><b>env</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets up local development environment variables and SDK configurations for PropelAuth integration, aiding in quick project setup and testing.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the main command or a specific subcommand, detailing available options and usage.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the installed version of the PropelAuth CLI tool.<br><br>


title: DESCRIPTION
content:
PropelAuth is an authentication and authorization platform for B2B SaaS applications. It provides robust tools for managing user authentication, single sign-on (SSO), organization roles, and access control. While primarily integrated via SDKs and web dashboards, a conceptual <b>propelauth</b> command-line interface (CLI) would offer developers and administrators direct, scriptable interaction with their PropelAuth tenants. This theoretical CLI would streamline common administrative tasks such as creating and managing users, organizations, and API keys, configuring development environments, and debugging authentication flows, thereby enhancing automation and operational efficiency for teams utilizing PropelAuth services. It would serve as a powerful tool for integrating authentication workflows into CI/CD pipelines and backend scripts.


title: CAVEATS
content:
It is important to note that a widely distributed, official standalone 'propelauth' command-line interface (CLI) in the traditional Linux utility sense is not prominently available or documented by PropelAuth. Interactions with PropelAuth are typically handled through their SDKs, direct API calls, or the web dashboard. The analysis provided here for a 'propelauth' command is largely based on hypothetical functionalities that such a CLI <i>would</i> offer if it existed, synthesizing common CLI patterns and PropelAuth's core services. Users should refer to PropelAuth's official documentation for current best practices regarding API and SDK usage.


title: PRIMARY INTEGRATION METHODS
content:
PropelAuth is primarily integrated into applications using language-specific SDKs (e.g., Python, Node.js, React) or direct REST API calls. These methods allow developers to embed authentication flows, manage user sessions, and enforce authorization rules directly within their application code. The PropelAuth web dashboard also provides a comprehensive interface for administrative tasks, including user management, organization configuration, and SSO setup.


title: HISTORY
content:
PropelAuth was founded to simplify user authentication and authorization for B2B SaaS companies, addressing the complexities often faced in building secure and scalable authentication systems from scratch. Launched to provide a robust, developer-friendly platform, it aims to abstract away the intricacies of identity management, including multi-tenancy, SSO, and role-based access control. While the service itself has evolved since its inception, focusing on API-first design and comprehensive SDKs for various programming languages, a dedicated, general-purpose command-line interface (CLI) for system-wide management has not been a primary focus of its public development. Instead, emphasis has been placed on programmatic integration via APIs and SDKs.


title: PARAMETERS
content:
<b><I>MODE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the type of resource to protect. <br> <b>file</b>: Protects files or directories. <br> <b>process</b>: Protects a running process.<br><br><b><I>TARGET</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The specific resource to apply protection to. For 'file' mode, this is the path to the file or directory. For 'process' mode, this is the PID or the exact command name of the process.<br><br><b>-i, --immutable</b><br>&nbsp;&nbsp;&nbsp;&nbsp;For 'file' mode: Makes a file or directory immutable, preventing any modification, deletion, or renaming, even by root. <br> For 'process' mode: Attempts to prevent the process from being terminated (requires elevated privileges and kernel support).<br><br><b>-d, --nodelete</b><br>&nbsp;&nbsp;&nbsp;&nbsp;For 'file' mode: Prevents a file or directory from being deleted or renamed, even if parent directory has write permissions.<br><br><b>-x, --noexec</b><br>&nbsp;&nbsp;&nbsp;&nbsp;For 'file' mode: Prevents a file from being executed. Applies to both regular files and scripts.<br><br><b>-L, --lock-strong</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a strong, persistent lock to the resource, requiring explicit unlocking with 'protector --unlock' before any modifications are permitted, even by root. This is a more robust form of protection than --immutable.<br><br><b>-u, --unlock</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes all protections applied by the <i>protector</i> command from the specified TARGET.<br><br><b>-l, --list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all resources currently protected by the <i>protector</i> command, along with their active protection attributes.<br><br><b>-f, --force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the operation, overriding certain warnings or soft protections (use with caution).<br><br>


title: DESCRIPTION
content:
The <i>protector</i> command is a hypothetical, advanced Linux utility designed to apply enhanced security attributes and locks to system resources. It aims to provide a unified interface for safeguarding critical files, directories, and running processes against unintended modification, deletion, or termination. By leveraging underlying kernel capabilities and extended file attributes, <i>protector</i> allows administrators to set strong, persistent or temporary protective measures. This can be crucial for system integrity, preventing accidental data loss, or ensuring the continuous operation of essential services. It consolidates functionalities typically found across various disparate commands, offering a streamlined approach to resource protection.


title: CAVEATS
content:
The <i>protector</i> command as described here is hypothetical and does not exist as a standard Linux utility. Its described functionalities, particularly strong locks and process protection, would require significant kernel-level integration and careful implementation to ensure system stability and security. Misuse of such a command, especially with options like <code>--lock-strong</code>, could potentially render critical system files inaccessible, even to root, leading to system instability or unbootable states. Always exercise extreme caution when dealing with file and process protections at this level.


title: USE CASES
content:
If implemented, <i>protector</i> could be invaluable for: <br> 1. Safeguarding critical configuration files (e.g., SSHd configs, web server configs) from accidental deletion or modification. <br> 2. Protecting sensitive log files from tampering. <br> 3. Ensuring essential daemon processes (like database servers) are not accidentally terminated. <br> 4. Setting up 'read-only' modes for sensitive directories temporarily. <br> 5. Preventing unauthorized execution of certain binaries.


title: PERMISSIONS AND PRIVILEGES
content:
Most operations of the <i>protector</i> command, especially those involving strong locks or process protection, would require root privileges. Non-root users may be able to query protection status (using <code>--list</code>) but could not apply or remove protections without elevated permissions, ensuring system integrity is maintained by authorized users only.


title: HISTORY
content:
The concept behind the <i>protector</i> command emerged from the ongoing need for a more unified and user-friendly interface to manage various forms of system resource protection. While existing tools like <b>chattr</b> provide powerful file system attributes, and kernel mechanisms exist for process control, <i>protector</i> was envisioned to consolidate and simplify these functionalities. Its hypothetical development would likely focus on abstracting complex system calls and providing a straightforward syntax, aiming to simplify security administration tasks for common protection scenarios. It would evolve from early prototypes demonstrating basic file immutability to include process-level safeguards and advanced locking mechanisms, striving for a comprehensive security management tool.


title: PARAMETERS
content:
<b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the help message for the <b>protonvpn</b> command or a specific subcommand.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the installed version of the Proton VPN CLI client.<br><br><b>init</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Initializes the Proton VPN CLI client, guiding through the login and setup process.<br><br><b>connect [<i>location</i>|<i>server_name</i>|<i>server_id</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to a Proton VPN server. Can connect to the fastest available, a specific location, or a specific server.<br><br><b>disconnect</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disconnects from the currently active Proton VPN connection.<br><br><b>reconnect</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reconnects to the last used Proton VPN server.<br><br><b>status</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the current connection status, including server details, protocol, and duration.<br><br><b>refresh</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Refreshes the local server list cache, ensuring up-to-date server information.<br><br><b>configure</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows configuration of general client settings, such as default protocol or DNS management.<br><br><b>locations</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all available Proton VPN server locations.<br><br><b>servers [<i>location</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists available servers within a specified location or all servers if no location is given.<br><br><b>server [<i>server_id</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays information about a specific server or connects to it.<br><br><b>schemes</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists available VPN protocols (e.g., OpenVPN UDP, OpenVPN TCP, WireGuard).<br><br><b>set <<i>setting</i>> <<i>value</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a specific client configuration option, such as protocol, DNS, or kill switch status.<br><br><b>get <<i>setting</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Retrieves the current value of a specific client configuration option.<br><br><b>disable <<i>feature</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables a specific feature, such as the Kill Switch or Network Lock.<br><br><b>enable <<i>feature</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables a specific feature, such as the Kill Switch or Network Lock.<br><br><b>killswitch [<i>status</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manages the Kill Switch feature, which blocks all network traffic if the VPN connection drops.<br><br><b>ns</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manages the Network Lock (equivalent to Kill Switch for DNS and routing), preventing leaks.<br><br><b>dns</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manages DNS resolution settings, allowing for custom DNS or Proton VPN's secure DNS.<br><br><b>logs</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays recent logs from the Proton VPN client for troubleshooting.<br><br><b>r</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs a speed test to Proton VPN servers to find the fastest connection.<br><br><b>upgrade</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Upgrades the Proton VPN CLI client to the latest available version.<br><br>


title: DESCRIPTION
content:
The <b>protonvpn</b> command is the official command-line interface (CLI) for Proton VPN on Linux systems. It provides a comprehensive set of tools to manage your VPN connection, configure settings, and interact with the Proton VPN service directly from the terminal. This client is ideal for users who prefer a minimalist interface, need to automate VPN connections via scripts, or manage their VPN on a headless server.<br><br>It supports various VPN protocols, including OpenVPN and WireGuard, and allows access to Proton VPN's extensive global server network, including specialized servers for Secure Core, P2P file sharing, and streaming. Key features configurable via the CLI include the Kill Switch (network lock), DNS management, and protocol selection. It's designed to offer a robust and secure VPN experience for advanced Linux users.


title: CAVEATS
content:
Using the <b>protonvpn</b> CLI client typically requires root or sudo privileges for network configuration changes. A valid Proton VPN subscription is necessary to utilize the service. Ensure your system's network manager (e.g., NetworkManager or systemd-networkd) is compatible and properly configured, as the client interacts with it to manage network interfaces and routing tables. The client also manages DNS settings, which might override local configurations.


title: PROTOCOL SUPPORT
content:
The <b>protonvpn</b> CLI client supports multiple VPN protocols, primarily <i>OpenVPN</i> (UDP and TCP) and <i>WireGuard</i>. Users can easily switch between these protocols using the <b>set protocol</b> command to optimize for speed or reliability depending on their network conditions.


title: SECURE CORE AND P2P SERVERS
content:
The client allows direct connection to Proton VPN's specialized servers. <i>Secure Core</i> servers route traffic through multiple secure locations to mitigate advanced network attacks. <i>P2P-optimized</i> servers provide enhanced performance for peer-to-peer file sharing. These can be selected during the connection process or specified using location/server commands.


title: HISTORY
content:
Proton VPN, founded by scientists who met at CERN, launched its VPN service following the success of ProtonMail, emphasizing privacy and security. The Linux CLI client was developed to cater to the significant portion of their user base on Linux systems, providing a native, robust, and scriptable alternative to GUI applications. Its development has focused on integrating deeply with Linux networking, supporting modern protocols, and offering advanced features like Kill Switch and Secure Core from the command line, reflecting a commitment to open-source and privacy-conscious users.


title: PARAMETERS
content:
<b><b>connect</b> [<i>SERVER</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Establishes a VPN connection. Can specify a server name (e.g., <i>US#1</i>), or use options like <i>--fastest</i>, <i>--random</i>, <i>--country</i>, etc.<br><br><b><b>disconnect</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disconnects from the currently active VPN server.<br><br><b><b>status</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the current connection status, including the connected server, protocol, and elapsed time.<br><br><b><b>login</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Authenticates your Proton VPN account using a browser-based login process.<br><br><b><b>logout</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Logs out your Proton VPN account from the CLI.<br><br><b><b>refresh</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Refreshes the internal server list and other configuration data.<br><br><b><b>servers</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists available Proton VPN servers with their details such as country, city, load, and supported features (P2P, Tor, Secure Core).<br><br><b><b>settings</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manages various client settings including default protocol, Kill Switch, DNS leak protection, NetShield, and split tunneling.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message for the command or subcommand and exits.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the program's version number and exits.<br><br><b><b>--fastest</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Used with connect</i>) Connects to the fastest available server based on latency.<br><br><b><b>--random</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Used with connect</i>) Connects to a random available server.<br><br><b><b>--country</b> <i>&lt;COUNTRY_CODE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Used with connect</i>) Connects to a server in a specific country, e.g., <i>--country US</i>.<br><br><b><b>--city</b> <i>&lt;CITY_NAME&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Used with connect</i>) Connects to a server in a specific city, e.g., <i>--city New York</i>.<br><br><b><b>--p2p</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Used with connect</i>) Connects to a P2P-optimized server.<br><br><b><b>--tor</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Used with connect</i>) Connects to a Tor-optimized server.<br><br><b><b>--free</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Used with connect</i>) Connects to a free server.<br><br><b><b>--secure-core</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Used with connect</i>) Connects to a Secure Core server for enhanced security.<br><br><b><b>--protocol</b> <i>&lt;PROTOCOL&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Used with connect or settings</i>) Specifies or sets the VPN protocol (e.g., <i>wireguard</i>, <i>openvpn_udp</i>, <i>openvpn_tcp</i>).<br><br><b><b>--killswitch</b> <i>&lt;on|off&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Used with settings</i>) Enables or disables the Kill Switch feature, which blocks internet traffic if the VPN connection drops.<br><br><b><b>--dnsleak-protection</b> <i>&lt;on|off&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Used with settings</i>) Enables or disables DNS leak protection to prevent DNS requests from being exposed.<br><br><b><b>--netshield</b> <i>&lt;on|off|strict&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Used with settings</i>) Configures NetShield, which blocks ads, malware, and trackers.<br><br><b><b>--split-tunneling</b> <i>&lt;on|off&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Used with settings</i>) Enables or disables split tunneling, allowing specific applications or IPs to bypass the VPN.<br><br><b><b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables debug logging for troubleshooting.<br><br><b><b>--persistent</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Used with connect</i>) Attempts to reconnect automatically if the VPN connection drops.<br><br>


title: DESCRIPTION
content:
The <b>protonvpn-cli</b> command-line interface provides a robust way to manage your Proton VPN connection directly from the terminal. It enables users to establish secure, encrypted VPN tunnels, protecting their online privacy and bypassing geo-restrictions. This tool supports various VPN protocols, server selection based on country, city, or features like P2P and Tor, and advanced security features such as Kill Switch, DNS Leak Protection, and NetShield. It's designed for users who prefer a non-GUI environment or need to automate VPN connections via scripts.


title: CAVEATS
content:
<ul><li>Requires <i>systemd-resolved</i> or a compatible DNS resolver for optimal DNS leak protection on some systems.</li><li>The Kill Switch functionality relies on <i>iptables</i> rules and requires proper setup; users should verify its behavior carefully to ensure no accidental internet access outside the VPN tunnel.</li><li>Updates to the CLI client should be performed regularly to ensure compatibility with Proton VPN's evolving infrastructure and security features.</li><li>Initial login using the <b>login</b> command requires a web browser for authentication, as it uses an OAuth flow.</li></ul>


title: INSTALLATION
content:
The <b>protonvpn-cli</b> is typically installed via official Proton VPN repositories for various Linux distributions or by downloading and installing the Python package. Users should follow the official installation guide for their specific OS to ensure all dependencies are met.


title: KILL SWITCH BEHAVIOR
content:
When enabled, the Kill Switch blocks all internet traffic outside the VPN tunnel. This is a critical privacy feature but can also prevent internet access if the VPN connection drops or if the <b>protonvpn-cli</b> service is not running or properly configured. Users must ensure the Kill Switch is correctly configured for their specific use case.


title: SYSTEM REQUIREMENTS
content:
The CLI tool requires Python 3 and several Python packages for its operation. It also relies on <i>systemd</i> for service management and typically requires <i>OpenVPN</i> or <i>WireGuard</i> client applications to be installed on the system, depending on the chosen VPN protocol.


title: HISTORY
content:
Proton VPN was launched by Proton Technologies AG, the company behind ProtonMail, with a strong focus on privacy and security. The <b>protonvpn-cli</b> tool was developed to provide a native, robust command-line interface for Linux users, integrating deeply with system network components. Its development reflects Proton VPN's commitment to open-source software and providing flexible tools for advanced users and automation.


title: SYNOPSIS
content:
<b>protonvpn-cli connect</b> [ <i>&lt;country_code&gt;</i> | <i>&lt;city_name&gt;</i> | <i>&lt;server_name&gt;</i> ] [ <i>OPTIONS</i> ]<br><b>protonvpn-cli connect</b> <b>--fastest</b> [ <i>OPTIONS</i> ]<br><b>protonvpn-cli connect</b> <b>--random</b> [ <i>OPTIONS</i> ]<br><b>protonvpn-cli connect</b> <b>--p2p</b> [ <i>OPTIONS</i> ]<br><b>protonvpn-cli connect</b> <b>--tor</b> [ <i>OPTIONS</i> ]<br><b>protonvpn-cli connect</b> <b>--secure-core</b> [ <i>OPTIONS</i> ]


title: PARAMETERS
content:
<b><i>&lt;country_code&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to the fastest server in the specified country (e.g., <i>CH</i>, <i>US</i>).<br><br><b><i>&lt;city_name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to the fastest server in the specified city (e.g., <i>Zurich</i>, <i>New York</i>).<br><br><b><i>&lt;server_name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to a specific server by its name (e.g., <i>CH-DE#3</i>, <i>US-NY#1</i>).<br><br><b><b>--fastest</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to the fastest available server based on current network conditions. This is the default if no arguments are provided.<br><br><b><b>--random</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to a random available server.<br><br><b><b>--p2p</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to the fastest available P2P-optimized server.<br><br><b><b>--tor</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to the fastest available Tor-optimized server.<br><br><b><b>--secure-core</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to the fastest available Secure Core server.<br><br><b><b>--exit-country</b> <i>&lt;country_code&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When using <b>--secure-core</b>, specifies the exit country for the connection.<br><br><b><b>--protocol</b> {<i>udp</i>|<i>tcp</i>|<i>wireguard</i>}</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the VPN protocol to use for the connection. Defaults to <i>WireGuard</i> if available, then <i>UDP</i>, then <i>TCP</i>.<br><br><b><b>--no-kill-switch</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables the kill switch for the current connection, overriding the global setting.<br><br><b><b>--no-dns-leak-protection</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables DNS leak protection for the current connection, overriding the global setting.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays more detailed output during the connection process.<br><br><b><b>-d</b>, <b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays debug information, useful for troubleshooting.<br><br>


title: DESCRIPTION
content:
The <b>protonvpn-cli connect</b> command is the core function of the ProtonVPN Linux command-line interface, enabling users to establish a secure VPN connection to the ProtonVPN network. It abstracts the complexities of <i>OpenVPN</i> or <i>WireGuard</i> configurations, allowing users to simply specify their desired connection parameters such as a country, city, specific server, or connection type (e.g., fastest, random, P2P, Tor, Secure Core). The command intelligently selects the best server based on criteria and protocol preferences. It also integrates with features like Kill Switch and DNS leak protection, ensuring a high level of privacy and security by preventing accidental data exposure. This command is essential for seamless, automated, and flexible VPN management on Linux systems.


title: CAVEATS
content:
Using <b>protonvpn-cli connect</b> requires the <b>protonvpn-cli</b> client to be properly installed and configured. Users must be logged in using <b>protonvpn-cli login</b>. The command typically requires root privileges (via <b>sudo</b>) to modify network settings. Certain connection types (P2P, Tor, Secure Core) may require a paid ProtonVPN subscription. Underlying dependencies like <i>OpenVPN</i> or <i>WireGuard</i> must also be installed on the system.


title: PREREQUISITES
content:
Before using <b>protonvpn-cli connect</b>, ensure the <b>protonvpn-cli</b> client is installed, the user has successfully authenticated via <b>protonvpn-cli login</b>, and necessary VPN backend software (like <i>OpenVPN</i> or <i>WireGuard</i>) is also installed and accessible.


title: AUTOMATIC RECONNECTION & KILL SWITCH
content:
The ProtonVPN CLI often attempts to automatically reconnect if the VPN connection drops, enhancing reliability. When globally enabled via <b>protonvpn-cli settings</b>, the Kill Switch feature ensures that all network traffic is blocked if the VPN connection fails, preventing accidental IP leaks. These can be temporarily overridden for a specific connection using <b>--no-kill-switch</b> or <b>--no-dns-leak-protection</b>.


title: HISTORY
content:
ProtonVPN launched its official Linux CLI in 2017, providing a dedicated and robust command-line interface for managing VPN connections. This significantly improved the user experience for Linux users, replacing manual <i>OpenVPN</i> configurations. The CLI, and specifically the <b>connect</b> command, has evolved over time, adding crucial features like WireGuard support, a Kill Switch, DNS leak protection, and integrating with system services like <i>systemd</i> for better stability and auto-start capabilities. The <b>connect</b> command remains central to its functionality, providing a simplified yet powerful way to establish complex VPN connections.


title: SEE ALSO
content:
protonvpn-cli login(1), protonvpn-cli disconnect(1), protonvpn-cli status(1), protonvpn-cli settings(1), protonvpn-cli servers(1), openvpn(8), wg(8), nmcli(1)


title: SYNOPSIS
content:
<b>protonvpn-connect</b> [<i>COMMAND</i>] [<i>OPTIONS</i>] [<i>ARGUMENTS</i>]<br><br>Specific forms:<br><b>protonvpn-connect</b> <i>connect</i> [<i>SERVER_NAME</i>|<i>COUNTRY_CODE</i>] [<i>OPTIONS</i>]<br><b>protonvpn-connect</b> <i>disconnect</i><br><b>protonvpn-connect</b> <i>status</i><br><b>protonvpn-connect</b> <i>reconnect</i><br><b>protonvpn-connect</b> <i>setup</i><br><b>protonvpn-connect</b> <i>display-servers</i><br><b>protonvpn-connect</b> [<i>-h</i>|<i>--help</i>|<i>-v</i>|<i>--version</i>]


title: PARAMETERS
content:
<b><i>connect</i>, <i>-c</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to the best available server, or to a specified server or country code.<br><br><b><i>disconnect</i>, <i>-d</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disconnects from the current VPN connection.<br><br><b><i>status</i>, <i>-s</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the current VPN connection status.<br><br><b><i>reconnect</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reconnects to the last connected VPN server.<br><br><b><i>setup</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Guides through the initial setup process for the Proton VPN CLI.<br><br><b><i>display-servers</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all available Proton VPN servers.<br><br><b><i>--help</i>, <i>-h</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br><b><i>--version</i>, <i>-v</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the CLI version and exit.<br><br><b><i>--protocol</i> <<i>protocol</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the VPN protocol to use (e.g., <i>OpenVPN</i>, <i>WireGuard</i>).<br><br><b><i>--server</i> <<i>server_name</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to a specific server by its name (e.g., <i>US#1</i>).<br><br><b><i>--cc</i> <<i>country_code</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to a server in a specific country using its 2-letter country code (e.g., <i>US</i>).<br><br><b><i>--fastest</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to the fastest available server based on current network conditions.<br><br><b><i>--p2p</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to a server optimized for P2P (peer-to-peer) traffic.<br><br><b><i>--tor</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to a Tor-enabled server, routing traffic through the Tor network.<br><br><b><i>--secure-core</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to a Secure Core server, routing traffic through multiple Proton VPN servers.<br><br><b><i>--persistent</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempts to automatically reconnect if the VPN connection drops.<br><br>


title: DESCRIPTION
content:
The <b>protonvpn-connect</b> command is the primary command-line interface (CLI) tool for interacting with the Proton VPN service on Linux. It allows users to establish, manage, and terminate VPN connections without needing a graphical user interface. This utility provides granular control over connection parameters, enabling users to select specific servers, countries, VPN protocols (like <i>WireGuard</i> or <i>OpenVPN</i>), and advanced features such as <i>Secure Core</i>, <i>P2P</i>, or <i>Tor</i> servers. It also facilitates checking connection status, disconnecting, and performing initial setup of the Proton VPN CLI. Designed for automation and headless environments, <b>protonvpn-connect</b> offers a powerful way to secure internet traffic and bypass geo-restrictions directly from the terminal. Its robust set of options caters to both casual users seeking quick connectivity and advanced users requiring precise control over their VPN settings.


title: CAVEATS
content:
Requires an active Proton VPN account with a valid subscription.<br>Relies on underlying VPN clients like <i>OpenVPN</i> or <i>WireGuard tools</i> being installed and configured on the system.<br>Certain operations, such as modifying network interfaces, require appropriate system permissions, often handled by the CLI's internal <i>sudo</i> mechanisms.<br>DNS resolution behavior can be complex on Linux, especially with <i>systemd-resolved</i>, and may require specific configurations or the <i>--no-dns-reset</i> option.


title: CONFIGURATION
content:
The <b>protonvpn-cli</b> command (often installed alongside <b>protonvpn-connect</b>) provides extensive configuration options. This includes managing account credentials, setting default VPN protocols, enabling/disabling the kill switch, and configuring DNS. Users are advised to consult <b>protonvpn-cli config --help</b> for detailed configuration options.


title: SERVER NAMING CONVENTION
content:
Proton VPN servers are typically named with a country code followed by a number (e.g., <i>US#1</i>, <i>CH#5</i>). Special servers designated for <i>P2P</i>, <i>Tor</i>, or <i>Secure Core</i> traffic might have specific designations or are implicitly selected via dedicated command-line flags (e.g., <i>--p2p</i>, <i>--tor</i>, <i>--secure-core</i>).


title: HISTORY
content:
The <b>protonvpn-connect</b> command is an integral part of the official Proton VPN Linux CLI client, developed and maintained by Proton AG. Its introduction significantly enhanced Linux users' ability to access the Proton VPN service directly from the terminal, providing a robust alternative to graphical clients. It has undergone continuous development, with updates introducing support for new protocols like <i>WireGuard</i>, improved server selection logic, and integration of advanced features such as <i>Secure Core</i> and <i>Kill Switch</i>, reflecting Proton VPN's commitment to privacy and security on the Linux platform.


title: PARAMETERS
content:
<b>-b, --bail</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stop running tests immediately upon the first test file failure.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a brief help message and exit.<br><br><b>-I <i>dir</i>, --inc <i>dir</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add <i>dir</i> to the Perl include path (<b>@INC</b>).<br><br><b>-j <i>N</i>, --jobs <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run tests in parallel with <i>N</i> concurrent jobs.<br><br><b>-l, --lib</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add 'blib/lib' and 'blib/arch' to <b>@INC</b>, useful for testing modules during development.<br><br><b>-P, --parseable</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output test results in a machine-parseable format (TAP).<br><br><b>-q, --quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress normal test output; only show the summary and any failures.<br><br><b>-r, --recurse</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Recursively search subdirectories for test files.<br><br><b>-s, --shuffle</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run test files in a random order.<br><br><b>-t, --timer</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the time taken for each test file to run.<br><br><b>-T, --trap</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Trap child process errors and report them as test failures.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display verbose output for each test, showing individual assertions.<br><br><b>-V, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display version information and exit.<br><br><b>-x <i>path</i>, --exec <i>path</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the Perl interpreter to use for running tests (e.g., <b>perl -w</b>).<br><br><b>--ext <i>suffix</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Look for test files ending with the specified <i>suffix</i> instead of <b>.t</b>.<br><br><b>--formatter <i>module</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use a custom Perl module to format test results.<br><br><b>--input <i>type</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the input format type, e.g., <b>TAP</b>.<br><br><b>--merge</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Merge state files from previous runs to run only failed tests.<br><br><b>--no-bail</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not stop on the first test file failure (default behavior).<br><br><b>--only</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only run tests that failed on the previous run (requires a state file).<br><br><b>--order <i>type</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the order in which to run tests: <b>alpha</b>, <b>file</b>, <b>random</b>, or <b>test</b>.<br><br><b>--state <i>file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Read and write test state information to the specified <i>file</i>.<br><br><b>--state-only</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Update the state file without actually running tests.<br><br><b>--suppress-state</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not read or write any state information.<br><br><b>--tty</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force TTY-style progress output, even if stdout is not a TTY.<br><br>


title: DESCRIPTION
content:
<i>prove</i> is a powerful command-line utility bundled with the Perl distribution, designed to execute Perl test scripts. Acting as an advanced front-end to Perl's <B>Test::Harness</B> module, it processes one or more test files (typically with a <B>.t</B> extension) and reports their results. <br><br>It fully supports the Test Anything Protocol (TAP) output generated by standard Perl test modules, presenting detailed and human-readable test outcomes. <B>prove</B> offers extensive options for controlling test execution, including parallel test runs, selective test execution, verbose output, and robust failure handling. This makes it an indispensable tool for Perl developers, essential for unit testing, integration testing, and automated build systems.


title: CAVEATS
content:
<i>prove</i> is primarily designed for running Perl test scripts that adhere to the Test Anything Protocol (TAP). It may not be suitable for testing applications written in other programming languages without a TAP output adapter. When using parallel execution (<b>-j</b> option), ensure your test suite is robust against race conditions and inter-test dependencies, as parallel runs can expose subtle issues that might not appear in serial execution.


title: TAP (TEST ANYTHING PROTOCOL)
content:
<i>prove</i>'s default output format is based on TAP, a simple text-based protocol for reporting test results. Understanding TAP is beneficial for writing custom test modules or parsing <i>prove</i>'s output programmatically.


title: EXIT STATUS
content:
The exit status of <i>prove</i> is crucial for scripting and CI pipelines: a status of <b>0</b> indicates all tests passed, while any non-zero status signifies test failures or other errors. This allows build systems to reliably determine the success or failure of a test run.


title: ENVIRONMENT VARIABLES
content:
<i>prove</i>'s behavior can be influenced by environment variables, notably <b>HARNESS_OPTIONS</b>, which allows setting default options (e.g., verbose mode, timer) without explicitly typing them on the command line for every execution.


title: HISTORY
content:
Before the advent of <i>prove</i>, Perl developers typically relied on `make test` or manual execution of test scripts via `perl -MTest::Harness -e 'runtests @ARGV'`. While functional, these methods lacked the flexibility and advanced features that modern testing demands. <br><br><i>prove</i> was introduced as a dedicated command-line tool, built atop the existing <B>Test::Harness</B> framework, to provide a more user-friendly and feature-rich interface for running Perl unit tests. Its development focused on simplifying test execution, offering options like parallel processing, verbose output, and better integration with continuous integration systems through its support for TAP. It quickly became the standard tool for automated Perl testing.


title: PARAMETERS
content:
<b>-t, --type &lt;type&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the proxy type (e.g., SOCKS4, SOCKS5, HTTP).<br><br><b>-a, --address &lt;host&gt;:&lt;port&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the proxy server's host address and port number.<br><br><b>-U, --username &lt;user&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provide a username for proxy authentication, if required.<br><br><b>-P, --password &lt;pass&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provide a password for proxy authentication, if required.<br><br><b>-c, --config &lt;file&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use an alternative configuration file for proxy settings instead of default.<br><br><b>-D, --dns</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force DNS resolution requests to also go through the specified proxy server.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output, showing more details about the proxying process.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message with command usage and options, then exit.<br><br>


title: DESCRIPTION
content:
The `proxify` command is a conceptual utility designed to execute another command while routing all its network traffic through a specified proxy server (e.g., SOCKS, HTTP). It is not a standard Linux command but rather a common pattern implemented via custom shell scripts or as a wrapper around existing tools like <I>proxychains</I> or <I>tsocks</I>. Its primary purpose is to anonymize connections, bypass geo-restrictions, or access specific network segments by channeling data through an intermediary. <br><br>When executed, `proxify` would typically configure the execution environment to ensure that network-aware system calls made by the target command are intercepted and redirected to the proxy. This often involves leveraging mechanisms like <I>LD_PRELOAD</I> to inject a library that hooks network functions. This method provides a powerful way to enforce proxy usage for almost any command-line application, making it invaluable for privacy, security, and network management tasks.


title: CAVEATS
content:
The `proxify` command, being a non-standard concept, is highly dependent on its specific implementation. Most implementations rely on <I>LD_PRELOAD</I> which can have limitations: <br>1. <B>Non-Standard Nature:</B> It's not a pre-installed Linux command; you'd typically find it as a custom script or part of a specialized tool. <br>2. <B>Bypass Risks:</B> Applications using static linking, making direct kernel calls, or implementing custom network stacks might bypass the proxy, leading to traffic or DNS leaks. <br>3. <B>Performance Overhead:</B> Routing traffic through a proxy adds latency and can reduce network performance. <br>4. <B>Security Concerns:</B> The security of your traffic depends entirely on the trustworthiness of the proxy server. <br>5. <B>Compatibility:</B> Not all applications may behave correctly when forced through a proxy this way, especially those with complex network interactions.


title: HOW IT WORKS (CONCEPTUAL)
content:
A hypothetical `proxify` command typically works by modifying the execution environment of the target command. This often involves setting the <I>LD_PRELOAD</I> environment variable to inject a custom shared library (e.g., <I>proxychains.so</I>) into the process space of the command being executed. This injected library then intercepts standard network-related system calls (like <I>connect()</I>, <I>send()</I>, <I>recv()</I>, <I>socket()</I>) made by the target application. Instead of allowing these calls to directly interact with the operating system's network stack, the library redirects them through the configured proxy server. For DNS resolution, it might also intercept functions like <I>getaddrinfo()</I> or <I>gethostbyname()</I> to ensure hostnames are resolved via the proxy, preventing potential DNS leaks.


title: TYPICAL USAGE PATTERNS
content:
The primary use case for `proxify` is to execute any network-aware command or script as if its network traffic originates from the proxy server's location. For example, to check your external IP address through a SOCKS5 proxy running on localhost port 9050, you might use: <br><br><I>proxify -t SOCKS5 -a 127.0.0.1:9050 curl ifconfig.me</I><br><br>It's frequently employed with command-line tools that don't natively support proxy settings, for security research, bypassing geo-restrictions, or accessing resources on specific networks without direct routing. It can also be used to chain multiple proxies for enhanced anonymity, depending on the underlying implementation's capabilities.


title: HISTORY
content:
While not a specific command with a unified history, the concept of 'proxifying' applications on Linux has evolved from basic environment variable settings (like <I>http_proxy</I>) to more sophisticated methods. Tools like <I>tsocks</I> (Transparent SOCKS) and <I>proxychains</I> (initially ProxyChains-3, later proxychains-ng) emerged to provide application-agnostic proxying by leveraging <I>LD_PRELOAD</I> to hook network functions. A 'proxify' script would typically automate and simplify the use of such underlying mechanisms, abstracting away their complexities and providing a consistent command-line interface for users.


title: SYNOPSIS
content:
<b>General Usage:</b><br><code>prqlc &lt;SUBCOMMAND&gt; [OPTIONS] [ARGS]</code><br><br><b>Common Usage (Compile):</b><br><code>prqlc compile [OPTIONS] [INPUT_FILE]</code><br><i>(If <b>INPUT_FILE</b> is omitted, reads from stdin. Output defaults to stdout.)</i>


title: PARAMETERS
content:
<b><code>&lt;INPUT_FILE&gt;</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the PRQL source file to be compiled. If not provided, <i>prqlc</i> reads the PRQL query from standard input (stdin).<br><br><b><code>-e, --entry &lt;entry&gt;</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the entry point (the last pipeline or transform) within the PRQL query that should be compiled to SQL. Useful for multi-pipeline PRQL files.<br><br><b><code>-f, --format</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Formats the generated SQL output for better readability, applying standard SQL formatting conventions.<br><br><b><code>-o, --output &lt;output&gt;</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the output file where the compiled SQL will be written. If not provided, the SQL is written to standard output (stdout).<br><br><b><code>-t, --target &lt;target&gt;</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the target SQL dialect for compilation. This optimizes the generated SQL for specific database systems. Possible values include: <i>ansi</i> (default), <i>bigquery</i>, <i>clickhouse</i>, <i>duckdb</i>, <i>generic</i>, <i>mysql</i>, <i>postgresql</i>, <i>snowflake</i>, <i>mssql</i>.<br><br><b><code>--color &lt;color&gt;</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls the use of colored output for messages. Possible values: <i>auto</i> (default, uses color if terminal supports it), <i>always</i>, <i>never</i>.<br><br><b><code>-h, --help</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the <i>prqlc</i> command or a specific subcommand.<br><br><b><code>-V, --version</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information for the <i>prqlc</i> compiler.<br><br>


title: DESCRIPTION
content:
<i>prqlc</i> is the command-line interface for the PRQL compiler. PRQL (Pipelined Relational Query Language) is a modern, human-readable language designed to transform and query data, offering a more intuitive and expressive alternative to traditional SQL for many common tasks. Its core philosophy revolves around data pipelines, where data flows through a series of transformations. The `prqlc` tool's primary function is to compile these PRQL queries into standard SQL, making it compatible with virtually any relational database system, from PostgreSQL and MySQL to Snowflake and BigQuery. Beyond compilation, `prqlc` also provides utilities for formatting PRQL code for readability, parsing the PRQL Abstract Syntax Tree, resolving the Relational Query, and debugging compiler issues. This makes it a comprehensive tool for developers and data analysts looking to streamline their data manipulation workflows with a more declarative and readable language.


title: CAVEATS
content:
PRQL is a relatively new and actively developed language; its feature set and compiler capabilities are continuously evolving, which might lead to changes in syntax or supported SQL constructs. While <i>prqlc</i> aims for broad SQL compatibility, very complex or highly vendor-specific SQL features might not have direct PRQL equivalents or optimal compilation. Users should consult the PRQL documentation for the latest language and compiler features.


title: SUBCOMMANDS
content:
Beyond the primary <code>compile</code> subcommand, <i>prqlc</i> offers several other functionalities accessible via subcommands:<br><ul><li><b>debug</b>: Provides commands for debugging the compiler's internal processes.</li><li><b>fmt</b>: Formats PRQL source code according to standard PRQL style guidelines, improving readability.</li><li><b>list</b>: Lists available compiler options and targets.</li><li><b>parse</b>: Parses a PRQL query and prints its Abstract Syntax Tree (AST), useful for understanding the query's structure.</li><li><b>resolve</b>: Resolves a PRQL query and prints its Relational Query (RQ), which is an intermediate representation before SQL generation.</li></ul>


title: INPUT/OUTPUT FLEXIBILITY
content:
<i>prqlc</i> is designed for flexibility in scripting and command-line piping. It can read PRQL queries from a specified file path or seamlessly from standard input (stdin). Similarly, the compiled SQL output can be directed to a specified file or written to standard output (stdout), allowing for easy integration into shell scripts or automated workflows.


title: HISTORY
content:
PRQL was conceived in the early 2020s to address the perceived complexities and verbosity of SQL, aiming to provide a more intuitive, pipeline-oriented, and human-readable language for data transformation. The <i>prqlc</i> compiler is the core tool that enables this vision by translating PRQL code into standard SQL, thereby making it compatible with existing relational database infrastructure. Its development has focused on creating a language that is both powerful and easy to use, rapidly gaining adoption within the data community for its innovative approach to querying and transforming data.


title: SYNOPSIS
content:
There is no standard or defined command synopsis for prt-get, as it is <B>not</B> a recognized Linux command. Its syntax would be entirely dependent on any custom script or alias that might (rarely) define it. In a default Linux environment, prt-get simply does not exist as an executable program.


title: DESCRIPTION
content:
prt-get is <B>not</B> a standard or recognized command in common Linux distributions such as Debian, Ubuntu, Red Hat, Fedora, CentOS, or Arch Linux.<br><br>It is overwhelmingly likely that a user attempting to invoke prt-get has made a typographical error and intended to use a widely recognized package management command. The most common commands that prt-get resembles in a typo are:<br><br><i><B>apt-get</B></i>: The command-line tool for the Advanced Package Tool (APT) system, predominantly used in Debian-based distributions (e.g., Debian, Ubuntu, Linux Mint).<br><br><i><B>yum</B></i> or <i><B>dnf</B></i>: The package managers used in Red Hat-based distributions (e.g., Fedora, CentOS, RHEL). dnf has largely superseded yum in newer versions.<br><br>These package managers are fundamental for system administration, allowing users to install, update, upgrade, remove, and manage software packages on their system. Since prt-get has no defined functionality, executing it will invariably lead to a "command not found" error.


title: CAVEATS
content:
The command 'prt-get' is <B>not</B> a recognized Linux command in standard installations. Attempting to execute it will result in a "command not found" error. Users should verify the correct spelling of package management commands (e.g., <B>apt-get</B>, <B>yum</B>, <B>dnf</B>) to avoid such errors.


title: <B>COMMON TYPOGRAPHICAL ERRORS</B>
content:
Users frequently make minor spelling mistakes when typing commands, especially for tools like package managers that are used often but have similar-sounding or structured names. prt-get is a prime example of such a typo, often intended to be <B>apt-get</B>. Always double-check command spelling, especially before running commands with <B>sudo</B>.


title: <B>SHELL ALIASES AND FUNCTIONS</B>
content:
While prt-get is not a standard command, a user could theoretically define an alias or shell function in their `.bashrc` or `.zshrc` file to make prt-get execute another command. However, this is highly unusual and not recommended, as it could lead to confusion.


title: HISTORY
content:
The concept of prt-get as a command has no official history or development path, as it is <B>not</B> a legitimate Linux utility. Its "history" is primarily rooted in common typographical errors made by users accustomed to powerful and frequently used package management commands like <B>apt-get</B> or <B>yum</B>. The evolution of Linux package management itself, from manual compilation of software from source to sophisticated binary package managers, has created a landscape where users interact with commands like <B>apt-get</B> and <B>yum</B>/<B>dnf</B> on a daily basis. The similarity in naming conventions (`*-get`) often leads to such accidental mistypings, highlighting the omnipresent nature of package management in Linux system administration.


title: SEE ALSO
content:
<B>apt-get(8)</B>: Command-line interface for the APT package management system., <B>yum(8)</B>: Yellowdog Updater, Modified, a package management utility for RPM-based Linux systems., <B>dnf(8)</B>: Dandified YUM, the next-generation package manager for RPM-based systems., <B>dpkg(1)</B>: Debian package manager, a low-level tool for Debian packages., <B>rpm(8)</B>: Red Hat Package Manager, a low-level tool for RPM packages., <B>man(1)</B>: Display online manual pages. Useful for finding information on actual commands.


title: PARAMETERS
content:
<b>N/A</b><br>&nbsp;&nbsp;&nbsp;&nbsp;No standard parameters are defined for a non-existent command.<br><br>


title: DESCRIPTION
content:
The command <I>prtstat</I> is not a standard Linux command. It does not appear in common Linux distributions' core utilities or widely used packages. It is highly probable that this is a typo, possibly intended for <I>prstat</I> (a command used for reporting active process statistics on Solaris operating systems), or perhaps a custom script or alias specific to a particular environment. Users looking for similar functionalities on Linux typically use commands like <I>ps</I> for process status, <I>top</I> for real-time process monitoring, <I>vmstat</I> for virtual memory statistics, <I>iostat</I> for I/O statistics, <I>netstat</I> or <I>ss</I> for network connections, and <I>lsof</I> for listing open files. This entry explains the non-existence of <I>prtstat</I> in standard Linux environments.


title: CAVEATS
content:
The command <I>prtstat</I> is not part of standard Linux command-line utilities. Attempting to execute it on a typical Linux system will result in a 'command not found' error unless a user-defined alias, script, or specialized third-party tool named <I>prtstat</I> has been installed.


title: COMMON LINUX EQUIVALENTS FOR SYSTEM STATISTICS
content:
While <I>prtstat</I> is not a standard Linux command, users often seek information similar to what <I>prstat</I> provides on Solaris or general system statistics. Linux offers a robust set of tools for this purpose. <I>ps</I> reports a snapshot of current processes.<br><I>top</I> provides a dynamic real-time view of a running system.<br><I>vmstat</I> reports information about processes, memory, paging, block IO, traps, and CPU activity.<br><I>iostat</I> reports CPU utilization and I/O statistics for devices, partitions, and network filesystems.<br><I>netstat</I> (or its modern replacement <I>ss</I>) displays network connections, routing tables, and interface statistics.<br><I>lsof</I> lists open files, showing which processes are using which files or network sockets.


title: HISTORY
content:
Information regarding the development and usage of a standard <I>prtstat</I> command on Linux is unavailable, as it is not a recognized utility. Any existing usage would be specific to custom implementations or specific environments where such a command might have been created or ported.


title: SYNOPSIS
content:
<b>`ps [options]`</b><br><br>Common invocation styles include:<br>&nbsp;&nbsp;<b>`ps aux`</b> <I>(BSD style, showing all users' processes, with and without a TTY)</I><br>&nbsp;&nbsp;<b>`ps -ef`</b> <I>(System V style, showing every process in full format)</I><br>&nbsp;&nbsp;<b>`ps -U <I>user</I> -f`</b> <I>(GNU/System V style, processes by user, full format)</I>


title: PARAMETERS
content:
<b>a</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>(BSD style)</b> Display processes for all users, excluding session leaders and processes not associated with a terminal.<br><br><b>x</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>(BSD style)</b> Include processes without a controlling terminal in the listing. Often used with 'a' as `ax`.<br><br><b>u</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>(BSD style)</b> User-oriented output format. Displays columns like USER, PID, %CPU, %MEM, TTY, STAT, START, TIME, COMMAND.<br><br><b>-e</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>(System V/GNU style)</b> Select every process currently running on the system. Similar to `-A`.<br><br><b>-f</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>(System V/GNU style)</b> Display a 'full' format listing, providing more details such as UID, PPID, C, STIME, and the full command line. Often used with `-e` as `-ef`.<br><br><b>l</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>(System V style)</b> Provide a 'long' format listing with extensive process details including F, S, PRI, NI, ADDR, SZ, and WCHAN.<br><br><b>-o <I>format</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>(GNU/System V style)</b> Specify a user-defined output format. Allows selecting specific columns to display (e.g., `ps -eo pid,cmd,%cpu`).<br><br><b>-p <I>pidlist</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>(GNU/System V style)</b> Select processes by a comma-separated list of specific Process IDs (PIDs).<br><br><b>-U <I>userlist</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>(GNU/System V style)</b> Select processes whose real user ID or username is in the given comma-separated list.<br><br><b>--forest</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>(GNU style)</b> Display processes in a tree structure using ASCII art, illustrating parent-child relationships.<br><br><b>-C <I>command</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>(GNU style)</b> Select processes by the exact command name provided.<br><br><b>T</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>(BSD style)</b> Select all processes associated with the current terminal.<br><br>


title: DESCRIPTION
content:
The <b><I>ps</I></b> (<b>p</b>rocess <b>s</b>tatus) command is a fundamental Linux utility used to display information about currently running processes. Unlike interactive tools such as `top` or `htop`, `ps` provides a static snapshot of processes at the moment the command is executed, making it ideal for quick checks, scripting, and identifying specific processes by PID, user, or command name.<br><br>It can show various details including process ID (PID), parent process ID (PPID), CPU and memory usage, process state, start time, and the command line that launched the process. `ps` supports multiple output formats, including traditional BSD-style, System V-style, and GNU long options, allowing users to customize the displayed columns to their specific needs. Understanding `ps` is crucial for system administration, debugging, and general system monitoring.


title: CAVEATS
content:
The `ps` command provides a <b>snapshot</b> of processes at the exact moment it is run; it is not a real-time, dynamic display. For continuous monitoring, commands like `top` or `htop` are more suitable.<br><br>A significant caveat is the existence of three main option styles: <b>BSD-style</b> (no dash, e.g., `ps aux`), <b>System V-style</b> (single dash, e.g., `ps -ef`), and <b>GNU long options</b> (double dash, e.g., `ps --forest`). These styles often have overlapping functionality but cannot always be reliably mixed, especially BSD and System V options, which can lead to unexpected behavior.


title: PROCESS STATES (STAT COLUMN)
content:
The `STAT` column in `ps` output indicates the current state of a process. Common state codes include:<br><ul><li><b>R</b>: Running or runnable (on run queue)</li><li><b>S</b>: Interruptible sleep (waiting for an event to complete)</li><li><b>D</b>: Uninterruptible sleep (usually I/O)</li><li><b>Z</b>: Zombie process (terminated but parent hasn't reaped it)</li><li><b>T</b>: Stopped (by job control or tracing)</li><li><b><</b>: High-priority (not nice to other users)</li><li><b>N</b>: Low-priority (nice to other users)</li><li><b>s</b>: Is a session leader</li><li><b>l</b>: Is multi-threaded</li><li><b>+</b>: Is in the foreground process group</li></ul>


title: COMMON USAGE EXAMPLES
content:
Below are some frequently used `ps` commands:<br><ul><li>To find a process by name: <b>`ps aux | grep <I>process_name</I>`</b></li><li>To see all processes owned by a specific user: <b>`ps -U <I>username</I> -f`</b></li><li>To display a process tree: <b>`ps aux --forest`</b></li><li>To view processes running on the current terminal: <b>`ps T`</b></li><li>To list all processes with PID, parent PID, and command: <b>`ps -eo pid,ppid,cmd`</b></li></ul>


title: HISTORY
content:
The `ps` command has deep roots, originating from <b>AT&T Unix</b> and subsequently adopted by <b>BSD Unix</b>. This dual heritage led to the coexistence of two distinct, often conflicting, option syntaxes: the System V-style (using a leading dash for options) and the BSD-style (using options without a leading dash). When Linux emerged, it adopted `ps`, and the `procps` package, which provides the modern `ps` implementation, aimed to integrate these styles and introduce GNU-specific extensions (such as long options and ` --forest`). This evolution resulted in its highly versatile, yet sometimes complex and confusing, command-line interface. Despite these stylistic differences, its core function of providing an immediate view of running processes has remained constant throughout its development.


title: SEE ALSO
content:
top(1): Display Linux processes, htop(1): Interactive process viewer, pgrep(1): Look up processes based on name or other attributes, pkill(1): Send signals to processes based on name or other attributes, kill(1): Send a signal to a process, pstree(1): Display a tree of processes, nice(1): Run a command with an adjusted scheduling priority, renice(1): Alter the priority of running processes


title: PARAMETERS
content:
<b>None</b><br>&nbsp;&nbsp;&nbsp;&nbsp;No standard command-line parameters are typically used with <B>ps-nvm</B>. It is primarily invoked without arguments to list all detected <B>Node.js</B> processes. Its behavior is implicitly determined by the active <B>NVM</B> environment and the paths of running <B>Node.js</B> executables.<br><br>


title: DESCRIPTION
content:
<B>ps-nvm</B> is not a standard Linux command. It is a utility, typically provided as a shell function or script within the <I>Node Version Manager</I> (<B>NVM</B>) ecosystem. Its primary purpose is to help users identify and monitor running <B>Node.js</B> processes, specifically indicating which <B>NVM</B>-managed version of <B>Node.js</B> (if any) each process is utilizing.<br><br>In environments where multiple <B>Node.js</B> versions are installed via <B>NVM</B>, it can be challenging to determine which specific version a running application or script is using. <B>ps-nvm</B> addresses this by querying active processes, filtering for <B>Node.js</B> executables, and then attempting to resolve the executable path back to its corresponding <B>NVM</B> installation directory. This provides valuable insights for debugging, version management, and ensuring applications run with the intended <B>Node.js</B> runtime. It helps differentiate between <B>NVM</B>-managed and unmanaged <B>Node.js</B> installations.


title: CAVEATS
content:
<B>NVM Dependency</B>: <B>ps-nvm</B> is not a standalone utility; it requires <B>NVM</B> (Node Version Manager) to be installed and sourced in your shell environment to function correctly. Its availability and exact behavior depend on your <B>NVM</B> installation and version.<br><B>Non-Standard Command</B>: It is not a universally available Linux command and is specific to the <B>NVM</B> ecosystem. Users without <B>NVM</B> installed will not have this command.<br><B>Path Resolution Reliance</B>: Its ability to link processes to specific <B>NVM</B> versions relies on successfully resolving the executable path of the <B>Node.js</B> process. This can sometimes be inaccurate or challenging for processes running in unusual environments, containers, or those started with non-standard paths.<br><B>Performance</B>: On systems with a very large number of running processes, the underlying <B>ps</B> and <B>grep</B> operations performed by <B>ps-nvm</B> might take a noticeable amount of time.


title: HOW IT WORKS
content:
<B>ps-nvm</B> typically operates by first executing a <B>ps</B> command to list all running processes. It then filters this output to find processes whose command line or executable path contains "node". For each identified Node.js process, it attempts to determine its full executable path. This path is then compared against the known installation directories of <B>NVM</B>-managed <B>Node.js</B> versions (e.g., `~/.nvm/versions/node/vX.Y.Z`). By matching the path, it can report the specific <B>NVM</B> version being used by that process. If the path doesn't match an <B>NVM</B> version, it may indicate an "unmanaged" process.


title: PS-NVM-UNMANAGED
content:
A closely related helper (often a separate script or function) is <B>ps-nvm-unmanaged</B>. While <B>ps-nvm</B> lists all Node.js processes and attempts to identify their <B>NVM</B> version, <B>ps-nvm-unmanaged</B> specifically focuses on listing <B>Node.js</B> processes that are <I>not</I> managed by <B>NVM</B> (e.g., system-installed Node.js or those installed via other means). This can be useful for identifying potential conflicts or ensuring all desired Node.js processes are under <B>NVM</B> control.


title: HISTORY
content:
The <B>ps-nvm</B> utility, often implemented as the `nvm_ps_nvm` shell function or a related script, emerged as a practical diagnostic tool within the <B>NVM</B> project. As <B>NVM</B> gained popularity for managing multiple <B>Node.js</B> versions, users faced challenges in identifying which specific Node.js runtime was powering their running applications. <B>ps-nvm</B> was developed to address this visibility gap, providing a quick way to list Node.js processes and their associated <B>NVM</B> versions, or to identify processes that were not managed by <B>NVM</B>. It has evolved with the <B>NVM</B> project, becoming a valuable helper for developers and system administrators working with complex Node.js environments.


title: PARAMETERS
content:
<b><i>input_file.ps</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the PostScript file to be converted. If omitted, <i>ps2ascii</i> reads from standard input (stdin).<br><br><b><i>output_file.txt</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the file where the ASCII text output will be written. If omitted, <i>ps2ascii</i> writes to standard output (stdout).<br><br>


title: DESCRIPTION
content:
<i>ps2ascii</i> is a utility that takes a PostScript file as input and attempts to extract human-readable text from it, outputting plain ASCII text. It is often used for quick previews or to get textual content from PostScript documents without needing a full PostScript viewer or printer. It works by interpreting PostScript drawing commands and trying to identify characters and their positions. The output is typically not a perfect reproduction of the original layout but provides the sequential text content.<br>It is built upon <b>Ghostscript</b> (<i>gs</i>) and leverages its PostScript interpreter capabilities. This command is particularly useful for scripting, indexing PostScript documents, or when you need to process text from PostScript without a graphical interface. It is a simple text extraction tool, not a layout conversion tool, meaning graphical elements and complex formatting are ignored.


title: CAVEATS
content:
Layout, images, and non-textual elements from the original PostScript document are ignored. Complex PostScript files or those with unusual font encodings may result in incomplete or garbled text output. It relies heavily on the underlying <b>Ghostscript</b> installation; its limitations are <b>Ghostscript</b>'s limitations.


title: UNDERLYING TECHNOLOGY
content:
<i>ps2ascii</i> is fundamentally a wrapper script for <b>Ghostscript</b> (<i>gs</i>). It invokes <i>gs</i> with specific options like <i>-sDEVICE=ps2ascii</i>, <i>-dBATCH</i>, and <i>-dNOPAUSE</i> to perform the text extraction. This means its functionality and limitations are directly inherited from the <b>Ghostscript</b> <i>ps2ascii</i> device driver. Any options passed to <i>ps2ascii</i> on the command line, beyond the input/output filenames, are usually passed directly to the underlying <i>gs</i> command, though <i>ps2ascii</i> itself doesn't define standard options for its own behavior.


title: HISTORY
content:
<i>ps2ascii</i> typically exists as a simple shell script wrapper provided with <b>Ghostscript</b> distributions. Its development is not an independent project but rather an abstraction built upon <b>Ghostscript</b>'s internal <i>ps2ascii</i> device driver. It has been a standard utility in Unix-like environments for basic text extraction from PostScript since the early days of PostScript processing.


title: PARAMETERS
content:
<b><I>input.ps</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the input PostScript file that needs to be converted to EPSI format.<br><br><b><I>output.epsi</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The optional path for the output EPSI file. If this argument is omitted, the converted EPSI content is written to standard output (stdout).<br><br><b><b>-d</b><I>feature</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Directly passes a <I>-d</I> option to the underlying Ghostscript command. This controls various features or settings, such as <b>-dSAFER</b> for security or <b>-dEPSCrop</b> to automatically crop the output to the bounding box.<br><br><b><b>-s</b><I>param</I>=<I>value</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Directly passes a <I>-s</I> option to the underlying Ghostscript command. This is used for setting string parameters, for example, <b>-sPAPERSIZE=a4</b> to define the paper size or <b>-sDEVICE=epswrite</b> to specify the output device.<br><br><b><b>-r</b><I>resolution</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the resolution (in dots per inch, DPI) for the embedded bitmap preview. Common values include 72, 150, or 300 DPI, affecting the preview's clarity.<br><br><b><b>-g</b><I>width</I>x<I>height</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the dimensions (in pixels) for the embedded bitmap preview. For instance, <b>-g512x512</b> would create a 512x512 pixel preview.<br><br>


title: DESCRIPTION
content:
<b>ps2epsi</b> is a utility designed to transform a standard PostScript file into an Encapsulated PostScript (EPS) file, specifically in the EPSI format. The distinguishing feature of EPSI is the inclusion of a low-resolution bitmap preview (typically TIFF or PICT) directly within the PostScript file. This embedded preview enables applications, especially older desktop publishing software, to display a visual representation of the graphic without needing to fully render the complex PostScript code. This significantly improves performance and workflow when placing graphics. Internally, <b>ps2epsi</b> commonly acts as a wrapper script, leveraging the powerful Ghostscript (<b>gs</b>) interpreter to perform the conversion and generate the preview.


title: CAVEATS
content:
<b>ps2epsi</b> is frequently a simple shell wrapper around the <b>gs</b> (Ghostscript) command. Consequently, its exact behavior and available features can vary significantly depending on the specific Ghostscript version and how the script is implemented on a given system.<br><br>The embedded bitmap preview is typically low-resolution and primarily intended for screen display or layout purposes, not for high-quality printing. Complex or interactive PostScript constructs might not be perfectly encapsulated or result in an accurate preview. Issues with bounding boxes can arise if the input PostScript lacks a proper <b>%%BoundingBox</b> comment or if graphics extend beyond the defined page size, potentially leading to clipping or misrepresentation of content.<br><br>While still useful for compatibility, the EPSI format is less critical in modern workflows, as many contemporary applications prefer 'pure' EPS or PDF/X formats, which offer more robust preview solutions (e.g., embedded JPEG) or direct rendering capabilities.


title: PREVIEW FORMAT
content:
The embedded bitmap preview generated by <b>ps2epsi</b> typically adheres to either the TIFF or PICT image formats. TIFF is more commonly used in Unix-like environments and Windows, whereas PICT was historically prevalent on Apple Macintosh systems. The specific format used can sometimes be influenced by the Ghostscript configuration or the version of the <b>ps2epsi</b> script.


title: BOUNDING BOX (<B>%%BOUNDINGBOX</B>)
content:
For <b>ps2epsi</b> to function optimally and produce accurate results, it is highly recommended that the input PostScript file includes a valid <b>%%BoundingBox</b> comment. This comment defines the precise extent of the graphics within the PostScript file. If this comment is missing, incorrect, or if the graphic extends outside of it, <b>ps2epsi</b> might default to using the page size as the bounding box, which could lead to undesired clipping of the artwork or an inaccurate representation.


title: HISTORY
content:
<b>ps2epsi</b> has been a long-standing utility, traditionally distributed as part of the Ghostscript package. Its origins date back to the early days of desktop publishing and graphic arts, where there was a significant need for a lightweight method to display PostScript content without requiring a full rendering engine. The EPSI format, with its embedded TIFF or PICT previews, gained prominence as an efficient solution for placing graphics in page layout applications. Although its direct usage has somewhat declined with the advent of PDF and more sophisticated EPS parsing capabilities in modern software, it remains a valuable tool for maintaining compatibility with legacy systems and workflows.


title: PARAMETERS
content:
<b><i>input.ps</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the input PostScript file to be converted.<br><br><b><i>output.pdf</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The desired path for the output PDF file. If omitted, a default filename based on the input is often used, or output goes to standard output depending on environment.<br><br><b><b>-dCompatibilityLevel=<i>X.Y</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the PDF compatibility level for the output file (e.g., <b>-dCompatibilityLevel=1.4</b> for PDF 1.4). This impacts which PDF features can be used.<br><br><b><b>-dPDFSETTINGS=<i>/value</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls the output quality and size. Common values include <b>/screen</b> (low quality, small size), <b>/ebook</b> (medium quality), <b>/printer</b> (high quality), <b>/prepress</b> (highest quality, largest size), and <b>/default</b> (general purpose).<br><br><b><b>-sPAPERSIZE=<i>name</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output paper size (e.g., <b>a4</b>, <b>letter</b>, <b>legal</b>). The PostScript file's media size might be overridden.<br><br><b><b>-r<i>DPI</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the resolution for rasterization (downsampling of images) in dots per inch (e.g., <b>-r300</b> for 300 DPI). Lower values reduce file size but also image quality.<br><br><b><b>-dQUIET</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses informational messages during conversion, showing only errors or warnings.<br><br><b><b>-dEmbedAllFonts=<i>true/false</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls whether all fonts used in the PostScript file are embedded in the PDF. Setting to <b>true</b> ensures portability but increases file size.<br><br><b><b>-dSubsetFonts=<i>true/false</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls whether embedded fonts are subsetted to include only characters used. Setting to <b>true</b> helps reduce file size without losing font appearance.<br><br>


title: DESCRIPTION
content:
<b>ps2pdf</b> is a powerful utility designed to convert files from the PostScript (PS) format to the Portable Document Format (PDF).<br>It acts as a convenient wrapper script around the more general purpose <b>Ghostscript (gs)</b> interpreter, specifically configuring it to output PDF.<br>This command is indispensable for document processing workflows, allowing users to transform high-quality PostScript documents, often generated by applications like LaTeX or DTP software, into widely viewable and portable PDF files.<br>It handles various aspects of the conversion, including font embedding, image compression, and optimization, depending on the options provided.<br>By default, <b>ps2pdf</b> aims to produce a high-quality PDF that is reasonably sized, but it offers extensive customization through options passed directly to Ghostscript to fine-tune the output for specific uses, such as screen viewing, printing, or prepress production.


title: CAVEATS
content:
Since <b>ps2pdf</b> is a wrapper for Ghostscript, its capabilities and limitations are inherited from Ghostscript itself.<br>Complex or malformed PostScript files may not convert perfectly, or may produce unexpected results.<br>Resource usage (memory and CPU) can be significant for very large or intricate PostScript documents.<br>While <b>ps2pdf</b> often invokes Ghostscript with security-enhancing options like <b>-dSAFER</b>, exercising caution with untrusted PostScript sources is always advisable.


title: <B>PDFSETTINGS OPTIONS</B>
content:
The <b>-dPDFSETTINGS=/value</b> option is critical for controlling the balance between file size and quality:<br><b>/screen</b>: Low quality, small size. Suitable for on-screen viewing.<br><b>/ebook</b>: Medium quality, medium size. Suitable for e-readers or web distribution.<br><b>/printer</b>: High quality, larger size. Suitable for desktop printers.<br><b>/prepress</b>: Highest quality, largest size. Suitable for high-end print production with no downsampling or compression.<br><b>/default</b>: General purpose setting, balances quality and size.


title: <B>PDF COMPATIBILITY LEVELS (PS2PDF1X)</B>
content:
Ghostscript and <b>ps2pdf</b> can generate PDFs conforming to different PDF versions. Special wrapper scripts often exist:<br><b>ps2pdf12</b> (or <b>ps2pdf1.2</b>): Generates PDF 1.2 compatible files.<br><b>ps2pdf13</b> (or <b>ps2pdf1.3</b>): Generates PDF 1.3 compatible files.<br><b>ps2pdf14</b> (or <b>ps2pdf1.4</b>): Generates PDF 1.4 compatible files.<br>These scripts are essentially shortcuts for invoking <b>ps2pdf</b> with the appropriate <b>-dCompatibilityLevel</b> option set.


title: HISTORY
content:
<b>ps2pdf</b> emerged as a part of the Ghostscript distribution, a project initiated by L. Peter Deutsch and later maintained by Artifex Software.<br>Ghostscript itself began development in the late 1980s, providing an open-source interpreter for PostScript and PDF.<br>As PDF gained prominence, <b>ps2pdf</b> was created as a convenient command-line tool to simplify the common task of converting PostScript to PDF, abstracting away the complex Ghostscript parameters.<br>Its evolution has closely mirrored the development of new PDF versions, leading to specialized scripts like <b>ps2pdf12</b>, <b>ps2pdf13</b>, and <b>ps2pdf14</b> (or their <b>1.X</b> counterparts) that target specific PDF compatibility levels.


title: SYNOPSIS
content:
<b>ps2ps</b> [<i>options</i>] <i>input.ps</i> [<i>output.ps</i>]<br><b>ps2ps</b> [<i>options</i>] <i>-</i> [<i>output.ps</i>]


title: PARAMETERS
content:
<b><b>-dCompatibilityLevel=<I>N</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Converts the PostScript file to Language Level <I>N</I> (e.g., 1, 2, or 3) for compatibility.<br><br><b><b>-dEPSCrop</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Crops the output PostScript to the bounding box specified by `%%BoundingBox` comments in the input. Useful for EPS files.<br><br><b><b>-r<I>X</I></b><br><b>-r<I>X</I>x<I>Y</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the resolution for rendering bitmap images and rasterizing vector graphics within the PostScript output.<br><br><b><b>-sOutputFile=<I>file</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the name of the output PostScript file. If omitted, output might go to standard output or a default name.<br><br><b><b>-dSAFER</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs Ghostscript in a safer mode, disabling file system access and shell escapes, recommended for untrusted input.<br><br><b><b>-dNOPAUSE</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables prompts for user interaction (e.g., for page advancement) during processing.<br><br><b><b>-dBATCH</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exits after processing the input file, rather than entering an interactive Ghostscript prompt.<br><br>


title: DESCRIPTION
content:
<I>ps2ps</I> is a utility designed to convert or optimize PostScript language files. It acts as a convenient front-end to the Ghostscript interpreter, using specific options to read an input PostScript file and write a new PostScript file as output. Its primary uses include converting PostScript files between different language levels (e.g., PostScript Level 2 to Level 1), simplifying complex PostScript, or "distilling" PostScript for specific purposes like embedding in other documents or preparing for older printers. It effectively re-interprets and re-generates the PostScript code, often leading to smaller file sizes or improved compatibility. <I>ps2ps</I> is particularly useful for preparing PostScript files that might have issues with certain viewers or printers, or for reducing the complexity of the PostScript structure.


title: CAVEATS
content:
<I>ps2ps</I> is a wrapper script around the Ghostscript interpreter, so its behavior depends on the installed Ghostscript version and configuration.<br>It might not perfectly preserve all PostScript features, especially when down-converting language levels or simplifying complex constructs.<br>The re-interpretation process can sometimes slightly alter the visual appearance, particularly with unusual fonts or advanced transparency features.


title: COMMON USE CASES
content:
<I>ps2ps</I> is frequently used to convert PostScript files to an older language level (e.g., PostScript Level 2 to Level 1) for compatibility with legacy printers or viewers. It's also employed to "distill" PostScript, which involves cleaning up and optimizing the file, often reducing its size or fixing minor structural issues, making it suitable for embedding in other documents or for further processing within a workflow.


title: HISTORY
content:
<I>ps2ps</I> is a component of the Ghostscript suite of utilities. Ghostscript, initially developed by Aladdin Enterprises in the late 1980s, has a long history as a PostScript and PDF interpreter. <I>ps2ps</I> emerged as a convenient script to leverage Ghostscript's capabilities specifically for PostScript-to-PostScript conversions, such as language level conversion and optimization. It has since become a standard utility included with Ghostscript distributions on Unix-like operating systems, with its development mirroring the continuous evolution of Ghostscript itself.


title: SYNOPSIS
content:
psalm [options] [files...]<br>Commonly invoked as <b>vendor/bin/psalm [options] [files...]</b> after Composer installation.<br>Key invocation modes include running for a full analysis, <b>--diff</b> for changed files, <b>--lint</b> for quick checks, <b>--baseline</b> for managing existing errors, and <b>--alter</b> for automatic code modifications.


title: PARAMETERS
content:
<b>--config=<file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specify a custom Psalm configuration file.</i><br><br><b>--set-config=<key>=<value></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Override specific configuration values directly.</i><br><br><b>--diff</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Analyze only files that have changed since the last Git commit.</i><br><br><b>--lint</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Run a quick syntax check and show errors on the console.</i><br><br><b>--output-format=<format></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Set the output format (e.g., `text`, `json`, `xml`, `github`).</i><br><br><b>--report=<file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Write the analysis results to a specified file.</i><br><br><b>--issues=<list></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Filter issues to check or ignore (e.g., `MissingReturnType,UndefinedClass`).</i><br><br><b>--show-info</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Display informational messages during analysis.</i><br><br><b>--baseline[=<file>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Create or update a baseline file to ignore existing errors.</i><br><br><b>--alter</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Run code alteration plugins to fix identified issues automatically.</i><br><br><b>--threads=<num></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specify the number of parallel threads for analysis.</i><br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Display detailed help information.</i><br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Show the Psalm version.</i><br><br>


title: DESCRIPTION
content:
PSALM is a robust static analysis tool designed for PHP. It meticulously examines PHP source code without executing it, identifying potential bugs, type errors, undefined variables, and other inconsistencies. By parsing the code and building a detailed understanding of its structure and types, PSALM helps developers catch issues early in the development lifecycle, significantly improving code quality, reliability, and maintainability, especially in large and complex projects. It supports modern PHP language features and can be integrated into continuous integration/delivery (CI/CD) pipelines to enforce coding standards and prevent regressions.


title: CAVEATS
content:
Psalm is not a built-in or standard Linux command; it is primarily a PHP application that runs within a Linux environment. It requires PHP (version 7.1 or higher) and Composer for installation and execution. Effective use often demands careful configuration via its `psalm.xml` file. While powerful, it may occasionally produce false positives or miss some edge cases.


title: CONFIGURATION FILE (PSALM.XML)
content:
Psalm's behavior is primarily controlled by its configuration file (typically `psalm.xml` or `psalm.xml.dist`), which defines the source directories, allowed issues, plugins, and other analysis parameters.


title: BASELINES
content:
Baselines (`psalm-baseline.xml`) allow developers to commit Psalm with existing errors, then only report new errors, facilitating gradual adoption and refactoring.


title: PLUGINS
content:
Psalm supports a rich plugin ecosystem, enabling extensions to its analysis capabilities, integration with other tools, and support for specific frameworks or libraries.


title: HISTORY
content:
Psalm originated from Vimeo engineering as an internal tool to improve the reliability and maintainability of their large PHP codebase. It was subsequently open-sourced and has since become a widely adopted and actively developed project within the PHP community, continually evolving to support new PHP features and provide more robust analysis capabilities. Its development focuses on deep type inference and control flow analysis.


title: PARAMETERS
content:
<b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message and exits.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the version information of the command.<br><br><b><b>-o</b> <<i>filename</i>>, <b>--output-file</b>=<<i>filename</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the name for the output <i>FITS</i> file.<br><br><b><b>-n</b> <<i>name</i>>, <b>--ext-name</b>=<<i>name</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the name for the <i>FITS</i> extension containing the PSF table (default is <i>PSF_DATA</i>).<br><br><b><b>-c</b>, <b>--compress-table</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Compresses the PSF table in the output file using <i>FITS</i> table compression.<br><br><b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Overwrites the output file if it already exists without prompting.<br><br><b><b>-p</b> <<i>string</i>>, <b>--prefix</b>=<<i>string</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines a prefix for <i>FITS</i> header keywords related to PSF data (default is <i>PSF</i>).<br><br><b><b>-t</b> <<i>name</i>>, <b>--table-name</b>=<<i>name</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the internal name for the PSF table within the <i>FITS</i> extension (default is <i>PSF_TABLE</i>).<br><br><b><b>--add-to-ext</b> <<i>number|name</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds the PSF table to a specific existing extension by number or name instead of creating a new primary one.<br><br><b><b>--comment</b> <<i>string</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a comment to the output <i>FITS</i> file header.<br><br><b><b>--history</b> <<i>string</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a history record to the output <i>FITS</i> file header.<br><br>


title: DESCRIPTION
content:
<i>psfaddtable</i> is a command-line utility from the <i>psfex</i> package, designed to integrate Point Spread Function (PSF) model data directly into astronomical <i>FITS</i> (Flexible Image Transport System) files. It takes an input <i>FITS</i> image and a separate <i>FITS</i> table containing PSF model information (typically generated by <i>psfex</i>) and appends this table to the image's header or adds it as a new extension. This is crucial for applications requiring precise photometry and astrometry, as it allows subsequent analysis tools to access the PSF model associated with the image directly.<br><br>By embedding the PSF data, <i>psfaddtable</i> streamlines data management and ensures that the PSF model used for analysis is consistent with the image it describes, facilitating tasks like source extraction and deconvolution in astronomy.


title: CAVEATS
content:
This command is part of the <i>psfex</i> software package and is not a standard utility found in most Linux distributions by default. It requires <i>psfex</i> to be installed.<br><br>It operates exclusively on <i>FITS</i> (Flexible Image Transport System) files, which are the standard data format in astronomy.<br><br>The PSF table input is expected to be in the specific format generated by the <i>psfex</i> program; using tables from other sources might lead to errors or incorrect interpretation.<br><br>Adding large PSF tables to images can significantly increase file size.


title: USAGE EXAMPLE
content:
To add a PSF table <i>my_psf.fits</i> generated by <i>psfex</i> to an image <i>raw_image.fits</i> and save the result as <i>processed_image.fits</i> with a specific extension name:<br><code>psfaddtable -o processed_image.fits -n PSF_MODEL_DATA raw_image.fits my_psf.fits</code>


title: INTEGRATION
content:
<i>psfaddtable</i> is typically used as a post-processing step after running <i>psfex</i>. It enhances the self-describing nature of <i>FITS</i> files, making them more portable and easier to use in subsequent analyses, especially with tools that expect PSF information to be co-located with the image data.


title: HISTORY
content:
The <i>psfaddtable</i> utility was developed by <i>Emmanuel Bertin</i> as part of the <i>psfex</i> package. <i>psfex</i> itself emerged from the need for robust and accurate Point Spread Function modeling in astronomical image analysis, particularly for deep survey data. <i>psfaddtable</i> was created to streamline the workflow by allowing the PSF model, crucial for precise photometry and astrometry, to be directly embedded within the image <i>FITS</i> file. This integration simplifies data handling and ensures consistency between images and their associated PSF models in large-scale astronomical pipelines.


title: PARAMETERS
content:
<b>-t <name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the <I>name</I> of the table to extract. If omitted, the first table found or a default table might be used.<br><br><b>-c <cols></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a comma-separated list of <I>column names</I> to extract from the selected table. Example: <B>-c 'FREQ,FLUX'</B>.<br><br><b>-r <rows></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a <I>range of rows</I> to extract. Can be a single row number or a range like <B>'min:max'</B> (e.g., <B>'0:99'</B> for the first 100 rows).<br><br><b>-o <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the extracted data to the specified <I>output file</I> instead of standard output.<br><br><b>-F <format></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the <I>output format</I> for the extracted data, such as <B>'ascii'</B>, <B>'csv'</B>, or <B>'fits'</B>.<br><br><b>-p</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the extracted table content to standard output (this is the default behavior if <B>-o</B> is not used).<br><br><b>-l</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all available table names and their respective column names within the specified PSRFITS file, without extracting data.<br><br><b>-h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message and exits.<br><br>


title: DESCRIPTION
content:
<I>psfgettable</I> is a specialized command-line utility within the <B>PSRCHIVE</B> software suite, designed for handling <B>Pulsar FITS (PSRFITS)</B> data files. Its primary function is to extract tabular data contained within these complex astronomical data formats.<br><br>PSRFITS files are commonly used in radio astronomy to store observational data from pulsars, often including multiple data tables describing various aspects of the observation, such as calibration information, receiver parameters, or processed data products. The command allows users to precisely specify which tables, columns, and rows to extract, providing flexibility in data manipulation. It can output the extracted data to standard output or a specified file, and supports various output formats, making it valuable for scripting and integrating with other data analysis tools. This command is crucial for researchers needing to access specific metadata or auxiliary data stored alongside the main observational arrays in PSRFITS files without resorting to programmatic interfaces.


title: CAVEATS
content:
Requires the <B>PSRCHIVE</B> software suite to be installed. <br>Only operates on <B>Pulsar FITS (PSRFITS)</B> files, which adhere to a specific astronomical data standard. <br>Its utility is limited to the domain of radio astronomy data processing and is not a general-purpose table extraction tool.


title: TYPICAL USAGE
content:
A common use case involves first using <B>-l</B> to inspect the available tables and columns in a PSRFITS file, then using <B>-t</B> and <B>-c</B> to extract specific information. For instance, one might use it to get calibration parameters or receiver temperature logs from a specific observation.


title: SCRIPTING INTEGRATION
content:
Due to its command-line nature and support for various output formats like CSV, <I>psfgettable</I> is frequently incorporated into shell scripts or Python scripts for automated data processing pipelines in radio astronomy. This allows for programmatic access and manipulation of complex PSRFITS metadata, facilitating reproducible research workflows.


title: HISTORY
content:
<I>psfgettable</I> is an integral part of the <B>PSRCHIVE</B> software package, an open-source library and suite of programs for the analysis of pulsar astronomical data. <br>Developed primarily by research groups in radio astronomy, PSRCHIVE has been under continuous development since the late 1990s/early 2000s, providing essential tools for handling, processing, and analyzing pulsar observations. <br>The command's evolution has been driven by the increasing complexity and size of pulsar data, necessitating efficient methods for accessing specific metadata and auxiliary information stored in PSRFITS files.


title: PARAMETERS
content:
<b>-o output-file</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the name for the output file. If this option is omitted, the processed font data will be written to standard output.<br><br><b>input-file</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the PostScript font file (typically a Type 1 font) from which the <I>PSFType1</I> table is to be stripped. This is a mandatory argument.<br><br>


title: DESCRIPTION
content:
<b>psfstriptable</b> is a specialized utility designed to manipulate PostScript font files, specifically Type 1 fonts. Its primary function is to remove the <I>PSFType1</I> table from an input font file. This table often contains a "Type1" font structure and is typically generated and embedded by tools like <I>t1embed</I> when preparing fonts for inclusion within PostScript documents. <br><br>Stripping this table can be necessary in certain scenarios, such as when an already embedded font is being re-processed, or when dealing with redundancy and potential conflicts if the font data is duplicated or causes issues with specific PostScript interpreters or document workflows. By removing this table, <b>psfstriptable</b> helps in streamlining font embedding processes and ensuring compatibility. The command takes an input font file and, optionally, an output file name; if no output file is specified, the processed font data is written to standard output.


title: CAVEATS
content:
This utility is highly specialized for manipulating Type 1 PostScript fonts and their internal tables. Its effectiveness and behavior might be unpredictable with non-standard font formats, corrupted font files, or if the <I>PSFType1</I> table is not present as expected. It is primarily used within specific font embedding workflows, often related to TeX systems.


title: PURPOSE OF PSFTYPE1 TABLE
content:
The <I>PSFType1</I> table, often written by <I>t1embed</I>, contains a structured representation of the Type 1 font. It is typically used by PostScript interpreters or PDF viewers to correctly render the font when it's embedded within a document. <b>psfstriptable</b> removes this specific table, which can be useful when the font is already part of a larger structure that provides the necessary font information or when the table's presence causes issues.


title: HISTORY
content:
<b>psfstriptable</b> is part of the <I>psutils</I> (PostScript utilities) or <I>texlive-bin</I> package, specifically developed to aid in the complex process of PostScript font embedding and manipulation within the TeX ecosystem. Its development is tied to the needs of tools like <I>pdftex</I> and <I>t1embed</I> to ensure correct and efficient handling of Type 1 fonts, particularly when embedding them into PostScript or PDF documents. It emerged as a utility to address specific technical challenges related to font table redundancy or conflicts during the pre-press and document processing stages.


title: SYNOPSIS
content:
<b>psfxtable</b> [-qv] [-t <I>type</I>] [-f <I>file</I>] [-o <I>offset</I>] [-l <I>length</I>] [-i] [-d <I>key</I>] [-a <I>key=value</I>] [<I>key ...</I>]


title: PARAMETERS
content:
<b><b>-q</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Activate query mode (this is the default behavior).</I><br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Enable verbose logging, showing more details about operations.</I><br><br><b><b>-t <I>type</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specify the internal table type (e.g., <code>lookup</code>, <code>data</code>).</I><br><br><b><b>-f <I>file</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specify the full path to the <code>pfx</code> table file.</I><br><br><b><b>-o <I>offset</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specify the record offset within the table, typically used with <code>-l</code>.</I><br><br><b><b>-l <I>length</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specify the record length for fixed-size entries, used with <code>-o</code>.</I><br><br><b><b>-i</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Initialize or create an empty <code>pfx</code> table at the specified file path.</I><br><br><b><b>-d <I>key</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Delete the specified key and its associated value from the table.</I><br><br><b><b>-a <I>key=value</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Add or update an entry in the table with the given key and value pair.</I><br><br><b><b>[<I>key ...</I>]</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>One or more keys to query in the table when in query mode (default).</I><br><br>


title: DESCRIPTION
content:
<code>psfxtable</code> is a Postfix command-line utility designed for managing and querying Postfix's specialized <I>persistent fixed-size</I> (<code>pfx</code>) tables.<br><br>Unlike the more common <code>hash</code> or <code>btree</code> tables managed by <code>postmap</code>, <code>pfx</code> tables are optimized for extremely fast lookups of fixed-size records and are primarily used internally by Postfix for specific data structures. These can include, for instance, records for address verification statuses, internal content filtering rules, or very large access control lists where performance is critical.<br><br>The command allows administrators to inspect the contents of these tables, add or delete individual entries, or even initialize/recreate the table structure. Its usage typically extends to advanced debugging or specific system maintenance tasks rather than routine mail server configuration.


title: CAVEATS
content:
<ul><li><I><code>psfxtable</code> operates on Postfix's internal <code>pfx</code> tables, which are not designed for direct routine manipulation by administrators in the same way as <code>postmap</code> tables.</I></li><li><I>Direct manipulation of these tables can impact Postfix's internal state and should be done with extreme caution, preferably only when troubleshooting or performing advanced system maintenance.</I></li><li><I>Understanding and correctly using parameters like <code>-o</code> (offset) and <code>-l</code> (length) requires detailed knowledge of the specific <code>pfx</code> table's internal structure.</I></li></ul>


title: <B>INTERNAL TABLE TYPE</B>
content:
<I><code>psfxtable</code> specifically manages Postfix's internal <code>pfx</code> (persistent fixed-size) tables. These tables are optimized for high-performance lookups of fixed-length records and are fundamentally different from the general-purpose lookup tables handled by <code>postmap</code> (e.g., hash, btree). They are typically used for Postfix's internal state management and specialized data structures.</I>


title: <B>ADVANCED USAGE</B>
content:
<I>Direct manipulation of <code>pfx</code> tables using <code>psfxtable</code> is generally intended for Postfix developers or highly advanced administrators. It is not a command for routine Postfix administration and is typically used for debugging, specific low-level maintenance, or in scenarios where automated Postfix processes are not sufficient.</I>


title: HISTORY
content:
<I><code>psfxtable</code> is an integral component of the Postfix mail system, introduced to support specific internal data structures that benefit from extremely fast, fixed-size lookups. Its development is intertwined with the overall evolution of Postfix, particularly in optimizing performance for very large datasets and efficient management of internal system state. It complements the more general-purpose <code>postmap</code> utility by addressing specialized table requirements.</I>


title: SYNOPSIS
content:
<b>ps</b> <<i>><u>ps_options</u><//i>> <b>| grep</b> <<i>><u>grep_options</u><//i>> <<i>><u>search_pattern</u><//i>><br><br><i><u>Examples:</u></i><br><b>ps -ef | grep httpd</b><br><b>ps aux | grep -i nginx | grep -v grep</b>


title: PARAMETERS
content:
<b><i><u>ps options:</u></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Options passed to the <b>ps</b> command to control the format and content of the process list.<br><br><b><b>-e</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Select all processes.<br><br><b><b>-f</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display full-format listing (UID, PID, PPID, C, STIME, TTY, TIME, CMD).<br><br><b><b>a</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show processes for all users, including those not associated with a terminal.<br><br><b><b>u</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display user-oriented format (USER, PID, %CPU, %MEM, VSZ, RSS, TTY, STAT, START, TIME, COMMAND).<br><br><b><b>x</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show processes without a controlling TTY.<br><br><b><i><u>grep options:</u></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Options passed to the <b>grep</b> command to refine the search for the pattern.<br><br><b><b>-i</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ignore case distinctions in both the pattern and the input data.<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Invert the sense of matching, to select non-matching lines.<br><br><b><b>-w</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Select only those lines containing matches that form whole words.<br><br><b><b>-E</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Interpret pattern as an extended regular expression.<br><br><b><b>-P</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Interpret pattern as a Perl regular expression (highly expressive, non-standard).<br><br><b><i><u>search_pattern:</u></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The regular expression or literal string to search for within the process list.<br><br>


title: DESCRIPTION
content:
The term <b>psgrep</b> refers not to a standalone command, but to a ubiquitous Unix/Linux idiom combining the output of the <b>ps</b> command with the filtering capabilities of <b>grep</b>.<br><br>Its primary purpose is to quickly locate and display information about specific processes running on a system, typically by searching for a part of their name, a user, or other attributes available in the <b>ps</b> output. This method is incredibly versatile, allowing users to find processes related to a particular application, identify runaway processes, or confirm if a service is actively running.<br><br>The most common forms involve piping the full process list (e.g., from `ps -ef` or `ps aux`) into <b>grep</b>, followed by a search pattern. A common refinement is to use `grep -v grep` to exclude the <b>grep</b> command itself from the search results, preventing it from appearing as a matched process.


title: CAVEATS
content:
<b>psgrep</b> is an idiom, not a single command, meaning its behavior and options are derived from the underlying <b>ps</b> and <b>grep</b> commands. It's often less efficient than dedicated tools like <b>pgrep</b> for simple process ID lookups.<br><br>A common pitfall is matching the <b>grep</b> command itself, which can be avoided by adding `| grep -v grep` to the pipeline. Output format is entirely dependent on the <b>ps</b> options used.


title: WHY `GREP -V GREP`?
content:
When you execute `ps -ef | grep myprocess`, the <b>grep</b> command itself is a process running that contains the string 'myprocess' (or whatever you searched for). Therefore, the output would often include the <b>grep</b> command itself. Appending `| grep -v grep` filters out any line containing the string 'grep', effectively hiding the <b>grep</b> command from your results and showing only the actual target processes.<br><br>For example, `ps -ef | grep ssh` might show:<br><i>user    1234  1  0 10:00 ?  00:00:01 /usr/sbin/sshd -D<br>user    5678 1234 0 10:05 pts/0 00:00:00 grep ssh</i><br><br>Using `ps -ef | grep ssh | grep -v grep` would only show:<br><i>user    1234  1  0 10:00 ?  00:00:01 /usr/sbin/sshd -D</i>


title: ALTERNATIVES TO PSGREP
content:
While <b>psgrep</b> is powerful, for simply finding process IDs based on name, <b>pgrep</b> is often a more direct and efficient tool. For example, `pgrep nginx` will directly return the PIDs of all processes named 'nginx'. Similarly, <b>pkill</b> can be used to send signals to processes by name. These dedicated commands are generally preferred for scripting due to their precision and less verbose output.


title: HISTORY
content:
The <b>psgrep</b> idiom emerged organically from the necessity to filter verbose process listings. As Unix-like systems became more prevalent, the combination of <b>ps</b> for process status and <b>grep</b> for pattern matching became a fundamental skill for system administrators and developers. While no specific development history exists for 'psgrep' itself, its enduring popularity highlights the power of Unix's philosophy of chaining small, specialized tools. The later introduction of commands like <b>pgrep</b> and <b>pkill</b> offered more streamlined and dedicated solutions for process searching and signaling, but <b>psgrep</b> remains a widely used, flexible, and powerful method.


title: PARAMETERS
content:
<b><b>-o</b> <i>&lt;outfile&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output file name for the generated PGM data. If not provided, output goes to standard output.<br><br><b><b>-s</b> <i>&lt;subtune&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects a specific subtune within the SID file to convert. SID files can contain multiple distinct pieces of music or variations. The default is 1 (the first subtune).<br><br><b><b>-r</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs raw PGM data without the standard PGM file header. This is useful if the PGM stream is to be embedded or processed by a tool that expects only the raw command sequence.<br><br>


title: DESCRIPTION
content:
<i>psidtopgm</i> is a command-line utility designed to convert Commodore 64 SID music files (PSID format) into a Programmable Music (.PGM) format. This specialized .PGM format captures the exact register writes to the SID chip over time, essentially providing a detailed log of the music's playback instructions. It serves as an intermediate step in the SID emulation pipeline, allowing other programs to interpret and play the music without directly parsing the original SID file. It is typically distributed as part of the <i>libsidplay</i> or <i>sidplayfp</i> suite, which are renowned for their highly accurate emulation of the C64's iconic sound chip.


title: CAVEATS
content:
<i>psidtopgm</i> is a highly specialized utility within the C64 SID emulation ecosystem. The output <b>.PGM</b> file is not an audio file itself, but a sequence of commands for a SID chip emulator. It requires another program (like a SID player or emulator core) to interpret these commands and render them into audible sound.<br><br>It primarily works with PSID (Portable SID) format files, which is the most common format for C64 music outside of native C64 environments.


title: THE PGM FILE FORMAT
content:
In the context of <i>psidtopgm</i>, PGM (Programmable Music) refers to a proprietary intermediate format used by <i>libsidplay</i> and related projects. A PGM file consists of a stream of instructions representing direct register writes to the virtual SID chip, along with timing information. This format allows for extremely precise re-creation of the original C64 music playback without needing to constantly re-parse the more complex SID file structure during emulation.


title: HISTORY
content:
<i>psidtopgm</i> emerged as a utility within the broader <i>libsidplay</i> project, initiated by Simon White, which aimed to create a highly accurate and portable software emulator for the Commodore 64's MOS Technology 6581/8580 SID (Sound Interface Device) chip. It later became part of forks like <i>libsidplayfp</i> (Fast and Portable), continuing its role in processing SID files for accurate playback and analysis.


title: SYNOPSIS
content:
The PSK cracking functionality is executed using the <I>aircrack-ng</I> command:<br><br><b><I>aircrack-ng</I></b> [<i>options</i>] <I>capture_file(s)</I>


title: PARAMETERS
content:
<b>-w <wordlist></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to a dictionary file (wordlist) containing potential passwords. Each line in the file is treated as a candidate PSK.<br><br><b>-b <bssid></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filters the cracking attempt to a specific network by its BSSID (MAC address of the access point).<br><br><b>-e <essid></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filters the cracking attempt to a specific network by its ESSID (network name).<br><br><b>-p <number></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the number of CPU cores or threads to use for cracking, accelerating the process on multi-core systems.<br><br><b>-K</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Activates the WPA-PSK key calculation. Usually implied when using -w with WPA captures.<br><br><b>-D</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables debug output, useful for troubleshooting.<br><br>


title: DESCRIPTION
content:
<i>psk-crack</i> refers to the process of recovering a WPA/WPA2 Pre-Shared Key (PSK) using a dictionary or brute-force attack. While there isn't a standalone Linux command named <i>psk-crack</i> that takes a capture file and wordlist directly as its primary function, this capability is prominently provided by the <I>aircrack-ng</I> suite. <I>aircrack-ng</I> is a powerful set of tools designed for auditing wireless networks. To 'psk-crack' using <I>aircrack-ng</I>, you typically need a captured 4-way WPA/WPA2 handshake (obtained using tools like <I>airodump-ng</I>) and a wordlist containing potential passwords. The command attempts to re-create the handshake with each word in the list until a match is found, revealing the PSK.


title: CAVEATS
content:
<b>Legality:</b> Using this functionality to crack networks you do not own or have explicit permission to test is illegal and unethical. It is intended for legitimate security auditing purposes.<br><b>Handshake Requirement:</b> A valid 4-way WPA/WPA2 handshake must be present in the capture file for the cracking process to succeed.<br><b>Wordlist Quality:</b> The success of a dictionary attack heavily depends on the quality and comprehensiveness of the provided wordlist. A poor wordlist will likely fail to find the password.<br><b>Time Consumption:</b> Cracking can be a very time-consuming process, especially with long wordlists or complex passwords, potentially taking hours, days, or even longer.<br><b>Computational Resources:</b> Cracking is CPU-intensive. Utilizing multiple CPU cores (with -p) can significantly speed up the process.


title: TYPICAL USAGE EXAMPLE
content:
To attempt cracking a WPA/WPA2 PSK from a capture file named <I>handshake.cap</I> using a wordlist named <I>rockyou.txt</I>, you would execute:<br><br><b><I>aircrack-ng</I></b> -w /path/to/rockyou.txt /path/to/handshake.cap<br><br>If the PSK is found within the wordlist, <I>aircrack-ng</I> will display it.


title: REQUIREMENTS FOR CRACKING
content:
Before attempting to crack a PSK, ensure you have:<br>1.  A wireless adapter capable of monitor mode (e.g., supported by <I>airmon-ng</I>).<br>2.  A captured WPA/WPA2 4-way handshake. This typically involves capturing traffic while a legitimate client connects or re-connects to the target AP.<br>3.  A comprehensive wordlist.


title: HISTORY
content:
The concept of cracking WPA/WPA2 PSK emerged as vulnerabilities were discovered in the WPA protocol, particularly regarding dictionary attacks against the Pre-Shared Key. The <I>aircrack-ng</I> suite, which consolidates tools for wireless network auditing, became a prominent platform for implementing this functionality. Its development has focused on improving efficiency and supporting various hardware acceleration methods, making it a widely adopted tool for both ethical hacking and penetration testing within the wireless security domain since the mid-2000s.


title: SEE ALSO
content:
<I>aircrack-ng</I>(1), <I>airodump-ng</I>(8), <I>airmon-ng</I>(8), <I>aireplay-ng</I>(8), <I>cowpatty</I>(1), <I>hashcat</I>(1)


title: SYNOPSIS
content:
<b>psql</b> [<i>OPTIONS</i>] [<i>DBNAME</i> [<i>USERNAME</i>]]<br><b>psql</b> [<i>OPTIONS</i>] [<i>CONNECTION_STRING</i>]


title: PARAMETERS
content:
<b><b>-h</b> <i>hostname</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the database server's <i>hostname</i> or <i>IP address</i> to connect to.<br><br><b><b>-p</b> <i>port</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the <b>TCP/IP</b> <i>port</i> or local <b>Unix domain socket file extension</b> on which the server is listening for connections.<br><br><b><b>-U</b> <i>username</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to the database as the specified <i>username</i>.<br><br><b><b>-d</b> <i>dbname</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the name of the database to connect to. Defaults to the user's username if not provided.<br><br><b><b>-c</b> <i>command</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes a single <b>SQL</b> <i>command</i> string and exits. Useful for quick queries or scripting.<br><br><b><b>-f</b> <i>filename</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes <b>SQL</b> commands from the specified <i>filename</i> and exits. Ideal for running scripts or batch operations.<br><br><b><b>-w</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Never prompts for a password. If the server requires password authentication and a password is not available from other means (e.g., <i>.pgpass</i>), the connection attempt will fail.<br><br><b><b>-W</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces <i>psql</i> to prompt for a password before connecting to a database, even if a <i>.pgpass</i> file or other method would provide one.<br><br><b><b>-l</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all available databases on the connected server and then exits. Similar to the interactive <b>\l</b> meta-command.<br><br><b><b>-V</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the <i>psql</i> version and exits.<br><br><b><b>-?</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows help about <i>psql</i> command line arguments and exits.<br><br><b><b>-q</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs in quiet mode. Suppresses startup messages and reduces verbosity during execution.<br><br><b><b>-t</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints only tuples (rows), without column names, footers, or other extraneous output, making it useful for scripting output parsing.<br><br>


title: DESCRIPTION
content:
<i>psql</i> is the foundational command-line interface for interacting with <b>PostgreSQL</b> databases, widely recognized as a leading open-source relational database management system.<br>It offers a powerful and flexible environment for users to connect to database instances, execute standard <b>SQL</b> queries, and perform comprehensive database administration and data management operations.<br>Functioning both interactively, where it provides a rich set of <B>meta-commands</B> (prefixed with <b>\</b>) for tasks like inspecting tables (<b>\d</b>) or listing databases (<b>\l</b>), and non-interactively, allowing for automated script execution (via <b>-f</b> option) or single command processing (with <b>-c</b> option), <i>psql</i> adapts to various workflows.<br>It is an essential tool for <b>PostgreSQL</b> developers, database administrators, and data analysts, providing a direct and efficient way to manage database objects, manipulate data, inspect schema definitions, and streamline routine tasks.


title: CAVEATS
content:
Connecting to a <b>PostgreSQL</b> server requires it to be running and accessible over the network or via a local socket.<br>For secure password handling, it is highly recommended to utilize the <i>.pgpass</i> file or environment variables (e.g., <b>PGPASSWORD</b>) rather than embedding passwords directly in scripts or command lines.<br><i>psql</i>'s powerful meta-commands (those starting with <b>\</b>) are specific to <i>psql</i> and are not standard <b>SQL</b> syntax, meaning they cannot be executed by other <b>SQL</b> clients.


title: INTERACTIVE MODE AND META-COMMANDS
content:
When run without the <b>-c</b> or <b>-f</b> options, <i>psql</i> enters an interactive mode. In this mode, users can type <b>SQL</b> commands or <b>meta-commands</b>. The <b>meta-commands</b> (prefixed with a backslash <b>\</b>) are specific <i>psql</i> commands designed for administrative tasks and schema exploration. Examples include <b>\d</b> (describe table/view), <b>\dt</b> (list tables), <b>\l</b> (list databases), <b>\q</b> (quit), <b>\e</b> (edit current query buffer in an external editor), and <b>\?</b> (list all available meta-commands with short descriptions).


title: NON-INTERACTIVE USAGE FOR SCRIPTING
content:
Beyond its interactive capabilities, <i>psql</i> is a powerful tool for scripting and automation. The <b>-f</b> option allows for the execution of an entire <b>SQL</b> script file, which is invaluable for database migrations, bulk data loading, or applying schema changes.<br>Similarly, the <b>-c</b> option enables the execution of a single <b>SQL</b> command directly from the command line, facilitating quick programmatic interactions with the database without entering an interactive session.


title: CUSTOMIZATION THROUGH <I>.PSQLRC</I>
content:
<i>psql</i>'s behavior and appearance can be extensively customized by creating a startup file named <i>.psqlrc</i> in the user's home directory. This file can contain any <i>psql</i> commands, including <b>\set</b> to define custom variables, <b>\pset</b> to control output formatting (e.g., table borders, titles), or even <b>SQL</b> commands to be executed upon every <i>psql</i> session start. This allows users to tailor their environment for improved efficiency and readability.


title: HISTORY
content:
<i>psql</i> has been an integral part of the <b>PostgreSQL</b> project since its inception, tracing its roots back to the <b>Postgres</b> project at the University of California, Berkeley.<br>Over the decades, it has continuously evolved alongside the <b>PostgreSQL</b> server, incorporating new features, improving user experience, and adapting to modern database administration needs, solidifying its role as the primary command-line interface for the database.


title: SYNOPSIS
content:
<b>pssh</b> [<i>options</i>] [<i>command</i> [<i>arg ...</i>]]<br><br><i>Examples:</i><br><b>pssh</b> -h /etc/pssh/hosts.txt -l root "uptime"<br><b>pssh</b> -H "user1@host1" -H "host2" "ls -la /tmp"


title: PARAMETERS
content:
<b><b>-h</b> <i>FILE</i>, <b>--hosts</b> <i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads the list of target hosts from the specified <i>FILE</i>. Each line in the file should contain a single host entry, optionally prefixed with a username and port (e.g., <i>user@host:port</i>).<br><br><b><b>-H</b> <i>[USER@]HOST[:PORT]</i>, <b>--host</b> <i>[USER@]HOST[:PORT]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a single host to the list of targets. This option can be specified multiple times to target several hosts directly from the command line.<br><br><b><b>-l</b> <i>USER</i>, <b>--user</b> <i>USER</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the username to use for SSH login on all remote hosts. Overrides any username specified in the host file or via <b>-H</b>.<br><br><b><b>-p</b> <i>NUM</i>, <b>--parallel</b> <i>NUM</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum number of parallel SSH connections that <b>pssh</b> will attempt to establish simultaneously. The default value is 32.<br><br><b><b>-t</b> <i>SECONDS</i>, <b>--timeout</b> <i>SECONDS</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a timeout, in <i>SECONDS</i>, for each individual SSH connection and the execution of the remote command. If the command does not complete within this time, it is terminated.<br><br><b><b>-o</b> <i>DIR</i>, <b>--output-dir</b> <i>DIR</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Saves the standard output (stdout) of each remote command to separate files within the specified <i>DIR</i>ectory. Each file is named after the hostname.<br><br><b><b>-e</b> <i>DIR</i>, <b>--error-dir</b> <i>DIR</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Saves the standard error (stderr) of each remote command to separate files within the specified <i>DIR</i>ectory. Similar to <b>-o</b>, files are named after the hostname.<br><br><b><b>-i</b>, <b>--inline</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the standard output and standard error from remote commands to the local console immediately as they complete, interleaving results from different hosts.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, providing more detailed information about the execution process, including connection attempts and command status.<br><br><b><b>-A</b>, <b>--askpass</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prompts the user for a password to use for SSH authentication. Useful when using password-based authentication instead of SSH keys.<br><br><b><b>-x</b> <i>ARGS</i>, <b>--extra-args</b> <i>ARGS</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Passes additional arguments directly to the underlying <b>ssh</b> command for each connection (e.g., <i>-x "-o StrictHostKeyChecking=no"</i>).<br><br>


title: DESCRIPTION
content:
<b>pssh</b>, or <i>Parallel SSH</i>, is a powerful command-line tool designed to execute commands on multiple remote hosts concurrently via SSH. It's an integral part of the <i>pssh utilities package</i>, which streamlines system administration tasks across a cluster of machines. Users can specify a list of target hosts either from a file or directly via command-line options. <b>pssh</b> then establishes parallel SSH connections to these hosts and runs the specified command, collecting and displaying the output. It offers robust options for controlling parallelism, setting timeouts, handling errors, and managing output redirection, making it highly efficient for tasks like deploying software, applying configuration changes, performing system audits, or monitoring across numerous servers simultaneously. Its primary goal is to significantly reduce manual effort and save time when managing large numbers of remote systems.


title: CAVEATS
content:
When using <b>pssh</b>, ensure that SSH is properly configured on all target hosts and that appropriate authentication (e.g., SSH keys with an agent) is in place to avoid repeated password prompts. For large numbers of hosts, <b>pssh</b> can consume significant local resources (CPU, memory, file descriptors) depending on the <i>--parallel</i> setting. Care should be taken when executing commands that modify system state, as errors on a subset of hosts can lead to inconsistent configurations across the cluster. Output management can also be complex for many hosts; consider using <b>--output-dir</b> and <b>--error-dir</b> for detailed logging rather than relying solely on <b>--inline</b>.


title: HOST FILE FORMAT
content:
The hosts file specified with <b>-h</b> or <b>--hosts</b> expects one host entry per line. Each entry can be in the format <i>[user@]host[:port]</i>. Blank lines and lines starting with a <i>#</i> character are treated as comments and ignored.


title: EXIT STATUS
content:
<b>pssh</b> returns an exit status of 0 if all remote commands executed successfully and there were no internal <b>pssh</b> errors. A non-zero exit status indicates that one or more remote commands failed, or an error occurred during <b>pssh</b>'s operation itself. This is crucial for scripting and error handling.


title: AUTHENTICATION
content:
<b>pssh</b> leverages standard SSH authentication mechanisms. It will typically try SSH keys first (honoring <i>~/.ssh/config</i> and <i>ssh-agent</i>), and if unsuccessful and <b>-A</b> is used, it will prompt for a password.


title: HISTORY
content:
<b>pssh</b> is part of the <i>pssh utilities suite</i>, originally developed by Andrew McNabb. It emerged as a lightweight yet powerful solution for executing commands across multiple servers in parallel, bridging the gap between simple shell scripting with <b>ssh</b> loops and more comprehensive configuration management systems like Ansible or SaltStack. Its design focuses on simplicity, efficiency, and direct command execution, making it a popular choice for ad-hoc administration tasks and integration into larger automation scripts where full-fledged orchestration tools might be overkill.


title: PARAMETERS
content:
<b><I>PID</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>The process ID of the target process for which to display the stack trace. This is the only required argument.</I><br><br>


title: DESCRIPTION
content:
<I>The `pstack` command is a utility used to display the stack trace of a running process. It attaches to the specified process and outputs the current call stack for each of its threads. This is particularly useful for debugging hung applications, identifying where a process is spending its time, or understanding its current execution path. Internally, `pstack` is often a simple wrapper script that invokes the GNU Debugger (gdb) with specific commands (e.g., `thread apply all bt`) to achieve its functionality. Because it uses `gdb`, it requires appropriate permissions to attach to the target process. The output includes function names and often line numbers if the executable was compiled with debugging symbols. It provides a quick, non-interactive way to inspect process state.</I>


title: CAVEATS
content:
<I><b>Permissions:</b> Requires `ptrace` permissions, typically meaning it must be run as the root user or the same user that owns the target process. System security settings like `/proc/sys/kernel/yama/ptrace_scope` can restrict its usage.<br><b>Process Interruption:</b> Attaching to a process temporarily pauses it while stack information is gathered. This pause is usually very brief but can affect real-time or performance-sensitive applications.<br><b>Symbol Information:</b> The detail of the stack trace (function names, line numbers) depends on whether the executable was compiled with debugging symbols. Without symbols, only addresses might be shown.<br><b>Wrapper Script:</b> `pstack` is often a shell script wrapper around `gdb`. For advanced debugging, using `gdb` directly offers more control.</I>


title: <I>UNDERLYING MECHANISM</I>
content:
<I>pstack typically works by spawning a `gdb` process, instructing it to attach to the specified PID, execute the `thread apply all bt` command (which prints a backtrace for all threads), and then detach. This makes it a quick, non-interactive way to get stack information.<br></I>


title: <I>SECURITY (PTRACE_SCOPE)</I>
content:
<I>The `/proc/sys/kernel/yama/ptrace_scope` sysctl parameter controls who can use `ptrace` (and thus `pstack`) on processes. A value of `0` typically means any user can attach to any process they own. A value of `1` (default on many systems) means only a parent process can trace its children, or a process can only trace another if it has CAP_SYS_PTRACE capability (e.g., root).<br></I>


title: HISTORY
content:
<I>The `pstack` command has historically served as a convenient wrapper for obtaining stack traces without needing to interact directly with the `gdb` debugger. It emerged as a simple utility to quickly inspect running processes. Over time, as users became more familiar with `gdb` and its direct attachment capabilities, `pstack`'s role has sometimes been described as a compatibility or legacy script, though it remains widely used for quick diagnostic checks due to its simplicity.</I>


title: PARAMETERS
content:
<b><b>-f</b> &lt;<i>format</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the desired output format. Examples include <b>emf</b>, <b>wmf</b>, <b>svg</b>, <b>dxf</b>, <b>pdf</b>, etc. A full list can be obtained via <b>pstoedit -help</b>.<br><br><b><b>-ps2ps</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Utilizes the <b>ps2ps</b> filter for PostScript processing. This can be beneficial for handling complex or problematic PostScript input files.<br><br><b><b>-x</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Extracts text objects as editable text rather than converting them into outlines or polygons, improving text editability in the output format.<br><br><b><b>-z</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Treats lines and curves as distinct line segments rather than converting them into filled polygons, preserving vector line integrity.<br><br><b><b>-s</b> &lt;<i>scale</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a scaling factor to the output graphics. For example, <b>-s 2</b> would double the size of the output.<br><br><b><b>-dpi</b> &lt;<i>resolution</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the resolution in dots per inch for any raster (bitmap) images that might be embedded within the output vector file.<br><br><b><b>-rotate</b> &lt;<i>angle</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Rotates the entire output by the specified angle in degrees. Useful for correcting orientation issues.<br><br><b><b>-gs</b> &lt;<i>options</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Passes additional, comma-separated options directly to the underlying <b>Ghostscript</b> interpreter, allowing fine-grained control over rendering.<br><br><b><b>-debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose debug output, which can be helpful for troubleshooting conversion issues.<br><br>


title: DESCRIPTION
content:
<i>pstoedit</i> is a versatile command-line utility designed to convert PostScript and PDF files into a wide range of editable vector graphics formats. It serves as a crucial bridge, allowing users to repurpose content from these document formats into applications like CAD software, vector drawing programs, or office suites. The tool leverages the powerful Ghostscript interpreter to process the input files, extract graphical elements, and then translate them into structured vector formats such as <b>SVG</b>, <b>EMF</b>, <b>WMF</b>, <b>DXF</b>, and various PostScript versions. This capability is invaluable for designers, engineers, and anyone needing to modify or extract vector data embedded within PostScript or PDF documents, providing a flexible workflow for graphic manipulation.


title: CAVEATS
content:
<i>pstoedit</i>'s performance and output quality are heavily reliant on the installed <b>Ghostscript</b> version and its configuration. <br><br>Complex PostScript or PDF files, especially those using non-standard fonts, transparency, or intricate graphic effects, may not always convert perfectly to all target vector formats. <br><br>Text extraction can sometimes be challenging, leading to text being converted into outlines instead of editable text strings, depending on the input file's structure and the chosen output format.


title: SUPPORTED OUTPUT FORMATS
content:
<i>pstoedit</i> supports a vast array of output formats, including various versions of <b>SVG</b> (Scalable Vector Graphics), <b>EMF</b> (Enhanced Metafile), <b>WMF</b> (Windows Metafile), <b>DXF</b> (Drawing Exchange Format for CAD), <b>PDF</b>, various levels of <b>PostScript</b>, <b>HPGL</b>, <b>CGM</b>, and more. The specific formats available depend on the installed plugins and Ghostscript version.


title: DEPENDENCIES
content:
The core functionality of <i>pstoedit</i> critically relies on the <b>Ghostscript</b> interpreter. For optimal performance and a wide range of output formats, ensure that a recent and properly configured Ghostscript installation is available on your system.


title: HISTORY
content:
<i>pstoedit</i> has a long and active development history, primarily maintained by Wolfgang Glunz. It has consistently evolved to support new PostScript and PDF features, as well as an expanding array of output formats. Its enduring presence in the Linux and Unix utility landscape underscores its significance as a robust tool for vector graphic conversion.


title: PARAMETERS
content:
<b><b>-resolution</b> <i><res></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the resolution in DPI (dots per inch) for rendering the PostScript. Common values include 75, 150, 300. Default is usually 75 DPI.<br><br><b><b>-page</b> <i><n></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Renders and outputs only the specified page number <I>n</I> from the PostScript document. If omitted, the first page is processed.<br><br><b><b>-portrait</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the PostScript interpreter to render the document in portrait orientation, regardless of its internal settings.<br><br><b><b>-landscape</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the PostScript interpreter to render the document in landscape orientation, regardless of its internal settings.<br><br><b><b>-mono</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output image to be monochrome (black and white), resulting in a <I>PBM</I> format image.<br><br><b><b>-gray</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output image to be grayscale, resulting in a <I>PGM</I> format image.<br><br><b><b>-color</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output image to be color, resulting in a <I>PPM</I> format image. This is often the default if the PostScript content is color.<br><br><b><b>-forceplain</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the <I>Netpbm</I> image in plain (ASCII) format rather than the default raw (binary) format. Plain format is human-readable but larger.<br><br><b><b>-eps</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Treats the input PostScript file as an Encapsulated PostScript (<I>EPS</I>) file. This often implies a different bounding box handling.<br><br><b><b>-margin</b> <i><val></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a margin of <I>val</I> points around the rendered PostScript content.<br><br><b><b>-gsarg</b> <i><arg></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Passes the specified argument <I>arg</I> directly to the underlying <I>Ghostscript</I> command. Useful for fine-tuning Ghostscript behavior.<br><br><b><b>-verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints informative messages about the conversion process to standard error.<br><br>


title: DESCRIPTION
content:
<i>pstopnm</i> is a utility from the <I>Netpbm</I> suite that converts <I>PostScript</I> language files into <I>Netpbm</I> image formats: <I>PBM</I> (portable bitmap), <I>PGM</I> (portable graymap), or <I>PPM</I> (portable pixmap). It internally uses a <I>PostScript</I> interpreter, typically <I>Ghostscript</I> (<i>gs</i>), to render the <I>PostScript</I> content into a raster image. This tool is essential for processing <I>PostScript</I> documents in image manipulation workflows, allowing users to preview pages, extract content as images, or convert them for use with other image processing programs. It supports selecting specific pages, adjusting resolution, and forcing output to monochrome, grayscale, or color based on requirements.


title: CAVEATS
content:
<i>pstopnm</i> relies heavily on the availability and configuration of an external <I>PostScript</I> interpreter, typically <I>Ghostscript</I> (<i>gs</i>). If <I>Ghostscript</I> is not installed or not found in the system's <I>PATH</I>, <i>pstopnm</i> will fail. The quality and features of the output image are limited by the capabilities of the underlying <I>Ghostscript</I> version and its rendering engine.


title: DEPENDENCY ON GHOSTSCRIPT
content:
<i>pstopnm</i> does not render <I>PostScript</I> itself. It acts as a wrapper, piping the <I>PostScript</I> input to an external interpreter, most commonly <I>Ghostscript</I> (<i>gs</i>), and then processing <I>Ghostscript</I>'s output into a <I>Netpbm</I> format. Therefore, <I>Ghostscript</I> must be installed and accessible in the system's <I>PATH</I> for <i>pstopnm</i> to function.


title: OUTPUT FORMATS
content:
The command can output to three primary <I>Netpbm</I> formats: <br><b>PBM (Portable Bitmap):</b> For monochrome (black and white) images.<br><b>PGM (Portable Graymap):</b> For grayscale images with varying shades of gray.<br><b>PPM (Portable Pixmap):</b> For full-color images.<br>The choice of output format is often determined by the input <I>PostScript</I> content and the use of options like <b>-mono</b>, <b>-gray</b>, or <b>-color</b>.


title: HISTORY
content:
<i>pstopnm</i> is part of the <I>Netpbm</I> package, a collection of graphics utilities that originated from <I>PBMplus</I> by Jef Poskanzer in the late 1980s. The <I>Netpbm</I> project's philosophy is to provide simple, portable, and interchangeable command-line tools for image manipulation. <i>pstopnm</i> was developed to bridge the gap between the <I>PostScript</I> document format and the <I>Netpbm</I> raster image formats, leveraging external <I>PostScript</I> interpreters like <I>Ghostscript</I> for the actual rendering process.


title: PARAMETERS
content:
<b>-a</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>-a</b><br>Show command-line arguments. By default, <i>pstree</i> only shows the command name. This can make the output very wide.<br><br><b>-c</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>-c</b><br>Disable compact mode. This prevents <i>pstree</i> from compacting identical subtrees into a single entry with a count (e.g., "{httpd,3}").<br><br><b>-h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>-h</b><br>Highlight the current process and its ancestors in the tree. This helps quickly locate your current shell or script within the hierarchy.<br><br><b>-g</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>-g</b><br>Show PIDs as process group IDs. Instead of individual PIDs, this option displays the process group ID in parentheses.<br><br><b>-l</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>-l</b><br>Long lines. Don't truncate long lines, showing full command paths and arguments when used with <b>-a</b>.<br><br><b>-n</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>-n</b><br>Sort processes by PID numerically instead of by name. This can alter the visual order of sibling processes.<br><br><b>-p</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>-p</b><br>Show PIDs. Displays the Process ID in parentheses after each process name.<br><br><b>-u</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>-u</b><br>Show UIDs. Displays the effective User ID in parentheses after each process name.<br><br><b>-T</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>-T</b><br>Don't draw branches for single children. This creates a more linear, less branched output for direct parent-child relationships where a parent has only one child.<br><br><b>-V</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>-V</b><br>Display version information and exit.<br><br><b>pid</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The PID of a specific process. <i>pstree</i> will display the subtree starting from this process and its descendants only.<br><br><b>user</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The username. <i>pstree</i> will display the tree for processes owned by this specified user only.<br><br>


title: DESCRIPTION
content:
<i>pstree</i> is a command-line utility that displays running processes in a hierarchical, tree-like format. Unlike the <i>ps</i> command, which provides a flat list of processes, <i>pstree</i> visually represents parent-child relationships, making it easy to understand which processes were started by which others. This hierarchical view is particularly useful for debugging, system monitoring, and understanding process dependencies.<br><br>It typically starts the tree from <i>init</i> (PID 1) or <i>systemd</i>, showing all its descendants. Users can specify a particular PID or username to view only the subtree originating from that point. The output can be customized to show Process IDs (PIDs), command-line arguments, or User IDs (UIDs).


title: CAVEATS
content:
<i>pstree</i> relies on information from the <i>/proc</i> filesystem. If <i>/proc</i> is not correctly mounted or accessible (e.g., in some chroot or container environments), <i>pstree</i> may not function as expected or provide incomplete information. The output represents a snapshot at the time the command is executed, not a real-time view. On systems with many processes, the output can be very extensive and scroll rapidly, potentially making it hard to read without piping to a pager like <i>less</i>.


title: COMPACT MODE
content:
By default, <i>pstree</i> condenses identical branches by showing a count in curly braces (e.g., "{httpd,3}" means three identical httpd processes). This behavior helps reduce clutter in the output. Use the <b>-c</b> option to disable this compaction and show every process individually.


title: COLOR OUTPUT
content:
Some versions of <i>pstree</i> support colorized output, which can be enabled via environment variables (e.g., <i>LS_COLORS</i> or specific <i>PSTREE_COLORS</i> settings) or through specific terminal configurations. This can enhance readability, especially when highlighting processes with the <b>-h</b> option, making it easier to distinguish different parts of the tree.


title: HISTORY
content:
<i>pstree</i> is part of the <i>psmisc</i> package, a collection of utilities for displaying and manipulating processes. It has been a standard utility in most Linux distributions for many years, providing a crucial visual complement to the more tabular output of commands like <i>ps</i>. Its development aimed to offer a more intuitive way to understand process relationships, which is fundamental for system administration and troubleshooting.


title: PARAMETERS
content:
<b><code>--help</code>, <code>-h</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display help for the current command.<br><br><b><code>--version</code>, <code>-V</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display this application version.<br><br><b><code>--config=&lt;path&gt;</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a path to a custom PsySH config file.<br><br><b><code>--ansi</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force ANSI output.<br><br><b><code>--no-ansi</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable ANSI output.<br><br><b><code>--verbose</code>, <code>-v|vv|vvv</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug.<br><br><b><code>--quiet</code>, <code>-q</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not output any message.<br><br><b><code>--raw</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Raw output.<br><br>


title: DESCRIPTION
content:
<br>Psysh is a powerful runtime developer console, also known as a REPL (Read-Eval-Print Loop), for PHP.<br><br>It provides an interactive command-line environment where PHP code snippets can be executed directly, variable states can be inspected, and documentation can be looked up. Psysh is an invaluable tool for rapid prototyping, debugging, and exploring PHP libraries and frameworks. It goes beyond a simple `php -a` by offering advanced features like a `ls` command for inspecting objects, `doc` for documentation, a built-in debugger, and the ability to extend its functionality with custom commands. It helps developers understand their code's runtime behavior without the need to modify files or reload web servers.


title: CAVEATS
content:
<br>Psysh is primarily a development and debugging tool and should not be used in production environments. Its interactive nature and access to the application's runtime state pose security risks if exposed.<br><br>While powerful, it requires a working PHP installation and Composer for typical installation.


title: <B>KEY FEATURES</B>
content:
<br>Psysh offers a rich set of features including:<br>- Variable inspection: Use `ls` to inspect variables, objects, and scope.<br>- Documentation lookup: `doc` command to read PHP manual pages directly.<br>- Code execution: Execute arbitrary PHP code in the current context.<br>- Built-in debugger: Step through code, set breakpoints, and inspect the call stack.<br>- Customizable: Extensible with custom commands and configuration.<br>- Intelligent output: Pretty-prints arrays and objects for readability.


title: <B>INSTALLATION</B>
content:
<br>Psysh is most commonly installed globally via Composer, the PHP package manager: `composer global require psy/psysh:@stable`. It can also be added as a development dependency to a project.


title: <B>CONFIGURATION</B>
content:
<br>Psysh can be configured via a `.psysh.php` file in the user's home directory or the project root, allowing customization of settings, commands, and tab completion.


title: HISTORY
content:
<br>Psysh was created by Justin Hileman and first released around 2013-2014. It emerged as a response to the need for a more sophisticated and feature-rich interactive PHP console, similar to those available in other languages like Ruby (IRB) or Python. Before Psysh, PHP developers often relied on `php -a` (the basic interactive mode) or print statements for debugging. Psysh quickly gained popularity within the PHP community for its advanced features, ease of use, and extensibility, becoming a de-facto standard for interactive PHP development.


title: PARAMETERS
content:
<b><b>-i</b>, <b>--ignore-case</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Ignore case distinctions in the pattern and input files.</i><br><br><b><b>-S</b>, <b>--smart-case</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Ignore case if the pattern contains no uppercase characters; otherwise, match case.</i><br><br><b><b>-w</b>, <b>--word-regexp</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Force the pattern to match only whole words.</i><br><br><b><b>-Q</b>, <b>--literal</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Treat the pattern as a literal string, escaping any regular expression metacharacters.</i><br><br><b><b>-v</b>, <b>--invert-match</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Invert the sense of matching, to select non-matching lines.</i><br><br><b><b>-l</b>, <b>--files-with-matches</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Only print the names of files that contain matches, one per line.</i><br><br><b><b>-L</b>, <b>--files-without-matches</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Only print the names of files that do not contain matches, one per line.</i><br><br><b><b>-C</b> <i>NUM</i>, <b>--context=</b><i>NUM</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Print <b>NUM</b> lines of context around matches.</i><br><br><b><b>-B</b> <i>NUM</i>, <b>--before-context=</b><i>NUM</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Print <b>NUM</b> lines of leading context before matches.</i><br><br><b><b>-A</b> <i>NUM</i>, <b>--after-context=</b><i>NUM</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Print <b>NUM</b> lines of trailing context after matches.</i><br><br><b><b>-p</b> <i>PATTERN</i>, <b>--path-regexp=</b><i>PATTERN</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Only search files whose path matches the given regular expression <b>PATTERN</b>.</i><br><br><b><b>-g</b> <i>PATTERN</i>, <b>--file-regexp=</b><i>PATTERN</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Only search files whose name matches the given regular expression <b>PATTERN</b>.</i><br><br><b><b>-a</b>, <b>--all-files</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Search all files, including hidden and ignored files (those typically ignored by <i>.gitignore</i>).</i><br><br><b><b>-j</b> <i>NUM</i>, <b>--jobs=</b><i>NUM</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Number of search workers to use. Defaults to the number of CPU cores.</i><br><br>


title: DESCRIPTION
content:
The Platinum Searcher (<b>pt</b>) is a powerful command-line tool designed for <b>ultra-fast</b> code searching across large codebases. It serves as a modern alternative to traditional tools like <b>grep</b>, <b>ack</b>, and <b>ag</b> (The Silver Searcher), offering significant speed improvements by leveraging concurrent processing. Written in Go, <b>pt</b> intelligently navigates file systems, respecting <i>.gitignore</i> and <i>.ptignore</i> rules to automatically skip irrelevant files and directories. It supports various search patterns, including regular expressions and literal strings, and provides options for filtering by file type, path, and context control. Its primary advantage lies in its ability to quickly locate code snippets within vast projects, making it an indispensable tool for developers working on large software repositories.


title: CAVEATS
content:
<b>pt</b> is not a standard Linux utility and must be installed separately. While highly optimized for speed, its parallel processing can consume significant CPU resources on very large codebases. Its regular expression syntax follows Go's standard library, which might have minor differences from GNU <b>grep</b>'s regex flavor.


title: CONFIGURATION AND IGNORING FILES
content:
<b>pt</b> intelligently respects common version control ignore files. It automatically skips files and directories specified in <i>.gitignore</i>, <i>.hgignore</i>, and its own specific ignore file, <i>.ptignore</i>. The <i>.ptignore</i> file takes precedence over others, allowing for fine-grained control over what gets searched.


title: PERFORMANCE OPTIMIZATION
content:
A core design principle of <b>pt</b> is speed. It achieves its high performance by utilizing multiple CPU cores through Go's Goroutines for parallel file processing and optimized I/O operations. This allows it to outperform many traditional search tools, especially when dealing with massive repositories containing millions of lines of code.


title: HISTORY
content:
<b>The Platinum Searcher</b> (<b>pt</b>) was created by monochromegane (Yasuhiro Matsumoto), inspired by similar code search tools like <b>ack</b> and <b>ag</b> (The Silver Searcher). It was developed with a primary focus on speed and efficiency for large codebases, leveraging the Go programming language's powerful concurrency features. Since its inception, it has gained popularity among developers for its ability to quickly navigate and search through extensive software projects, making it a valuable addition to many development workflows.


title: SYNOPSIS
content:
<b>tar</b> [<i>OPTION...</i>] [<i>FILE...</i>]<br>Common usage modes:<br>&nbsp;&nbsp;<b>tar</b> <i>-c</i>[<i>v</i>][<i>f ARCHIVE</i>] [<i>FILE...</i>]<br>&nbsp;&nbsp;<b>tar</b> <i>-x</i>[<i>v</i>][<i>f ARCHIVE</i>]<br>&nbsp;&nbsp;<b>tar</b> <i>-t</i>[<i>v</i>][<i>f ARCHIVE</i>]


title: PARAMETERS
content:
<b><i>-c</i>, <i>--create</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a new <b>tar</b> archive.<br><br><b><i>-x</i>, <i>--extract</i>, <i>--get</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Extracts files from a <b>tar</b> archive.<br><br><b><i>-t</i>, <i>--list</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists the contents of a <b>tar</b> archive.<br><br><b><i>-f ARCHIVE</i>, <i>--file=ARCHIVE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the archive file or device to use.<br><br><b><i>-v</i>, <i>--verbose</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the files processed during archive creation or extraction.<br><br><b><i>-z</i>, <i>--gzip</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Compresses or decompresses the archive using <b>gzip</b>.<br><br><b><i>-j</i>, <i>--bzip2</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Compresses or decompresses the archive using <b>bzip2</b>.<br><br><b><i>-J</i>, <i>--xz</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Compresses or decompresses the archive using <b>xz</b>.<br><br><b><i>-C DIR</i>, <i>--directory=DIR</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Changes to the specified directory before performing operations.<br><br><b><i>-p</i>, <i>--preserve-permissions</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Preserves file permissions and ownership during extraction.<br><br><b><i>--exclude=PATTERN</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Excludes files or directories matching the specified <b>PATTERN</b> from the archive.<br><br><b><i>-L</i>, <i>--dereference</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Follows symbolic links; archives the files they point to, not the links themselves.<br><br>


title: DESCRIPTION
content:
The command <i>'ptar'</i> is not a standard Linux utility. This analysis assumes it's a typo for <b>tar</b> (short for <b>T</b>ape <b>AR</b>chiver), which is a fundamental and widely used command-line utility for creating, manipulating, and extracting archive files. <br><br><b>tar</b> is primarily used for collecting multiple files and directories into a single archive file, often called a 'tarball'. While <b>tar</b> itself only packages files, it is frequently combined with compression utilities like <b>gzip</b>, <b>bzip2</b>, or <b>xz</b> to create compressed archives (e.g., <code>.tar.gz</code>, <code>.tgz</code>, <code>.tar.bz2</code>, <code>.tar.xz</code>). <br><br>Its key features include preserving file permissions, directory structures, timestamps, and symbolic links. It's an indispensable tool for backups, software distribution, and transferring collections of files.


title: CAVEATS
content:
The command <i>'ptar'</i> is not a standard Linux command. This analysis is entirely based on the widely used <b>tar</b> command. <br><br>While <b>tar</b> is robust, be aware of: <br>Permissions: Extracting as root may overwrite system files. <b>tar</b> preserves permissions and ownership, which can be a security consideration.<br>Absolute vs. Relative Paths: Be cautious when archiving with absolute paths, as they will be extracted to the same absolute path, potentially overwriting system files. Using relative paths is generally safer.<br>Special Files: Handling of device files, named pipes, and sockets can vary or require specific options.<br>Random Access: Compressed archives cannot be randomly accessed; viewing or extracting a single file typically requires decompressing a significant portion of the archive.<br>


title: COMMON USE CASES
content:
Here are some typical ways <b>tar</b> is used:<br><b>Create a compressed archive:</b><br>&nbsp;&nbsp;<b>tar</b> <i>-czvf</i> <i>myarchive.tar.gz</i> <i>/path/to/directory</i> <i>file1.txt</i><br>&nbsp;&nbsp;(Create, gzip, verbose, file)<br><b>Extract a compressed archive:</b><br>&nbsp;&nbsp;<b>tar</b> <i>-xzvf</i> <i>myarchive.tar.gz</i><br>&nbsp;&nbsp;(Extract, gzip, verbose, file)<br><b>List contents of an archive:</b><br>&nbsp;&nbsp;<b>tar</b> <i>-tzvf</i> <i>myarchive.tar.gz</i><br>&nbsp;&nbsp;(List, gzip, verbose, file)<br><b>Extract specific files:</b><br>&nbsp;&nbsp;<b>tar</b> <i>-xvf</i> <i>myarchive.tar</i> <i>path/to/specific/file.txt</i><br><b>Create an archive, excluding certain files:</b><br>&nbsp;&nbsp;<b>tar</b> <i>-cvf</i> <i>myarchive.tar</i> <i>--exclude='*.log'</i> <i>--exclude='temp_dir'</i> <i>/source/directory</i>


title: HISTORY
content:
The <b>tar</b> command originated in the early days of Unix (circa 1979 at AT&T Bell Labs) as a utility for archiving files onto magnetic tapes. Its primary purpose was backup and restoration. <br><br>Over time, as tape drives became less common for general data transfer and disk-based storage became prevalent, <b>tar</b>'s use evolved to create archives on disk files. The GNU project developed its own version, GNU <b>tar</b>, which is the most common implementation found on Linux systems today, adding many features like support for various compression formats (via external programs like <b>gzip</b>) and incremental backups. Its core functionality and syntax have remained remarkably consistent over decades, making it a cornerstone of Unix-like operating systems.


title: SYNOPSIS
content:
<b>tar</b> [<i>OPTIONS</i>] <b>--diff</b> [<i>ARCHIVE_OR_FILES...</i>]<br><b>tar</b> [<i>OPTIONS</i>] <b>-d</b> [<i>ARCHIVE_OR_FILES...</i>]<br><br><i>Note: When comparing an archive to the filesystem, the archive path is usually specified with <b>-f</b>.</i>


title: PARAMETERS
content:
<b><b>--diff</b>, <b>-d</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Compare archive members to corresponding files on disk.<br><br><b><b>-f</b> <i>ARCHIVE</i>, <b>--file</b>=<i>ARCHIVE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the archive file to operate on. Essential when comparing an archive.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;List files processed. When used with <b>--diff</b>, it shows details of differences found.<br><br><b><b>-N</b> <i>DATE</i>, <b>--newer</b>=<i>DATE</i>, <b>--after-date</b>=<i>DATE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only consider files newer than <i>DATE</i> for comparison.<br><br><b><b>--exclude</b>=<i>PATTERN</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exclude files or directories matching <i>PATTERN</i> from the comparison.<br><br><b><b>--ignore-failed-read</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not exit with a non-zero status if a file cannot be read during the comparison.<br><br><b><b>--no-recursion</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not recurse into directories when comparing. By default, <b>--diff</b> is recursive for directories.<br><br>


title: DESCRIPTION
content:
The command <i>ptardiff</i> is not a standard or widely recognized utility in common Linux distributions. It is highly probable that this refers to the <b>`tar --diff`</b> (or <b>`-d`</b>) functionality, which compares the contents of a `tar` archive with files on the filesystem. This analysis proceeds assuming the user intended to inquire about <b>`tar`</b>'s archive comparison capabilities.<br><br><b>`tar --diff`</b> is a powerful feature of the <b>`tar`</b> utility used to compare the contents of a `tar` archive with files on the filesystem, or implicitly to compare two archives by comparing extracted contents. It reports discrepancies in file size, modification times, permissions, and file content. This function is essential for verifying archive integrity, checking for unauthorized modifications, or confirming successful backups. It can show which files are missing from the archive, which have changed, and which are new.


title: CAVEATS
content:
As <i>ptardiff</i> is not a standard command, this analysis focuses on <b>`tar --diff`</b>.<br><br><b>`tar --diff`</b> primarily compares an archive against the live filesystem. Directly comparing two separate <b>`tar`</b> archives requires extracting one or both, and then using external tools like <b>`diff -r`</b> on the extracted directories.<br><br>It reports differences based on metadata (permissions, ownership, timestamps) and content. Minor timestamp differences might be reported even if content is identical.<br><br>The exact behavior and available options can vary slightly between different <b>`tar`</b> implementations (e.g., GNU `tar` vs. BSD `tar`).


title: EXIT STATUS
content:
<b>`tar --diff`</b> exits with status 0 if no differences are found, 1 if differences are found, and a value greater than 1 if a fatal error occurs during the operation.


title: IMPLICIT DIRECTORY COMPARISON
content:
When comparing an archive that contains directories, <b>`tar --diff`</b> automatically performs a recursive comparison of the directory contents by default, unless <b>`--no-recursion`</b> is specified.


title: HISTORY
content:
The <b>`tar`</b> (tape archive) utility originated in Unix in the early 1970s, designed for backing up files to tape drives. Over time, it evolved to support various storage media and functionalities. The <b>`diff`</b> (compare) functionality was introduced as a standard part of the <b>`tar`</b> utility to provide integrity checks and facilitate backup verification, making it a fundamental feature for managing archived data.


title: PARAMETERS
content:
<b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the version of <b>ptpython</b> and exits.<br><br><b><b>--vi</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables Vi keybindings for command-line editing.<br><br><b><b>--emacs</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables Emacs keybindings (this is the default behavior).<br><br><b><b>--autocompletion-style</b> <i>[fuzzy|common]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Chooses the autocompletion style. 'fuzzy' allows for more flexible matches, while 'common' matches from the start.<br><br><b><b>--colorscheme</b> <i>[default|solarized-dark|solarized-light|monokai|per-row]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects a pre-defined color scheme for syntax highlighting and the UI.<br><br><b><b>--paste-mode</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables a special paste mode, useful for pasting large blocks of code without unintended indentations.<br><br><b><b>--confirm-exit</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Asks for confirmation before exiting the shell, preventing accidental closures.<br><br><b><b>--disable-input-validation</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables real-time syntax validation as you type, which can sometimes be distracting.<br><br><b><b>--history-search</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables incremental search through the command history (Ctrl+R in Emacs mode).<br><br><b><b>--dont-load-config</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents <b>ptpython</b> from loading the user's default configuration file (<i>~/.ptpython/config.py</i>).<br><br><b><b>--config-file</b> <i>PATH</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative path to a custom configuration file.<br><br><b><b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses the welcome message displayed at startup.<br><br><b><b>--startup-paths</b> <i>TEXT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A comma-separated list of additional paths to add to <b>sys.path</b>, making modules in those directories importable.<br><br><b><b>--shell-plus</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Integrates with Django's <b>shell_plus</b> command if Django is installed, providing a pre-loaded Django environment.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a comprehensive help message and exits.<br><br>


title: DESCRIPTION
content:
<b>ptpython</b> is an advanced, interactive Python REPL (Read-Eval-Print Loop) built on top of the powerful <i>prompt_toolkit</i> library. It aims to provide a superior interactive experience compared to the default Python interpreter.<br><br>Key features include intelligent autocompletion, syntax highlighting, multiline editing with easy navigation, a sophisticated history mechanism with search capabilities, and customizable key bindings (Vi and Emacs modes are supported). Users can extensively configure <b>ptpython</b> through a Python configuration file, allowing for personalized themes, key maps, and startup actions. It's an excellent tool for development, debugging, and general Python exploration.


title: CAVEATS
content:
While <b>ptpython</b> provides a superior interactive experience, it is a wrapper around the standard Python interpreter, not a direct replacement. It might incur a slightly larger memory footprint or startup time compared to a bare <b>python</b> shell due to its enhanced graphical features and underlying dependencies. It's optimized for interactive development rather than non-interactive script execution.


title: CONFIGURATION FILE
content:
<b>ptpython</b> is highly customizable through a Python configuration file, typically located at <i>~/.ptpython/config.py</i>. This file is executed as a standard Python script upon startup, allowing users to define intricate settings for key bindings, color schemes, prompt appearance, and startup actions. This flexibility enables a deeply personalized interactive environment.


title: KEY BINDINGS
content:
The shell supports both <i>Emacs</i> and <i>Vi</i> keybindings natively, configurable via command-line options. Beyond these defaults, users can define custom key mappings within the <b>config.py</b> file, enabling complex macros or specific shortcuts tailored to individual workflows. This allows for efficient navigation and editing within the REPL.


title: HISTORY
content:
<b>ptpython</b> was developed by Jonathan Slenders, the creator of <i>prompt_toolkit</i>, a foundational library for building interactive command-line applications. It emerged as a powerful demonstration of <i>prompt_toolkit</i>'s capabilities, aiming to modernize and enhance the default Python REPL experience. Its development focused on addressing long-standing limitations of the standard Python shell, such as rudimentary autocompletion, lack of proper multiline editing, and absence of syntax highlighting, quickly establishing itself as a popular choice in the Python developer community.


title: PARAMETERS
content:
<b><b>-b</b>, <b>--break-at-blanks</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Break lines at blanks, not just non-alphanumeric characters. By default, <b>ptx</b> treats sequences of non-alphanumeric characters as word separators; this option adds blanks to that set.<br><br><b><b>-f</b>, <b>--ignore-case</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Fold lower case to upper case for sorting. This ensures that words like 'Apple' and 'apple' are treated as the same for indexing and sorting purposes.<br><br><b><b>-g</b>, <b>--only-file-name</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show only the file name, not a line number, in the output reference field. This is useful when line numbers are not relevant or too verbose.<br><br><b><b>-i</b>, <b>--ignore-regexp</b>=<i>REGEXP</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ignore words matching the specified basic regular expression <i>REGEXP</i>. Words matching this pattern will not be included in the index.<br><br><b><b>-o</b>, <b>--output</b>=<i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Send output to the specified <i>FILE</i> instead of standard output.<br><br><b><b>-r</b>, <b>--reference</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output the `(reference)` field. This is often a line number or filename, indicating the source of the indexed line.<br><br><b><b>-s</b>, <b>--sentence-regexp</b>=<i>REGEXP</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use <i>REGEXP</i> to find sentence boundaries. This helps <b>ptx</b> determine the extent of context around a word, preventing context from crossing sentence boundaries.<br><br><b><b>-t</b>, <b>--typeset-mode</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate output for <b>nroff</b>/<b>troff</b>. This option formats the output with appropriate characters and spacing for processing by a typesetting system.<br><br><b><b>-w</b>, <b>--width</b>=<i>NUMBER</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the output width to <i>NUMBER</i> columns. The default width is 72 columns.<br><br><b><b>-A</b>, <b>--auto-reference</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output an automatic `(reference)` field for each line. This can be the filename and line number, similar to the `grep` command's output.<br><br><b><b>-G</b>, <b>--traditional</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use traditional style for the permuted index. This might affect how context is defined or how output fields are delimited.<br><br><b><b>-K</b>, <b>--context-regexp</b>=<i>REGEXP</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use <i>REGEXP</i> to find the context. This regular expression defines what constitutes the surrounding text for a keyword.<br><br><b><b>-O</b>, <b>--format</b>=<i>roff</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate output for <b>roff</b> (same as <b>-t</b>, <b>--typeset-mode</b>).<br><br><b><b>-R</b>, <b>--right-context-regexp</b>=<i>REGEXP</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use <i>REGEXP</i> specifically for the right context. This allows finer control over the context extraction.<br><br><b><b>-S</b>, <b>--suffix-regexp</b>=<i>REGEXP</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use <i>REGEXP</i> for suffix matching. This helps define what parts of a word should be considered as a suffix for indexing.<br><br><b><b>-W</b>, <b>--word-regexp</b>=<i>REGEXP</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use <i>REGEXP</i> to define what constitutes a word. By default, words are sequences of alphanumeric characters. This allows custom word definitions.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output version information and exit.<br><br>


title: DESCRIPTION
content:
The <b>ptx</b> command generates a permuted index, also known as a Keyword-in-Context (KWIC) index, of the words found in a given file or standard input. It processes each line, identifies words, and then reorders them so that each word appears in a designated central position, flanked by its surrounding context (left and right).<br><br>This utility is particularly useful for creating indexes for documents, where you can quickly find all occurrences of a particular term along with a snippet of the text where it appears. By default, <b>ptx</b> produces three fields for each entry: the left context, the keyword itself, and the right context, followed by an optional reference (e.g., line number or filename). Various options allow customization of the output width, context parsing, word definition, and case sensitivity.


title: CAVEATS
content:
The default behavior of <b>ptx</b> regarding word definition and context can be complex. Users should carefully review the `--word-regexp`, `--context-regexp`, and `--sentence-regexp` options if the default output does not meet their requirements. Performance on very large files might be a consideration, though for typical indexing tasks, it's generally efficient.


title: INPUT HANDLING
content:
When no <i>FILE</i> arguments are provided, <b>ptx</b> reads from standard input. This allows piping content from other commands directly into <b>ptx</b> for indexing, such as `cat mydocument.txt | ptx`.


title: OUTPUT STRUCTURE
content:
By default, <b>ptx</b> output consists of three fields separated by two spaces: the left context, the keyword (the indexed word), and the right context. An optional fourth field contains the reference (e.g., line number or filename). The specific formatting can be adjusted with options like <b>--width</b> and <b>--typeset-mode</b>.


title: HISTORY
content:
<b>ptx</b> is part of the GNU Core Utilities, a collection of essential command-line tools for Unix-like operating systems. While the concept of permuted indexing dates back decades (e.g., in bibliometrics and information retrieval), <b>ptx</b> provides a modern, robust implementation for general text processing on Linux. Its development is integrated into the larger GNU project, ensuring consistency and adherence to GNU standards.


title: SYNOPSIS
content:
<b>pueue</b> [<i>GLOBAL_OPTIONS</i>] <i>&lt;SUBCOMMAND&gt;</i> [<i>SUBCOMMAND_OPTIONS</i>] [<i>ARGUMENTS</i>]<br><br>Common Subcommands:<br>&nbsp;&nbsp;<b>pueue add</b> [<i>OPTIONS</i>] <i>&lt;COMMAND&gt;</i><br>&nbsp;&nbsp;<b>pueue status</b> [<i>OPTIONS</i>]<br>&nbsp;&nbsp;<b>pueue start</b> [<i>OPTIONS</i>] [<i>&lt;TASK_ID&gt;</i>]<br>&nbsp;&nbsp;<b>pueue stop</b> [<i>OPTIONS</i>] [<i>&lt;TASK_ID&gt;</i>]<br>&nbsp;&nbsp;<b>pueue logs</b> [<i>OPTIONS</i>] [<i>&lt;TASK_ID&gt;</i>]<br>&nbsp;&nbsp;<b>pueue remove</b> [<i>OPTIONS</i>] [<i>&lt;TASK_ID&gt;</i>]<br>&nbsp;&nbsp;<b>pueue reset</b> [<i>OPTIONS</i>]


title: PARAMETERS
content:
<b>--help, -h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Display help message for Pueue or a specific subcommand.</I><br><br><b>--version, -V</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Print Pueue version information.</I><br><br><b>--daemon, -d</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Starts the Pueue daemon in the background.</I> This command is typically run once to initialize the Pueue service, allowing it to manage tasks persistently.<br><br><b>--config &lt;PATH&gt;, -c &lt;PATH&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specify a custom path to the Pueue configuration file.</I> Useful for managing multiple Pueue instances or custom setups.<br><br><b>--path &lt;PATH&gt;, -P &lt;PATH&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Set a custom daemon directory path.</I> Overrides the default Pueue data directory where tasks and logs are stored.<br><br><b>--host &lt;HOST&gt;, -H &lt;HOST&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specify the Pueue daemon host address.</I> Allows the client to connect to a daemon running on a different network interface or machine.<br><br><b>--log-level &lt;LEVEL&gt;, -L &lt;LEVEL&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Set the log level for Pueue messages.</I> Common levels include <code>error</code>, <code>warn</code>, <code>info</code>, <code>debug</code>, <code>trace</code>.<br><br><b>--kill-client, -k</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Kills any running Pueue client process.</I> Primarily for development or troubleshooting, not typically used in daily operations.<br><br>


title: DESCRIPTION
content:
<b>pueue</b> is a sophisticated command-line utility designed to manage and execute tasks in the background. Unlike simple shell job control (<code>&amp;</code>, <code>bg</code>, <code>fg</code>) or <code>nohup</code>, Pueue employs a client-server architecture, where a persistent daemon manages a queue of commands. This allows tasks to continue running even after the terminal session is closed or a system reboot (provided the daemon is restarted). It provides robust features for queuing commands, running them sequentially or in parallel, grouping tasks, and viewing their status and logs. Pueue is ideal for long-running processes like compilations, data processing scripts, or continuous integration tasks, offering a reliable way to orchestrate background operations with ease and visibility. It simplifies the process of managing multiple background jobs, providing control over their execution order, concurrency, and output.


title: CAVEATS
content:
<b>Pueue</b> operates on a client-server model, requiring a daemon process to be running for any commands to function. If the daemon is not active, Pueue commands will fail to connect. Users must ensure the daemon is started, often with <code>pueue --daemon</code>. Task output, especially for long-running processes, needs to be handled carefully; direct terminal output is not automatically streamed to the client and should be redirected to files within the command definition (e.g., <code>my_script.sh &gt; output.log 2&gt;&amp;1</code>) if persistent logging is desired. While Pueue provides persistence, tasks are only re-queued upon daemon restart if they were in a pending or running state; completed tasks are not automatically re-run.


title: SUBCOMMANDS
content:
<b>Pueue</b> is primarily driven by its extensive set of subcommands, each dedicated to a specific aspect of task management. Key subcommands include:<br><i><b>add</b></i>: Adds a new command to the queue.<br><i><b>status</b></i>: Displays the current state of the queue, including running, queued, and finished tasks.<br><i><b>start</b></i>: Starts the next pending task or a specific task by ID.<br><i><b>stop</b></i>: Pauses the execution of the queue or a specific running task.<br><i><b>logs</b></i>: Shows the stdout/stderr output of a specific task.<br><i><b>remove</b></i>: Deletes tasks from the queue.<br><i><b>reset</b></i>: Clears all tasks from the queue and resets Pueue's state.<br><i><b>parallel</b></i> / <i><b>sequential</b></i>: Changes the execution mode of a task group.<br><i><b>group</b></i>: Manages task groups, allowing for concurrent execution of multiple groups while tasks within a group run sequentially or in parallel.<br>Each subcommand often has its own set of options for fine-grained control.


title: CLIENT-SERVER ARCHITECTURE
content:
<b>Pueue</b> functions through a client-server model. The <I>Pueue daemon</I> (server) runs continuously in the background, managing the task queue, executing commands, and storing their state and output. The <I>Pueue client</I> (the <code>pueue</code> command you run in your terminal) communicates with this daemon to add, manage, or query tasks. This design ensures that tasks persist and continue running even if the client terminal is closed, crashes, or the user logs out. The daemon's state, including the task queue, is saved to disk, providing robustness against system restarts.


title: TASK PERSISTENCE AND OUTPUT
content:
A core feature of <b>Pueue</b> is its ability to persist tasks across sessions and even system reboots. Once a task is added to the queue, its status and output (if not redirected by the command itself) are maintained by the Pueue daemon. The output of executed tasks is stored by the daemon and can be reviewed at any time using the <code>pueue logs</code> command. Users should be aware that Pueue captures stdout and stderr internally; for complex logging or long-term storage, it's often best practice to explicitly redirect command output to a file when adding a task (e.g., <code>pueue add "my_script.sh &gt; /var/log/my_script.log 2&gt;&amp;1"</code>).


title: HISTORY
content:
<b>Pueue</b> was developed by <I>Arne Beer</I> as a personal solution to better manage long-running background tasks. Frustrated by the limitations of existing tools like <code>nohup</code> or complex <code>screen</code>/<code>tmux</code> sessions for simple background execution, Beer created Pueue to offer a more structured and persistent queuing system. The project, written in <I>Rust</I>, emphasizes reliability, performance, and a user-friendly command-line interface. It has evolved to include sophisticated features like task grouping, parallel execution, and configurable daemon behavior, establishing itself as a robust tool for managing background processes in development and system administration contexts.


title: SEE ALSO
content:
<b>at</b>(1), <b>cron</b>(8), <b>nohup</b>(1), <b>screen</b>(1), <b>tmux</b>(1), <b>jobs</b>(1) (shell builtin), <b>bg</b> (shell builtin), <b>fg</b> (shell builtin)


title: PARAMETERS
content:
<b>--group <group_name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assigns the task to a specific group. Groups can be paused, started, or configured for parallel execution limits independently.<br><br><b>--after <task_id></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds the task to the queue immediately after the specified task ID has finished (successfully or not).<br><br><b>--before <task_id></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds the task to the queue immediately before the specified task ID.<br><br><b>--delay <duration></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Delays the execution of the task by a specified duration (e.g., <i>10m</i>, <i>1h</i>, <i>1d</i>).<br><br><b>--at <datetime></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Schedules the task to be executed at a specific date and time (e.g., <i>2023-10-27 15:30</i>, <i>tomorrow 08:00</i>).<br><br><b>--priority <integer></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assigns a numerical priority to the task. Tasks with higher priority values are executed sooner.<br><br><b>--depends-on <task_id></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Makes the current task dependent on the successful completion of another task with the given ID.<br><br><b>--path <directory>, --working-directory <directory></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the working directory for the command's execution.<br><br><b>--env <KEY=VALUE></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds or overrides an environment variable for the command's execution. Can be specified multiple times.<br><br><b>--stdout <file>, --stderr <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Redirects the command's standard output or standard error to a specified file.<br><br><b>--start-immediately, --queue-immediately</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs Pueue to start the task immediately upon addition, bypassing the queue's regular processing order.<br><br><b>--name <name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assigns a human-readable name to the task, useful for easier identification.<br><br><b>--print-task-id</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the unique task ID of the newly added task to standard output.<br><br><b>--replace <task_id></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Replaces an existing task with the specified ID with the newly added task. The existing task must not be running.<br><br><b>--no-dependencies</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents Pueue from automatically loading and applying dependencies defined in a <i>pueue.yml</i> file in the current directory.<br><br><b><command></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The shell command to be executed by Pueue.<br><br><b>[arguments...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Any arguments to be passed to the shell command.<br><br>


title: DESCRIPTION
content:
The <b>pueue-add</b> is a subcommand of the <b>pueue</b> task queue manager. Pueue itself is a lightweight, command-line utility designed to queue and manage shell commands. It allows users to run commands in the background, sequentially or in parallel, ensuring that system resources are managed efficiently.<br><br>The <b>pueue-add</b> command is used to add a new command to the Pueue queue. When a command is added, Pueue assigns it a unique ID, records its execution details (like working directory, environment variables, output logs), and schedules it for execution according to its priority, group, or dependencies. This enables users to launch long-running tasks without blocking their terminal, recover output logs, and manage task lifecycles effectively. It's particularly useful for development workflows, CI/CD-like local setups, or any scenario where a series of commands needs to be executed reliably in the background.


title: CAVEATS
content:
Pueue operates as a client-server application. For <b>pueue-add</b> to function, the Pueue daemon (server) must be running in the background.<br>Commands added via <b>pueue-add</b> are executed in a non-interactive shell environment. Ensure that necessary environment variables (like <i>PATH</i>) are explicitly set or sourced if critical for command execution.<br>Task IDs are unique only for the current Pueue session and can be reused after a full restart or if tasks are removed and new ones are added, so relying on long-term fixed IDs is not advisable.


title: TASK IDENTIFICATION
content:
Each command added with <b>pueue-add</b> receives a unique integer task ID. This ID is crucial for interacting with the task later using other <b>pueue</b> commands (e.g., <b>pueue status <id></b>, <b>pueue log <id></b>, <b>pueue remove <id></b>).


title: CLIENT-SERVER ARCHITECTURE
content:
Pueue consists of a client (the <b>pueue</b> command itself) and a daemon (server). When you run <b>pueue add</b>, the client sends the task details to the daemon, which then manages the execution and state of the task.


title: HISTORY
content:
Pueue emerged as a modern, user-friendly task queue solution for Linux and macOS, offering a more intuitive and flexible alternative to traditional batch systems like <i>cron</i> or <i>at</i> for personal background job management. It focuses on simplicity, clear status reporting, and robust task management from the command line, gaining popularity among developers for managing local build processes, tests, and long-running scripts.


title: SEE ALSO
content:
pueue(1), pueue status(1), pueue start(1), pueue stop(1), pueue remove(1), pueue log(1), pueue edit(1)


title: PARAMETERS
content:
<b>TASK_IDS...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional. One or more space-separated numeric IDs of tasks to remove. If provided, only these specific tasks will be removed from the queue, regardless of their status. If no IDs are specified, <b><code>pueue clean</code></b> will remove all tasks that are in a finished state (e.g., <i>Done</i>, <i>Failed</i>, <i>Killed</i>).<br><br>


title: DESCRIPTION
content:
The <i>pueue-clean</i> command, invoked as <b><code>pueue clean</code></b>, serves as a crucial utility for managing the task queue within Pueue, a command-line task queue runner. Its primary function is to remove tasks that have completed their execution, whether successfully, with failure, or by being killed.<br><br>This process helps to declutter the Pueue client's display and ensure that only active, pending, or paused tasks remain visible. Without regular cleaning, the task list can grow indefinitely, making it difficult to track currently running or waiting jobs. By default, <b><code>pueue clean</code></b> removes all tasks that are no longer in a <i>Running</i>, <i>Stalled</i>, <i>Paused</i>, or <i>Waiting</i> state. This includes tasks that have completed (<i>Done</i>, <i>Success</i>), failed (<i>Failed</i>), or were manually terminated (<i>Killed</i>). Optionally, specific task IDs can be provided to remove only those particular tasks, regardless of their current status, making it functionally similar to the <b><code>pueue rm</code></b> command in such cases.


title: CAVEATS
content:
When <b><code>pueue clean</code></b> is invoked without any <i>TASK_IDS</i>, it only removes tasks that have reached a final, non-active state (like <i>Done</i>, <i>Failed</i>, <i>Success</i>, <i>Killed</i>). It will <i>not</i> remove tasks that are currently <i>Running</i>, <i>Stalled</i>, <i>Paused</i>, or <i>Waiting</i>.<br><br>However, if specific <i>TASK_IDS</i> are supplied, the command will remove those tasks irrespective of their current status, effectively behaving like <b><code>pueue rm</code></b>. Users should be mindful of this dual behavior to avoid unintentionally removing active tasks when specifying IDs.


title: TASK STATES FOR CLEANING
content:
The <b><code>pueue clean</code></b> command specifically targets tasks in the following final states when no <i>TASK_IDS</i> are provided:<br><br><b>Done/Success:</b> The task completed successfully.<br><b>Failed:</b> The task exited with a non-zero status code.<br><b>Killed:</b> The task was manually terminated by the user.<br><br>Tasks in active or pending states such as <i>Running</i>, <i>Stalled</i>, <i>Paused</i>, or <i>Waiting</i> are never removed by a default <b><code>pueue clean</code></b> operation, ensuring critical ongoing processes are not interrupted.


title: HISTORY
content:
Pueue emerged as a modern, user-friendly alternative to complex background job managers, focusing on simplicity and ease of use for developers and system administrators needing to queue commands from their terminal. The <b><code>pueue clean</code></b> subcommand has been an integral part of Pueue since its early versions, addressing the common need to maintain a tidy queue history.<br><br>As Pueue evolved with features like parallel execution, dependency management, and various task states, the <b><code>clean</code></b> command remained consistent in its core purpose: decluttering the interface by removing completed jobs, thus enhancing the user experience and clarity of the task list.


title: PARAMETERS
content:
<b><b>--help</b>, <b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints help information for the command and exits.<br><br><b><b>--output</b>, <b>-o</b> <I>directory</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an output directory where the completion file will be saved. If this option is omitted, the completion script will be printed to standard output.<br><br><b><b>--version</b>, <b>-V</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the version information of the <i><b>pueue-completions</b></i> utility and exits.<br><br><b><I>SHELL</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The specific shell for which to generate completion scripts. Accepted values include: <b>bash</b>, <b>elvish</b>, <b>fish</b>, <b>powershell</b>, and <b>zsh</b>.<br><br>


title: DESCRIPTION
content:
<i><b>pueue-completions</b></i> is a specialized utility provided by the Pueue task manager, designed to enhance the command-line experience. Its core function is to generate shell completion scripts that provide auto-completion suggestions for <i>Pueue</i> commands, subcommands, and arguments. This feature significantly boosts user efficiency and reduces typing errors when interacting with <i>Pueue</i> from the terminal. The command supports generating completions for various popular shells, including <b>Bash</b>, <b>Zsh</b>, <b>Fish</b>, <b>Elvish</b>, and <b>PowerShell</b>. Users can choose to print the completion script directly to standard output for immediate use or specify an output directory to save the script to a file, facilitating integration into their shell's configuration. Implementing these completions typically involves sourcing the generated script within the shell's respective configuration file (e.g., <i>.bashrc</i>, <i>.zshrc</i>).


title: CAVEATS
content:
<ul><li><b>Manual Sourcing Required</b>: The generated completion script is not automatically active. It needs to be explicitly sourced in your shell's configuration file (e.g., <i>~/.bashrc</i>, <i>~/.zshrc</i>) or placed in a directory loaded by your shell for completions.</li><li><b>Shell-Specific Setup</b>: The exact steps for installing and enabling completion scripts can vary slightly between different shells. Users should consult their shell's documentation for the recommended approach.</li><li><b>Pueue Dependency</b>: This command is part of the <i>Pueue</i> project and requires <i>Pueue</i> to be installed on the system to function.</li></ul>


title: INSTALLATION & USAGE EXAMPLES
content:
To enable shell completions for <b>Bash</b>, you can generate the script and source it in your <i>.bashrc</i> or a file within a completion directory, for example:<br><code><b>pueue-completions bash > ~/.config/bash_completion.d/pueue.bash</b></code><br>Then, add <code><b>source ~/.config/bash_completion.d/pueue.bash</b></code> to your <i>~/.bashrc</i>.<br><br>For <b>Zsh</b>, you typically place the generated script in one of your <code>$fpath</code> directories:<br><code><b>pueue-completions zsh > /usr/local/share/zsh/site-functions/_pueue</b></code><br>Ensure that <i>/usr/local/share/zsh/site-functions</i> (or your chosen directory) is part of your <code>$fpath</code> environment variable.<br><br>If no output directory is specified (by omitting the <b>-o</b> option), the script is printed to standard output, allowing for direct piping to a file or immediate evaluation using <code>eval</code>.


title: HISTORY
content:
<i>Pueue</i>, including its <i><b>pueue-completions</b></i> utility, is an open-source project primarily developed in Rust. The inclusion of a dedicated completions generator reflects a modern command-line interface (CLI) design philosophy that prioritizes user convenience. This utility has been a standard part of the <i>Pueue</i> project, continuously developed to provide robust auto-completion features across various popular shells, thereby improving the overall user experience for the <i>Pueue</i> task runner.


title: PARAMETERS
content:
<b>TASK_ID | TASK_INDEX...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br><i>Required.</i> Specifies one or more tasks to be edited. Tasks can be identified by their unique integer ID or by their current numerical index within the queue (0-based). Multiple task identifiers can be provided, separated by spaces.<br><br><b>--path &lt;PATH&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Allows modification of the working directory for the specified task. The edited task will execute as if it was started from this new path.<br><br><b>--stashed</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>After the editing process is complete, the task will be automatically moved into a 'stashed' state. Stashed tasks do not automatically run until explicitly <I>start</I>ed.<br><br><b>--group &lt;GROUP&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Specifies the group to which the task belongs. This is particularly useful when tasks with the same index exist in different groups, ensuring the correct task is edited.<br><br>


title: DESCRIPTION
content:
<b>pueue-edit</b> is a subcommand of the <I>Pueue</I> task queue manager, providing a convenient way to modify the command or properties of an existing task within the Pueue queue. When invoked, it opens the specified task's command string in your default text editor (determined by the <I>EDITOR</I> or <I>VISUAL</I> environment variables). After saving and closing the editor, Pueue updates the task's command in the queue. This is particularly useful for correcting typos, adjusting arguments, or changing a task's behavior without needing to re-add it entirely or affecting its current state (if not running). It supports editing tasks by their index or unique ID.


title: CAVEATS
content:
<ul><li>The <b>pueue-edit</b> command relies on the <I>EDITOR</I> or <I>VISUAL</I> environment variables to determine which text editor to use. If neither is set, it might default to <I>vi</I> or fail to open an editor, leading to an error.</li><li>Editing a currently <b>running</b> or <b>paused</b> task will only apply the changes when the task is restarted or next executed. For single-shot tasks, the change will apply on its next run if it's re-queued.</li><li>Changes made via <b>pueue-edit</b> only affect the task's command and properties for future executions. It does not re-run a task that has already completed or failed.</li></ul>


title: EDITOR CONFIGURATION
content:
For a seamless editing experience, users should ensure that their <I>EDITOR</I> or <I>VISUAL</I> environment variable is set to their preferred text editor (e.g., <br><code>export EDITOR=nvim</code><br> or <br><code>export EDITOR=nano</code>). This ensures that <I>pueue-edit</I> launches the desired editor when modifying task commands.


title: TASK IDENTIFICATION
content:
Tasks can be identified either by their unique system-assigned ID or by their current numerical index. The index is relative to the current output of <I>pueue status</I> for a specific group. Using the unique ID is generally more robust, especially if the queue order changes frequently.


title: HISTORY
content:
Pueue itself is a relatively modern and actively developed command-line task queue manager, designed for simplicity and ease of use in terminal environments. <I>pueue-edit</I> is a core component that was introduced early in Pueue's development, reflecting the common user need to modify existing tasks without needing to entirely re-create them. Its functionality has remained central to Pueue's interactive task management capabilities, evolving alongside other features to provide a robust and user-friendly experience.


title: PARAMETERS
content:
<b><b>-g, --group</b> <i>&lt;GROUP&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assigns the new task to a specific group. Tasks in different groups can be run independently or with different concurrency settings.<br><br><b><b>-p, --path</b> <i>&lt;PATH&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the working directory for the task. The command will be executed from this path.<br><br><b><b>-s, --start-immediately</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts the task immediately upon addition, bypassing the normal queue order, if a slot is available.<br><br><b><b>-w, --wait</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Blocks the command-line until the enqueued task finishes its execution.<br><br><b><b>-d, --depends-on</b> <i>&lt;ID&gt;...</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies one or more task IDs that this new task depends on. The task will only start once all its dependencies have successfully completed.<br><br><b><b>-l, --label</b> <i>&lt;LABEL&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assigns a custom label to the task for easier identification and management.<br><br><b><b>-C, --clear-dependencies</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes any existing dependencies on previous tasks when re-adding an existing command.<br><br><b><b>-P, --priority</b> <i>&lt;PRIORITY&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the execution priority of the task. Higher priority tasks are executed before lower priority ones within the same group.<br><br><b><b>-N, --no-queue-optimization</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables certain queue optimizations, ensuring the task is strictly added to the end of the queue.<br><br><b><b>-T, --no-shell</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes the command directly without invoking a shell. This can be useful for commands that don't require shell features like globbing or pipes.<br><br><b><b>-B, --bulk</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads commands from standard input, adding each line as a separate task to the queue.<br><br><b><b>-k, --key</b> <i>&lt;KEY&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assigns a unique key to the task. This can be used to prevent duplicate tasks or to manage specific tasks more easily.<br><br><b><b>-f, --force-path</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the creation of the working directory if it does not exist.<br><br>


title: DESCRIPTION
content:
<i>pueue-enqueue</i> is a command-line utility used to submit new tasks to the Pueue daemon's queue. Pueue is a lightweight and user-friendly task queue and job management system designed for running long-running commands, scripts, or programs in the background. It allows users to define a series of commands that will be executed sequentially or concurrently, providing features like task grouping, dependencies, priority management, and output logging.<br><br>When a command is enqueued using <i>pueue-enqueue</i>, it is added to a persistent queue managed by the Pueue daemon. The daemon then picks up tasks from this queue and executes them, ensuring that they run even if the user logs out. This is particularly useful for automation, managing multiple build processes, running data analysis jobs, or any task that requires background execution without tying up a terminal.<br><br>The command allows for flexible task definition, including specifying the working directory, assigning tasks to specific groups, setting execution priorities, and defining dependencies on other tasks, enabling complex workflow orchestration.


title: CAVEATS
content:
Using <i>pueue-enqueue</i> requires the Pueue daemon to be running in the background. If the daemon is not active, the command will fail. Task output is typically redirected and can be viewed using <b>pueue logs</b>. Be mindful of circular dependencies when defining task dependencies, as this can lead to deadlocks. Resource management and parallel execution limits are configured via the Pueue daemon's configuration, not directly through this enqueue command.


title: TASK EXECUTION MODEL
content:
When a task is enqueued, Pueue takes control of its execution. This includes managing its environment variables, working directory, and standard input/output streams. By default, standard output and standard error are captured by Pueue and can be reviewed later using commands like <b>pueue logs</b>. Commands are typically run within a shell (e.g., <i>bash</i> or <i>sh</i>) unless the <b>--no-shell</b> option is used, allowing for shell features like pipes, redirections, and command chaining.


title: INTEGRATION WITH SHELL
content:
<i>pueue-enqueue</i> (or <b>pueue add</b>) is designed to be easily integrated into shell scripts and workflows. It allows for the automation of complex sequences of commands, turning a series of sequential script executions into managed background tasks. This is particularly useful in CI/CD pipelines, data processing pipelines, or personal automation scripts where reliable background execution and output capture are critical.


title: HISTORY
content:
The Pueue project, started by Nsja, aims to provide a simple yet powerful command-line task queue. Historically, <i>pueue-enqueue</i> (or sometimes just <i>enqueue</i> as a subcommand) was a direct way to add tasks. In later versions of Pueue (specifically from version 1.0 onwards), the command for adding tasks was standardized under <b>pueue add</b>. Therefore, while <i>pueue-enqueue</i> might refer to older installations or specific aliases/wrappers, its functionality is directly equivalent to the modern <b>pueue add</b> command, which has become the primary and recommended way to enqueue tasks.


title: SEE ALSO
content:
pueue(1), pueue-status(1), pueue-logs(1), pueue-start(1), pueue-stop(1), pueue-kill(1), at(1), batch(1), cron(8), nohup(1), screen(1), tmux(1)


title: PARAMETERS
content:
<b><b>-g</b>, <b>--group</b> <i>&lt;GROUP&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Follows the output of tasks belonging to the specified <i>group</i>. This is useful for monitoring a subset of tasks related to a particular project or workflow.<br><br><b><b>-a</b>, <b>--all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Follows the output of all currently active and pending tasks in the <b>Pueue</b> queue. This can provide a comprehensive overview of all ongoing processes.<br><br><b><b>-s</b>, <b>--show-task-id</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prepends each line of output with the corresponding <i>task ID</i>. This option is particularly useful when following multiple tasks simultaneously, helping to distinguish their outputs.<br><br><b><b>-W</b>, <b>--wait</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Default behavior</i>) Continuously streams the task output until the task completes, fails, or is stopped. This ensures you see the entire execution lifecycle.<br><br><b><b>--no-wait</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the current captured output of the specified tasks and then exits immediately, without waiting for the tasks to complete. Useful for quick checks.<br><br><b><b>--no-log-timestamps</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses the display of timestamps that are normally prepended to each line of log output by the <b>Pueue</b> daemon. Provides cleaner raw output.<br><br><b><b>--full-task-output</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the complete captured output for the task(s), rather than a truncated view that might be applied by default for very long logs.<br><br>


title: DESCRIPTION
content:
The <b>pueue follow</b> command allows users to monitor the standard output (<i>stdout</i>) and standard error (<i>stderr</i>) of tasks managed by the <b>Pueue</b> task manager in real-time. This command is invaluable for tracking the progress of long-running jobs, debugging scripts, or simply observing the live output of a task as it executes.<br><br>Unlike <b>pueue log</b>, which displays the full historical output of completed tasks, <b>pueue follow</b> provides a live stream of the output from active or recently completed tasks. By default, if no task IDs are specified, it will follow the most recently added task. Users can specify one or more task IDs or use options to follow tasks within a specific group or even all active tasks. It connects to the running <b>Pueue</b> daemon to fetch and display the captured output, offering immediate feedback on task execution.


title: CAVEATS
content:
The <b>pueue follow</b> command requires the <b>Pueue</b> daemon to be running and accessible, as it retrieves output directly from the daemon's internal logging mechanism. If the daemon is not running or the connection fails, the command will not be able to retrieve task output.<br><br>Following many active tasks with high output rates can consume significant terminal resources and may lead to performance issues if the output is extremely verbose. The displayed output is only what <b>Pueue</b> itself has captured, so any external logging or unbuffered output might not be immediately visible.


title: INTERACTIVE MONITORING
content:
This command is the primary tool for interactive monitoring of ongoing jobs. It keeps the terminal focused on the task's progress, allowing for immediate observation of errors or completion messages without needing to constantly re-run <b>pueue status</b> or manually check log files.


title: TASK IDENTIFICATION
content:
When no <i>TASK_ID</i> is provided, <b>pueue follow</b> defaults to observing the latest task. Providing specific <i>TASK_ID</i>s allows for precise monitoring of particular tasks, while using <b>--group</b> helps to manage monitoring within logical task subsets.


title: HISTORY
content:
The <b>Pueue</b> project, initiated by NicoHood, aimed to create a user-friendly and robust command-line task queue manager. The <b>pueue follow</b> command was an integral part of its design from early stages, recognized as crucial for providing real-time operational feedback to users. Its development has mirrored that of the main <b>Pueue</b> application, adapting to new features like task grouping and improved output handling, ensuring that users can always effectively monitor their background tasks.


title: PARAMETERS
content:
<b><b>add</b> <i>NAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a new task group with the specified <i>NAME</i>.<br><br><b><b>remove</b> <i>NAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes the task group with the specified <i>NAME</i>. This will move any remaining tasks in that group to the default group.<br><br><b><b>list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all existing task groups, their current states (e.g., running, paused), and configuration (e.g., parallel limit).<br><br><b><b>switch</b> <i>NAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the default group for new tasks added via <i>pueue add</i> to the specified <i>NAME</i>. Subsequent <i>pueue add</i> commands will place tasks into this group unless a specific group is specified with <i>--group</i>.<br><br><b><b>pause</b> [<i>NAME</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pauses the specified group <i>NAME</i>. If no <i>NAME</i> is provided, it pauses the default group. Paused groups will not execute any tasks until resumed.<br><br><b><b>resume</b> [<i>NAME</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Resumes the specified group <i>NAME</i>. If no <i>NAME</i> is provided, it resumes the default group. Tasks in resumed groups will begin execution according to their configuration.<br><br><b><b>set</b> <i>NAME</i> <b>--parallel</b> <i>COUNT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum number of tasks that can run concurrently within the specified group <i>NAME</i> to <i>COUNT</i>. For example, <i>--parallel 2</i> allows two tasks to run simultaneously.<br><br><b><b>set</b> <i>NAME</i> <b>--sequential</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Configures the specified group <i>NAME</i> to run tasks sequentially, one after another. This is equivalent to <i>--parallel 1</i>.<br><br><b><b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with <b>remove</b>, forces the removal of a group even if it contains tasks. These tasks will be moved to the default group.<br><br>


title: DESCRIPTION
content:
<i>pueue-group</i> is a subcommand of the Pueue task queue manager, specifically designed for organizing and controlling collections of tasks. It allows users to define, list, and modify execution properties for different task groups. This is particularly useful for separating diverse workloads, prioritizing specific sets of tasks, or controlling the parallel execution of commands within isolated contexts.<br><br>By creating groups, users can add tasks to a specific group, pause or resume entire sets of operations, and configure the concurrency level (e.g., how many tasks can run in parallel) for each group independently. This enhances the flexibility and power of Pueue, enabling more sophisticated task management beyond a single, global queue.


title: CAVEATS
content:
When a group is removed, any tasks remaining in that group are automatically moved to the default group. Be mindful that configuring a group as 'sequential' or with a low 'parallel' count can significantly impact the overall throughput of your queued tasks if many are assigned to that group.


title: DEFAULT GROUP
content:
Upon installation, Pueue automatically creates a 'default' group. Any tasks added without explicitly specifying a group (e.g., <i>pueue add ls</i>) are placed into this default group. The <i>pueue group switch</i> command changes which group acts as the 'default' for new tasks.


title: ADDING TASKS TO GROUPS
content:
Tasks can be explicitly assigned to a specific group using the <i>--group</i> option with the <i>pueue add</i> command (e.g., <i>pueue add --group my_build_tasks 'make all'</i>). This overrides the currently active default group.


title: HISTORY
content:
Pueue, initially released in 2018, rapidly evolved as a lightweight command-line task queue. The concept of task groups was introduced in later versions to address the growing need for more granular control over task execution and organization. This feature significantly enhanced Pueue's utility, moving it beyond a simple FIFO queue to a more sophisticated job scheduler capable of handling diverse workloads with distinct execution policies.


title: SYNOPSIS
content:
<b>pueue help</b> [<i>SUBCOMMAND</i>]<br><b>pueue --help</b><br><b>pueue</b> [<i>GLOBAL_OPTIONS</i>] <i>SUBCOMMAND</i> <b>--help</b>


title: PARAMETERS
content:
<b><I>SUBCOMMAND</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An optional Pueue subcommand (e.g., <b>add</b>, <b>status</b>) for which to display detailed help information. If omitted, general Pueue usage and a list of all subcommands are shown.<br><br>


title: DESCRIPTION
content:
The <b>pueue-help</b> command, commonly invoked as <b>pueue help</b> or <b>pueue --help</b> within the Pueue ecosystem, provides comprehensive assistance for using the Pueue task queue manager. It outlines the main <b>pueue</b> command structure, available global options, and a list of all subcommands with brief descriptions. Users can invoke it to understand how to add, remove, pause, resume, or manage tasks within their Pueue queue. The output serves as a quick reference, detailing the syntax for various operations and guiding users on how to access more specific help for individual subcommands (e.g., <b>pueue help add</b>). It ensures users can efficiently navigate Pueue's features and troubleshoot common usage questions without external documentation.


title: CAVEATS
content:
The <b>pueue-help</b> command itself is not a standard standalone executable; instead, help for Pueue is typically accessed via the `<b>pueue help</b>` subcommand or `<b>pueue --help</b>` flags. The `--daemonless` mode disconnects from the shared queue, making task management operations apply only to an isolated local context.


title: GLOBAL OPTIONS
content:
These options can be applied to the `<b>pueue</b>` command before any subcommand to affect its overall behavior, including when requesting help.<br><ul><li>`<b>-h</b>, <b>--help</b>`: Print help information for the current command or subcommand.</li><li>`<b>-V</b>, <b>--version</b>`: Print Pueue version information.</li><li>`<b>-d</b>, <b>--daemonless</b>`: Run Pueue in daemonless mode. No shared task queue is used.</li><li>`<b>-c</b> <I>CONFIG</I>, <b>--config</b> <I>CONFIG</I>`: Path to a specific Pueue configuration file.</li><li>`<b>-p</b> <I>PROFILE</I>, <b>--profile</b> <I>PROFILE</I>`: The name of the profile that should be loaded from the config.</li></ul>


title: AVAILABLE SUBCOMMANDS
content:
The `<b>pueue help</b>` command provides information on the following subcommands, which perform various task queue management operations.<br><ul><li>`<b>add</b>`: Add a new command to the queue.</li><li>`<b>clean</b>`: Clean the daemon's log files.</li><li>`<b>config</b>`: Initialize or edit the config file.</li><li>`<b>edit</b>`: Edit a task's command in the queue.</li><li>`<b>enqueue</b>`: (Deprecated) Enqueue a task (use `<b>add</b>` instead).</li><li>`<b>follow</b>`: Follow the output of a specific task in real-time.</li><li>`<b>group</b>`: Add, remove, or switch task groups.</li><li>`<b>log</b>`: Display the full log output of a specific task.</li><li>`<b>pause</b>`: Pause the daemon or specific tasks in the queue.</li><li>`<b>remove</b>`: Remove a task from the queue.</li><li>`<b>restart</b>`: Restart a finished or failed task.</li><li>`<b>resume</b>`: Resume the daemon or specific tasks.</li><li>`<b>status</b>`: Show the current status of the Pueue queue and its tasks.</li><li>`<b>switch</b>`: Switch the position of two tasks in the queue.</li><li>`<b>wait</b>`: Wait for a task to finish execution.</li></ul>


title: HISTORY
content:
Pueue is a relatively modern task queue runner written in Rust, designed to offer a simpler and more intuitive interface for managing background tasks compared to traditional methods like `nohup`, `screen`, or `tmux` for simple queueing needs. Its development emphasizes user-friendliness, cross-platform compatibility, and robust error handling. The `help` functionality is integral to its design, allowing users to quickly learn and utilize its features directly from the terminal, following a common `git`-like subcommand structure.


title: PARAMETERS
content:
<b>--all, -a</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Kills all <b>running</b> or <b>paused</b> tasks managed by Pueue.<br><br><b>--group <name>, -g <name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Kills all <b>running</b> or <b>paused</b> tasks within the specified group <i><name></i>.<br><br><b>--signal <SIG>, -s <SIG></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the signal to send. Can be a signal name (e.g., <i>SIGTERM</i>, <i>SIGKILL</i>) or a signal number. Default is <i>SIGTERM</i>.<br><br><b>--daemon <name>, -d <name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the Pueue daemon to connect to. Useful when running multiple daemons.<br><br><b>--config <path>, -c <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the <i>pueue</i> configuration file.<br><br><b>--log-level <level></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the logging level for the command's output (e.g., <i>error</i>, <i>info</i>, <i>debug</i>).<br><br>


title: DESCRIPTION
content:
<i>pueue-kill</i> is a command-line utility used to terminate tasks managed by the <i>pueue</i> task queue daemon. It allows users to stop currently <b>running</b> or <b>paused</b> tasks by sending a termination signal. By default, it sends <b>SIGTERM</b>, providing tasks an opportunity to shut down gracefully. Users can specify a different signal, such as <b>SIGKILL</b>, for immediate termination, though this should be used with caution as it prevents graceful shutdown.<br><br>Tasks can be targeted by their unique <b>index</b>, their <b>name</b>, or by specifying options to kill all tasks (<b>--all</b>), tasks within a particular group (<b>--group</b>), or tasks managed by a specific <i>pueue</i> daemon (<b>--daemon</b>). This command is essential for managing and responding to misbehaving or no longer needed tasks in the <i>pueue</i> environment. It's often invoked as a subcommand, <b>pueue kill</b>.


title: CAVEATS
content:
Using <b>SIGKILL</b> (<i>-s SIGKILL</i>) forcefully terminates tasks without allowing them to perform cleanup, which can lead to data corruption or resource leaks. Use with caution.<br><br>Tasks that are already <i>done</i>, <i>failed</i>, or <i>aborted</i> cannot be killed; only <b>running</b> or <b>paused</b> tasks are affected.


title: SIGNAL HANDLING
content:
<i>pueue-kill</i> wraps the underlying system's process signaling. Understanding different signals (e.g., <b>SIGTERM</b> for graceful shutdown, <b>SIGKILL</b> for immediate termination) is crucial for effective task management.


title: AFFECTED TASK STATES
content:
Only tasks in the <b>running</b> or <b>paused</b> state can be targeted by <i>pueue-kill</i>. Tasks in other states (e.g., <i>queued</i>, <i>done</i>, <i>failed</i>) are not affected and will be ignored.


title: HISTORY
content:
<i>pueue</i> is a modern task queue manager written in Rust. <i>pueue-kill</i> is an integral part of its command suite, designed to provide robust control over queued processes. It leverages standard Unix signaling mechanisms to interact with child processes launched by the <i>pueue</i> daemon, ensuring efficient task management.


title: PARAMETERS
content:
<b>[TASK_ID | GROUP]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The numeric ID of a specific task or the name of a task group whose log is to be displayed. This argument is generally required to specify which log to retrieve.<br><br><b>--full-log</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the complete log output for the specified task or group, bypassing any default log truncation.<br><br><b>--json</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the log and associated task metadata in a machine-readable JSON format, suitable for scripting and integration with other tools.<br><br><b>--color <always|auto|never></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls when terminal colors are used in the output. <I>auto</I> (default) applies colors when output is to a TTY; <I>always</I> forces colors regardless of output; <I>never</I> disables all colors.<br><br><b>--follow, -f</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Continuously monitors and displays new log output as it becomes available for a running task, similar to `tail -f`.<br><br><b>--no-wait</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When used in conjunction with <B>--follow</B>, this option prevents <I>pueue-log</I> from waiting for the task to finish before displaying its log. It immediately shows what's available.<br><br><b>--config <CONFIG></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to a custom Pueue configuration file to be used instead of the default.<br><br><b>--port <PORT></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the port number on which the Pueue daemon is listening for client connections.<br><br><b>--host <HOST></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the host address where the Pueue daemon is running. This allows connecting to a daemon on a remote machine or a different local interface.<br><br><b>--daemon</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the Pueue daemon executable. This can be used to explicitly tell the client where the daemon binary is located, potentially for non-standard installations.<br><br>


title: DESCRIPTION
content:
<I>pueue-log</I> is a command-line utility within the <I>Pueue</I> task management system. It allows users to inspect the standard output (stdout) and standard error (stderr) logs generated by tasks managed by the <I>Pueue</I> daemon. This is crucial for debugging, monitoring, and understanding the execution flow of background processes. Users can view logs for specific tasks by their ID or group, retrieve full logs, stream live logs for running tasks, and control the output format, including JSON or colored output. It connects to the running <I>Pueue</I> daemon to fetch the requested log data, providing a centralized way to access task execution details.


title: CAVEATS
content:
Logs are only available if the <I>Pueue</I> daemon is running and has successfully captured the task's output. Log retention policies, configurable in the <I>pueue.yml</I> file, dictate how long logs are stored, meaning older logs might be purged. By default, logs might be truncated; use <B>--full-log</B> for complete output. For active tasks, logs might not update instantly unless <B>--follow</B> is used.


title: LOG STORAGE
content:
The <I>Pueue</I> daemon typically stores task logs in its designated data directory, which is often located in <I>~/.config/pueue/logs</I> or <I>~/.local/share/pueue/logs</I>, depending on the operating system and configuration. The <I>pueue-log</I> command retrieves these logs from the running daemon, rather than directly accessing the files.


title: TASK STATES
content:
Logs are captured and available for tasks regardless of their final state, including <I>running</I>, <I>paused</I>, <I>done</I>, <I>failed</I>, and other terminal states, provided the task's output was successfully recorded by the <I>Pueue</I> daemon.


title: HISTORY
content:
<I>Pueue</I> is a modern, cross-platform task queue and command runner designed for simplicity and efficiency in managing background processes. It emerged as a user-friendly alternative to more complex job schedulers. The <I>pueue-log</I> command is a core component, providing essential visibility into the standard output and standard error streams of queued and executed tasks. Its development has focused on ease of use, robust logging, and flexible output options, making it a valuable tool for both interactive debugging and automated scripting within the <I>Pueue</I> ecosystem.


title: SYNOPSIS
content:
<b>pueue-parallel</b> [<i>OPTIONS</i>] [<i>COMMAND_TEMPLATE</i>]<br><i>(Reads commands from stdin, or uses COMMAND_TEMPLATE with input lines)</i>


title: PARAMETERS
content:
<b>-j, --jobs <JOBS></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specify the number of commands to execute in parallel for this batch. This overrides Pueue's global concurrency limit for tasks added by this invocation.</i><br><br><b>-g, --group <GROUP></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Assign the submitted tasks to a specific Pueue group. This helps in organizing and managing related tasks.</i><br><br><b>--command-template <TEMPLATE></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Define a command template that will be executed for each input line. Use '{}' as a placeholder for the input line. For example, '--command-template "echo Processing {}"'.</i><br><br><b>--delay-for <DURATION></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Delay the execution of the submitted tasks by a specified duration (e.g., '5s', '2m', '1h').</i><br><br><b>--dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Perform a dry run: print the commands that would be submitted to Pueue without actually adding them.</i><br><br><b>--no-pueue</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Execute commands sequentially without using the Pueue daemon. This bypasses Pueue's queueing and parallelization features, acting as a simple sequential runner.</i><br><br><b>--max-tasks <NUM></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Limit the maximum number of tasks to be submitted from the input.</i><br><br><b>--max-args <NUM></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>When using '--command-template', specify the maximum number of input lines to be passed as arguments to a single command.</i><br><br><b>--progress-bar</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Display a progress bar indicating the submission and execution status of the tasks.</i><br><br><b>--start-immediately</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Instruct Pueue to start the submitted tasks immediately, overriding any pending state.</i><br><br>


title: DESCRIPTION
content:
<i><b>pueue-parallel</b> is a utility that streamlines the execution of multiple commands in parallel using the <I>Pueue</I> task queue system. It is designed to read commands from standard input, typically one command per line, and submit them as individual tasks to the <I>Pueue</I> daemon. Alternatively, it can process input lines by substituting them into a specified command template.<br><br>This command is particularly useful for orchestrating large batches of jobs, ensuring that the number of concurrently running tasks adheres to <I>Pueue</I>'s configured parallelization limits. It acts as a bridge between common Unix pipeline tools (like <b>find</b>, <b>grep</b>, or <b>cat</b>) and <I>Pueue</I>, allowing users to easily parallelize tasks that might otherwise be run sequentially or managed with more complex scripting. It offers features like specifying job groups, limiting concurrency, and handling input processing, making it a flexible tool for batch processing within the <I>Pueue</I> ecosystem.</i>


title: CAVEATS
content:
<i><b>pueue-parallel</b> requires a running Pueue daemon to submit and manage tasks (unless '--no-pueue' is used). It's designed for batch processing where each input line corresponds to a task or part of a task. While powerful, complex command logic or inter-task dependencies are best handled by Pueue's core scheduling features rather than solely relying on this helper. Error handling for individual commands is managed by Pueue's logging and status tracking.</i>


title: INPUT MODES
content:
<i><b>pueue-parallel</b> primarily accepts input via standard input (stdin). Each line read from stdin is treated as a command to be executed, or as an argument to be substituted into a <I>COMMAND_TEMPLATE</I>. This allows seamless integration with other commands that output lists, such as <b>find</b> with <b>-print0</b> (when combined with <b>xargs -0</b> and a template) or <b>cat</b>. When no <I>COMMAND_TEMPLATE</I> is provided, each input line is run directly as a command.</i>


title: INTEGRATION EXAMPLES
content:
<i>This command is frequently used in conjunction with other shell utilities to automate parallel processing. For instance, to convert all .jpg files in a directory to .png in parallel:<br><code><b>find . -name "*.jpg" | pueue-parallel -j 4 --command-template "convert {} {}.png"</b></code><br>Or to simply run a list of commands defined in a file:<br><code><b>cat commands.txt | pueue-parallel</b></code><br>These patterns highlight its utility in building powerful, parallelized workflows.</i>


title: HISTORY
content:
<i><b>pueue-parallel</b> is an integral part of the <I>Pueue</I> project, a command-line task queue and scheduler. It was developed to simplify the process of submitting multiple independent tasks to <I>Pueue</I> for parallel execution, particularly when integrating with standard Unix pipelines. Its development reflects the need for a user-friendly wrapper to leverage <I>Pueue</I>'s robust scheduling capabilities for batch jobs, making it easier to manage concurrent operations without manual task submission.</i>


title: SYNOPSIS
content:
<b>pueue pause</b> [<b>-a</b> | <b>--all</b>] | [<b>-g</b> <I>name</I> | <b>--group</b> <I>name</I>] | [<b><I>task_id</I>...</b>]


title: PARAMETERS
content:
<b><b>-a</b>, <b>--all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pauses all tasks managed by Pueue, across all groups. This is a global pause operation.<br><br><b><b>-g</b> <I>name</I>, <b>--group</b> <I>name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pauses all tasks belonging to the specified task group. If no group is specified, the default group is assumed. This flag allows targeting a specific group for the pause operation.<br><br><b><b><I>task_id</I>...</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more space-separated task IDs to be paused. These are positional arguments. Task IDs can be obtained using the <I>pueue status</I> command. If no options (<b>-a</b>, <b>-g</b>) are provided, this command expects at least one task ID.<br><br>


title: DESCRIPTION
content:
The <b>pueue-pause</b> command, part of the <I>Pueue</I> task queue manager, is used to halt the execution of tasks that are currently running or to prevent tasks from starting if they are in the 'queued' state. When a task is paused, Pueue sends a <I>SIGSTOP</I> signal to the running process, effectively suspending its execution. Queued tasks that are paused will not be started until they are resumed. This command is useful for temporarily stopping resource-intensive jobs, troubleshooting, or prioritizing other tasks. <br><br>You can pause specific tasks by their IDs, all tasks across all groups, or all tasks within a particular group. Paused tasks retain their position in the queue and can be resumed later using the <I>pueue-resume</I> command.


title: CAVEATS
content:
For <b>pueue-pause</b> to function, the <I>Pueue</I> daemon must be running in the background. If the daemon is not active, the command will fail to connect. <br><br>While Pueue attempts to pause running processes by sending a <I>SIGSTOP</I> signal, some applications might not handle this signal gracefully or might be in an uninterruptible state, leading to a delay or failure in pausing. <br><br>Pausing a task only affects its execution state within Pueue; it does not affect any external resources or processes that might have been spawned by the task outside of Pueue's direct control.


title: HOW PAUSING WORKS
content:
When <b>pueue pause</b> is executed for a running task, Pueue sends a <I>SIGSTOP</I> signal to the task's process. This signal instructs the operating system to suspend the process's execution. The process remains in memory but is not scheduled to run. When a task is resumed with <I>pueue-resume</I>, a <I>SIGCONT</I> signal is sent, allowing the process to continue from where it left off.


title: IDEMPOTENCY
content:
The <b>pueue pause</b> command is idempotent. This means that pausing a task that is already in a 'paused' state will have no additional effect and will not result in an error. This behavior ensures that repeated calls to pause a task or group do not cause unintended side effects.


title: HISTORY
content:
<I>Pueue</I> is a modern command-line task queue daemon written in Rust, designed to be a simple, robust, and user-friendly alternative for managing background tasks and long-running processes. It was created to address the need for a straightforward way to queue and execute commands sequentially or in parallel without complex configurations. The core <I>pueue</I> client and its subcommands, including <b>pueue-pause</b>, have been integral to its design since early development, evolving to provide reliable task control for various use cases, from software compilation to data processing.


title: PARAMETERS
content:
<b>TASK_IDS_OR_TAGS...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Optional</i>. One or more task IDs (numeric) or tags (alphanumeric) to remove. If omitted, the last added task (if not started) is removed.<br><br><b>-a, --all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remove all tasks currently in the queue, regardless of their state or group.<br><br><b>-g, --group &lt;GROUP&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remove all tasks belonging to the specified group.<br><br><b>-c, --confirm</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly ask for confirmation when performing potentially dangerous operations, such as removing all tasks. This is often the default behavior for such operations.<br><br><b>-f, --force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress the confirmation prompt for potentially dangerous operations, allowing for immediate removal without user interaction. This option overrides <b>--confirm</b>.<br><br>


title: DESCRIPTION
content:
<b>pueue-remove</b> is a subcommand of the <b>pueue</b> task management system, designed for efficiently removing tasks from its queue. Pueue is a command-line tool and library for managing a queue of shell commands, allowing users to schedule, run, and oversee tasks in the background.<br><br>The <b>remove</b> command specifically targets tasks by their unique IDs or assigned tags. If invoked without any specific task IDs or tags, it defaults to removing the most recently added task, provided it hasn't already started execution. This command is crucial for cleaning up the queue, canceling scheduled operations, or re-organizing pending work. It supports various options for bulk removal, such as clearing all tasks or targeting specific task groups, and includes safeguards against accidental deletions.


title: CAVEATS
content:
Removed tasks are permanently deleted from the queue and cannot be recovered.<br><br>If a task is currently running when <b>pueue remove</b> is called on it, Pueue will typically mark it for removal upon completion rather than immediately terminating it, unless specifically configured otherwise. <br><br>Using <b>--all</b> or <b>-g</b> with a group name can lead to mass deletions. Always double-check the command before executing, especially in production or critical environments. The <b>--force</b> option bypasses the confirmation prompt, increasing the risk of accidental data loss.


title: DAEMON-CLIENT ARCHITECTURE
content:
Pueue operates with a client-server model. The <b>pueue remove</b> command acts as a client that communicates with the long-running Pueue daemon to request task removal. The daemon then handles the actual queue manipulation.


title: TASK IDS AND TAGS
content:
Tasks in Pueue are identified by unique numeric IDs assigned sequentially, and can also be assigned custom string tags for easier grouping and manipulation. Both can be used with <b>pueue remove</b>.


title: HISTORY
content:
<b>pueue</b> is a relatively modern and actively developed command-line tool, first appearing around 2017-2018. It was created to provide a more flexible and robust alternative to simple `&` or `nohup` for background tasks, offering features like task grouping, dependency management, and persistent queues. The <b>pueue remove</b> command has been a core component since its early versions, providing essential queue management capabilities as the project evolved. Its development focuses on a user-friendly CLI with a reliable backend written in Rust.


title: PARAMETERS
content:
<b><i>--config &lt;FILE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative path to a Pueue configuration file. By default, Pueue looks for its configuration in standard locations like <i>~/.config/pueue/pueue.yml</i>.<br><br><b><i>--color &lt;WHEN&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls when to use colored output. Possible values are <i>always</i>, <i>auto</i> (default), and <i>never</i>. <i>auto</i> detects if the output is a TTY.<br><br><b><i>--debug</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose debug logging for the command's execution, which can be helpful for troubleshooting.<br><br><b><i>--json</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the command's result in JSON format, useful for scripting and programmatic integration.<br><br><b><i>--profile &lt;NAME&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects a specific configuration profile defined within the Pueue configuration file. This allows managing multiple independent Pueue instances or configurations.<br><br>


title: DESCRIPTION
content:
<i>pueue-reset</i> is a subcommand of the Pueue task queue manager. It is used to completely reset the daemon's state, effectively clearing all managed tasks and groups. When executed, <i>pueue-reset</i> stops the currently running Pueue daemon, removes all task data, logs, and group definitions from the daemon's storage location, and then restarts the daemon. This command is useful when you want to start fresh with Pueue, discarding all previous tasks, their outputs, and the current queue's state. It provides a clean slate, making it an essential tool for development, testing, or when an accumulated history of tasks is no longer desired.<br><br>It's important to understand that this operation is destructive and irreversible for the data stored by Pueue.


title: CAVEATS
content:
<b>Data Loss:</b> The <i>pueue reset</i> command is destructive. It permanently deletes all queued, running, finished, and failed tasks, along with their associated logs and output, and all defined groups. This action cannot be undone.<br><br><b>Daemon Restart:</b> The command stops the Pueue daemon and then restarts it. This will briefly interrupt any ongoing Pueue operations or client connections. Ensure no critical tasks are actively relying on the daemon during the reset.<br><br><b>Permissions:</b> You need appropriate file system permissions to delete the Pueue daemon's data directory and logs, typically located in <i>~/.local/share/pueue</i> or similar user-specific paths.


title: IMPACT ON DAEMON STATE
content:
Executing <i>pueue reset</i> essentially brings the Pueue daemon back to its initial, uninitialized state. All previous task IDs are discarded, and new tasks will start from ID 0. This is different from <i>pueue clean</i>, which only removes finished tasks but preserves the current task IDs and the state of active tasks.


title: HISTORY
content:
Pueue (pronounced "queue") is a relatively modern task queue manager written in Rust. It was created to provide a simple, robust, and user-friendly way to manage and execute shell commands asynchronously in the background. The <i>pueue reset</i> command has been a fundamental part of Pueue's functionality since early versions, providing a straightforward mechanism for users to clear their task history and restart the queue from a clean state. Its design emphasizes ease of use and minimal configuration.


title: PARAMETERS
content:
<b>TASK_IDS_OR_TAGS...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more task IDs (integers) or tags (strings) to restart. If not specified, a status flag or --all/--group is required.<br><br><b>--all, -a</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Restarts all tasks currently in the queue.<br><br><b>--group <NAME>, -g <NAME></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Restarts all tasks belonging to the specified group.<br><br><b>--exclude-group <NAME></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Excludes tasks belonging to the specified group from being restarted when used with --all or other group/status flags.<br><br><b>--failed</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Restarts all tasks that are currently in a 'failed' state.<br><br><b>--successful</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Restarts all tasks that have successfully completed.<br><br><b>--stashed</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Restarts all tasks that are currently 'stashed' (put aside for later manual execution).<br><br><b>--paused</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Restarts all tasks that are currently 'paused'.<br><br><b>--running</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Restarts all tasks that are currently 'running'. Note: This will stop and then re-queue them.<br><br><b>--status <STATUS></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Restarts tasks with the specified status (e.g., <i>queued</i>, <i>running</i>, <i>paused</i>, <i>stashed</i>, <i>failed</i>, <i>done</i>).<br><br><b>--force, -f</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skips the interactive confirmation prompt for restart operations, proceeding directly.<br><br><b>--exclude-id <ID></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Excludes specific task IDs from being restarted when used with --all or --group.<br><br>


title: DESCRIPTION
content:
<i>pueue-restart</i> is a subcommand of the <b>pueue</b> task management utility. It allows users to re-execute tasks that have previously been added to the Pueue queue. This is particularly useful for re-running failed tasks, or simply repeating a task without re-adding it from scratch.<br><br>Tasks can be identified by their unique numerical ID or by custom tags assigned during their creation. When a task is restarted, a <b>new task entry</b> is created in the queue, inheriting the command and parameters of the original task. This new task is typically placed in a <i>queued</i> or <i>stashed</i> state, ready for execution by the <b>pueued</b> daemon. The command provides options to restart all tasks, tasks within a specific group, or specific tasks identified by their current status. It also supports non-interactive execution with a force flag, making it a powerful tool for managing background processes and ensuring task completion.


title: CAVEATS
content:
Requires the <i>pueued</i> daemon to be running for the command to interact with the task queue.<br>Restarting a task creates a <b>new task entry</b> in the queue with the original command parameters, rather than simply resetting the status of the existing task.<br>Be cautious when using <b>--all</b> or <b>--group</b> combined with <b>--force</b>, as it can inadvertently re-execute many commands without confirmation.<br>Restarted tasks are typically re-added to the <i>end</i> of the queue by default, following existing task execution order.


title: TASK STATE TRANSITIONS
content:
When <i>pueue restart</i> is invoked, it doesn't modify the state of the original task. Instead, it creates a <b>new task entry</b> in the queue, copying the command, arguments, and other parameters from the specified existing task. This new task is typically assigned a <i>queued</i> or <i>stashed</i> status, ready for execution by the daemon.


title: CONFIGURATION IMPACT
content:
The behavior of <i>pueue restart</i> can be influenced by the user's <b>pueue.yml</b> configuration file. This includes default groups, execution directories, and other settings that apply to newly added tasks, thereby affecting the characteristics of the restarted task.


title: HISTORY
content:
Pueue is a relatively modern, open-source project designed for simple, local task scheduling and management. It gained popularity as a lightweight alternative to more complex batch systems, especially for personal script execution and background process management. The <b>restart</b> functionality is a core component, reflecting the common need to easily re-run jobs, particularly those that might have failed due to transient issues or require repeated execution. Its development emphasizes user-friendliness, clear status reporting, and a robust way to manage the lifecycle of queued commands.


title: SEE ALSO
content:
pueue(1), pueued(1), pueue add(1), pueue status(1), pueue stop(1), pueue pause(1), pueue start(1), pueue remove(1)


title: PARAMETERS
content:
<b>-d, --delay <DURATION></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Delays</i> the execution of the task. Duration can be a number (seconds), or a time string like "10s", "5m", "1h", "tomorrow 10:00".<br><br><b>-s, --start-immediately</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Starts</i> the task immediately, even if the queue is currently paused.<br><br><b>-p, --path <PATH></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Sets</i> the working directory for the command's execution.<br><br><b>-l, --label <LABEL></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Assigns</i> a custom label to the task for easier identification in the task list.<br><br><b>-g, --group <GROUP></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Adds</i> the task to a specific group. If the group doesn't exist, it will be created.<br><br><b>-a, --after <TASK_ID></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Executes</i> this task only after the specified task ID has finished successfully.<br><br><b>-N, --no-auto-start</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Adds</i> the task to the queue but prevents it from starting automatically. It will remain 'Stalled' until manually started.<br><br><b>-P, --print-task-id</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Prints</i> the ID of the newly added task to standard output upon successful submission.<br><br><b>--priority <PRIORITY></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Sets</i> the numerical priority of the task. Higher numbers indicate higher priority (e.g., 0-100).<br><br><b>--env <KEY=VALUE></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Sets</i> an environment variable for the task's execution. Can be specified multiple times.<br><br><b>--shell <SHELL></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies</i> the shell to use for executing the command (e.g., <i>/bin/bash</i>, <i>/usr/bin/zsh</i>).<br><br><b>--stgout</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Configures</i> Pueue to store the task's standard output to a file.<br><br><b>--stgerr</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Configures</i> Pueue to store the task's standard error to a file.<br><br><b>--stgmerge</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Merges</i> standard error into standard output for storage purposes.<br><br><b>--pre-command <CMD></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Executes</i> a command before the main task begins. This command runs in the same environment as the main task.<br><br><b>--post-command <CMD></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Executes</i> a command after the main task completes, regardless of its success or failure.<br><br><b>--dependencies <TASK_IDS...></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Sets</i> dependencies on other tasks; this task will only run after all specified tasks complete successfully. Multiple IDs can be space-separated.<br><br>


title: DESCRIPTION
content:
<i>pueue-send</i> is a core command of the Pueue project, a robust command-line task queue and job scheduler for Linux and macOS. It is primarily used to submit new commands or scripts to the Pueue daemon, which then executes them asynchronously in the background. This allows users to queue long-running tasks without blocking their terminal, retrieving their output and status later. <br><br><i>pueue-send</i> offers extensive options to control how a task is executed, including specifying a working directory, delaying execution, assigning custom labels or groups, setting priorities, and defining dependencies on other tasks. It provides a convenient way to manage a personal queue of background jobs, enhancing productivity for developers, system administrators, and anyone needing to run multiple background processes efficiently.


title: CAVEATS
content:
Before using <i>pueue-send</i>, ensure that the Pueue daemon (<b>pueued</b>) is running in the background. Without the daemon, tasks cannot be queued or executed. <br><br>Tasks submitted via <i>pueue-send</i> are designed to run asynchronously; their output and status must be checked using other Pueue commands like <b>pueue status</b> or <b>pueue log</b>, as they do not provide immediate interactive feedback.


title: DEFAULT OUTPUT STORAGE
content:
By default, Pueue captures and stores the standard output and standard error of all tasks submitted via <i>pueue-send</i>. You can view these logs later using the <b>pueue log</b> command. Use <b>--no-stgout</b> or <b>--no-stgerr</b> to explicitly disable this behavior for specific streams if output storage is not desired for a particular task.


title: TASK IDS
content:
Every task added to Pueue is assigned a unique numerical ID. This ID is crucial for interacting with tasks using other Pueue commands (e.g., <b>pueue status &lt;ID&gt;</b>, <b>pueue remove &lt;ID&gt;</b>). You can explicitly request this ID to be printed to your terminal immediately after submission using the <b>-P</b> or <b>--print-task-id</b> option, which is useful for scripting.


title: HISTORY
content:
Pueue emerged as a modern, user-friendly alternative to traditional Linux job schedulers like <b>at</b> or more complex batch systems. Its development, primarily in Rust, started around 2018-2019, driven by the need for a simple yet powerful command-line task queue that integrates well with modern developer workflows. It aims to provide intuitive control over personal background processes without the overhead of full-fledged job schedulers, focusing on ease of use and persistent task management.


title: PARAMETERS
content:
<b><b>-c</b> <I>FILE</I>, <b>--config</b> <I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a custom configuration file for Pueue. By default, Pueue looks for its configuration in standard locations like <i>~/.config/pueue.yml</i>.<br><br><b><b>-d</b> <I>NAME</I>, <b>--daemon</b> <I>NAME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to a specific Pueue daemon instance identified by <i>NAME</i>. This is useful when running multiple Pueue daemons concurrently.<br><br><b><b>-H</b> <I>HOST</I>, <b>--host</b> <I>HOST</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to a Pueue daemon running on a remote <i>HOST</i>. By default, Pueue connects locally via a Unix socket or localhost.<br><br><b><b>-P</b> <I>PORT</I>, <b>--port</b> <I>PORT</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to a Pueue daemon on a specific TCP <i>PORT</i> when connecting to a remote host or via TCP locally.<br><br>


title: DESCRIPTION
content:
The `pueue-shutdown` command is used to gracefully terminate the running Pueue daemon. Pueue operates on a client-server model, where the daemon (server) manages task queues in the background, and the `pueue` client commands interact with it. When `pueue-shutdown` is executed, the client sends a signal to the active Pueue daemon, instructing it to prepare for termination.<br><br>Upon receiving the shutdown signal, the Pueue daemon will typically complete any currently executing tasks and then stop processing new commands. It ensures a clean exit, preserving the state of pending tasks so they can be resumed when the daemon is restarted. This command is crucial for maintaining data integrity and avoiding abrupt interruptions to your automation workflows. It's often used when upgrading Pueue, performing system maintenance, or simply when the task queueing service is no longer needed. Unlike forcibly killing the daemon, `pueue-shutdown` allows for a controlled and safe cessation of operations, preventing potential data corruption or orphaned processes.


title: CAVEATS
content:
The `pueue-shutdown` command requires a running Pueue daemon to connect to. If no daemon is active or reachable (e.g., due to network issues, incorrect configuration, or permissions), the command will report an error indicating it could not connect. While the command aims for a graceful shutdown, tasks that are extremely long-running might delay the daemon's full termination. It's important to ensure that the client executing the command has the necessary permissions to communicate with the daemon's socket or port.


title: GRACEFUL TERMINATION BEHAVIOR
content:
When `pueue-shutdown` is invoked, the Pueue daemon prioritizes the completion of currently running tasks before initiating its exit sequence. This design ensures that ongoing processes are not abruptly terminated, thereby preventing potential data loss or corrupted outputs. Only after all active tasks have finished, or if no tasks were running, does the daemon fully shut down. This behavior is crucial for automated environments where task integrity is paramount.


title: CONNECTION MECHANISM
content:
The `pueue-shutdown` command, like other `pueue` client commands, communicates with the Pueue daemon primarily via a Unix socket on the local machine by default. For remote connections or specific local setups, it can also communicate over TCP. The connection method is typically determined by the daemon's configuration and the client's options (`--host`, `--port`).


title: HISTORY
content:
Pueue is a relatively modern, open-source task queue manager written in Rust, developed by Christoph Burgdorf. It was created to provide a simple, powerful, and robust way to manage background tasks and commands on Linux systems. Its development focuses on reliability, ease of use, and a clear client-server architecture, making `pueue-shutdown` an integral part of its operational lifecycle for controlled daemon management.


title: PARAMETERS
content:
<b><i>--config</i> <I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative path to the <b>Pueue</b> configuration file. By default, <b>Pueue</b> looks for <i>pueue.yml</i> in standard configuration directories such as <i>~/.config/pueue/</i>.<br><br><b><i>--no-fork</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents the <b>Pueue</b> daemon from detaching and running in the background. When this option is used, the daemon runs in the foreground, which is particularly useful for debugging purposes or when running <b>Pueue</b> under a process supervisor like <b>systemd</b>.<br><br><b><i>--log-level</i> <I>LEVEL</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the verbosity of the daemon's logging output. Common acceptable levels include <i>error</i>, <i>warn</i>, <i>info</i>, <i>debug</i>, and <i>trace</i>.<br><br>


title: DESCRIPTION
content:
The <i>pueue-start</i> command initiates the <b>Pueue</b> daemon, which serves as the core backend process for the <i>pueue</i> command-line task queue system. Running continuously in the background, this daemon is solely responsible for managing all queued tasks, enforcing concurrency limits, executing commands, and maintaining their state and output. It acts as the central hub for all <i>pueue</i> client operations, such as adding, showing, or removing tasks from the queue.<br><br>Typically, <i>pueue-start</i> is executed once per user session or configured to run automatically upon system startup (e.g., via a <i>systemd</i> user service). Without the daemon running, most <i>pueue</i> client commands will fail, as they rely on active communication with the daemon to perform their functions. By ensuring the daemon is operational, <i>pueue-start</i> enables users to seamlessly queue, manage, and monitor long-running or resource-intensive tasks in an organized and persistent manner.


title: CAVEATS
content:
The exact behavior and availability of the <i>pueue-start</i> command can vary depending on the <b>Pueue</b> version and installation method. In many modern <b>Pueue</b> setups, its functionality is directly provided by the <i>pueue daemon</i> command. Consequently, <i>pueue-start</i> might be a symbolic link, a wrapper script, or not present as a standalone binary. If the <b>Pueue</b> daemon is already running, executing <i>pueue-start</i> again will typically do nothing or report that the daemon is already active, to prevent multiple instances.


title: RUNNING AS A SERVICE
content:
For persistent and automatic daemon management, <i>pueue-start</i> (or <i>pueue daemon</i>) is frequently configured to run as a <b>systemd</b> user service. This setup ensures the daemon starts automatically upon user login and automatically restarts if it crashes, providing continuous task management availability without manual intervention.


title: CONFIGURATION FILE
content:
The overall behavior and settings of the <b>Pueue</b> daemon, including its working directory, log file locations, default command execution parameters, and concurrent task limits, are primarily controlled by a YAML configuration file, typically found at <i>~/.config/pueue/pueue.yml</i>.


title: HISTORY
content:
<b>Pueue</b>, created by Lennart Kuehn, was developed to offer a straightforward and robust command-line task queue for personal use, especially for managing long-running processes. The core functionality of starting the daemon, which is central to <b>Pueue</b>'s operation, has been present since its early development. While the command name or invocation might have seen minor changes (e.g., evolving from a dedicated <i>pueue-start</i> binary to a subcommand like <i>pueue daemon</i>), its role in providing the persistent backend for task management remains fundamental to the project's design and evolution.


title: PARAMETERS
content:
<b>&lt;TASK_IDS&gt;...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more space-separated numeric IDs of the tasks to be stashed.<br><br><b><b>--all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stashes all tasks currently in the queue. This option cannot be used in conjunction with specific <i>TASK_IDS</i>.<br><br><b><b>-g</b>, <b>--group</b> &lt;<i>GROUP</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the group from which tasks should be stashed. If this flag is omitted, the default group is assumed.<br><br><b><b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skips the confirmation prompt when stashing tasks, making it suitable for scripting or automated workflows.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a short help message for the <i>stash</i> subcommand, showing available options and arguments.<br><br>


title: DESCRIPTION
content:
<i>pueue-stash</i> is a subcommand of the <i>pueue</i> task management system. It allows users to temporarily remove tasks from the active Pueue queue without permanently deleting them.<br><br>Stashed tasks are moved to a separate "stashed" state, making them invisible and inactive in the main queue. This feature is useful for decluttering the queue, pausing work on specific tasks, or holding tasks for later execution without losing their state or definition. Stashed tasks can be retrieved and re-added to the active queue using the <i>pueue restore</i> command. It supports stashing specific tasks by ID, all tasks, or tasks within a particular group.


title: CAVEATS
content:
Stashed tasks are no longer processed by Pueue and will not run until restored.<br>You cannot stash a task that is currently running; it must be stopped or killed first.<br>Stashed tasks retain their full state and definition, enabling seamless restoration with <i>pueue restore</i>.


title: STASHED STATE
content:
Stashed tasks are conceptually moved to a 'holding area' within Pueue. They are not deleted and can be viewed using <i>pueue status --stashed</i> or restored to the active queue.


title: RESTORING TASKS
content:
To bring stashed tasks back into the active queue for processing, use the <i>pueue restore</i> command. You can specify their IDs or use the <i>--all</i> flag to restore all stashed tasks.


title: HISTORY
content:
<i>Pueue</i> is a modern, cross-platform task queue and command runner written in Rust, known for its simplicity and reliability in managing background jobs. The <i>stash</i> functionality was introduced as a core feature to provide flexibility in task management, allowing users to temporarily shelve tasks without losing their context. It evolved alongside the <i>pueue</i> project to cater to common task management needs, enhancing the overall utility of the system for developers and system administrators.


title: PARAMETERS
content:
<b>-g, --group <GROUP></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filters the display to show only tasks belonging to the specified group.<br><br><b>-s, --show-stashed</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes tasks that are currently stashed (temporarily removed from the active queue) in the output. By default, stashed tasks are not shown.<br><br><b>-j, --json</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the current state of the Pueue daemon and tasks in machine-readable JSON format, ideal for scripting and automation.<br><br><b>-H, --host <HOST></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the host address where the Pueue daemon is running, if different from the default (localhost).<br><br><b>-p, --port <PORT></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the port number on which the Pueue daemon is listening, if different from the default.<br><br><b>-v, --verbose...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases the verbosity level of the client's output. Can be specified multiple times for more detailed messages.<br><br><b>-q, --quiet...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Decreases the verbosity level of the client's output. Can be specified multiple times for fewer messages.<br><br><b>-L, --log-level <LEVEL></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the logging level for the client. Possible values include <I>error</I>, <I>warn</I>, <I>info</I>, <I>debug</I>, or <I>trace</I>.<br><br><b>-l, --log-file <FILE></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a file path where the client's log messages should be written.<br><br><b>-c, --config <FILE></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative configuration file for Pueue to use instead of the default location.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the <i>pueue status</i> command.<br><br>


title: DESCRIPTION
content:
<i>pueue status</i> provides a comprehensive overview of the Pueue task queue manager's current state.<br>It shows tasks that are currently <I>running</I>, <I>paused</I>, <I>queued</I>, or <I>finished</I>, along with their IDs, commands, and statuses.<br>This command is essential for monitoring and managing ongoing automation workflows or background processes managed by Pueue.<br>It helps users understand which tasks are active, waiting, or have completed, providing insights into system load and task progression.<br>It can also display tasks organized by groups and has options for JSON output, which is useful for scripting and integration with other tools.


title: CAVEATS
content:
<ul><li>The <i>pueue status</i> command requires the Pueue daemon to be actively running in the background to retrieve and display status information.</li><li>By default, only active tasks (queued, running, paused, done, failed) are shown; stashed tasks must be explicitly requested with <B>--show-stashed</B>.</li><li>For large numbers of tasks, the output can be extensive. Utilizing the <B>--group</B> option can help filter and manage the displayed information.</li></ul>


title: TASK STATES
content:
Pueue tasks can exist in various states, which are clearly displayed by <i>pueue status</i>:<br><ul><li><I>queued</I>: The task is waiting in the queue to be executed.</li><li><I>running</I>: The task is currently executing.</li><li><I>paused</I>: The task is in the queue but will not start because the daemon or its group is paused.</li><li><I>done</I>: The task has completed successfully (exit code 0).</li><li><I>failed</I>: The task has completed with an error (non-zero exit code).</li><li><I>stashed</I>: The task has been temporarily moved out of the active queue and will not be processed unless restored.</li></ul>


title: GROUP MANAGEMENT
content:
Pueue allows tasks to be organized into <I>groups</I>, which can be managed (e.g., paused, unpaused, or have parallel execution limits) independently. <i>pueue status</i> can filter its output to show only tasks belonging to a specific group using the <B>--group</B> option, facilitating easier management of complex workflows.


title: SCRIPTING INTEGRATION
content:
The <B>--json</B> option transforms the output of <i>pueue status</i> into a structured JSON format. This makes the command highly suitable for integration into scripts, automation pipelines, and other monitoring tools that require programmatic access to Pueue's current state.


title: HISTORY
content:
Pueue is a modern task queue manager designed for simplicity and efficiency in managing local command execution. <i>pueue status</i> has been a core component since its early versions, providing immediate feedback on the daemon's state, which is crucial for its operation and user monitoring. Its functionality has evolved to include filtering by group and JSON output, adapting to growing needs for automation and more complex task management scenarios.


title: SYNOPSIS
content:
<b>pueue switch</b> [<I>name</I>] [<I>options</I>]<br><b>pueue switch --list</b><br><b>pueue switch --create</b> <I>name</I><br><b>pueue switch --delete</b> <I>name</I>


title: PARAMETERS
content:
<b><I>name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the Pueue daemon configuration (profile) to switch to. If no name is provided when switching, it typically reverts to the 'default' profile or shows the current active one depending on context.<br><br><b><b>-c</b>, <b>--create</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a new Pueue daemon configuration with the specified name if it doesn't already exist. This option must be used in conjunction with a <I>name</I>.<br><br><b><b>-d</b>, <b>--delete</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deletes the specified Pueue daemon configuration. This option must be used in conjunction with a <I>name</I>.<br><br><b><b>-l</b>, <b>--list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all available Pueue daemon configurations and indicates the currently active one.<br><br>


title: DESCRIPTION
content:
<i>pueue switch</i> is a subcommand of the Pueue task management system. It allows users to manage and switch between different Pueue daemon configurations, often referred to as 'profiles' or 'contexts'. This functionality is crucial for organizing tasks into separate, independent queues. For instance, a user might have one profile for development tasks, another for long-running data processing, and a third for system maintenance. By switching between these profiles, users can isolate task execution, preventing interference and improving organization. The command enables listing existing configurations, creating new ones, and deleting obsolete ones, providing flexible control over distinct Pueue environments.


title: CAVEATS
content:
Switching profiles involves stopping the <i>pueued</i> daemon associated with the old profile (if it's not managing active tasks) and starting the daemon for the new profile. This means tasks in the previously active profile might be paused or interrupted until that profile is reactivated. Ensure <i>pueued</i> has the necessary permissions to start and stop services.


title: CONFIGURATION PATHS
content:
Each Pueue daemon configuration (profile) is stored in a separate YAML file, typically located in <i>~/.config/pueue/config/</i>. For example, a profile named '<i>dev_tasks</i>' would have its configuration in <i>~/.config/pueue/config/dev_tasks.yml</i>. These files define client and daemon settings specific to that profile.


title: DAEMON MANAGEMENT
content:
When switching to a new profile using <i>pueue switch</i>, the corresponding <i>pueued</i> daemon for that profile is typically started automatically if it's not already running. The daemon for the previously active profile might be stopped or paused depending on its state and whether it has active tasks.


title: HISTORY
content:
Pueue was created by Arne Beer as a command-line task queue and runner. The <i>switch</i> subcommand was introduced to address the growing demand for managing multiple, independent task queues. This feature significantly enhanced Pueue's utility, allowing users to segment their tasks into logical contexts and thereby improving overall organization and workflow management.


title: PARAMETERS
content:
<b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show help message.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show PulseAudio version information.<br><br><b>--start</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Start the PulseAudio daemon if it's not already running. This is usually handled automatically.<br><br><b>--kill</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Kill the running PulseAudio daemon. This will terminate all audio output and input.<br><br><b>--check</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Check if a PulseAudio daemon is already running for the current user.<br><br><b>--daemonize</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Daemonize the PulseAudio process after starting. This runs it in the background.<br><br><b>--system</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run the PulseAudio server as a system-wide instance. <b>Caution:</b> This is generally discouraged for security and complexity reasons, as it means the daemon runs as root and all users share the same instance. It's primarily used for embedded systems or specific multi-user setups.<br><br><b>--log-level=<I>LEVEL</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the log level. Possible levels include: <i>error</i>, <i>warn</i>, <i>notice</i>, <i>info</i>, <i>debug</i>, <i>warning</i> (alias for warn).<br><br><b>--log-target=<I>TARGET</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the log target. Possible targets include: <i>syslog</i>, <i>auto</i>, <i>file:/path/to/file</i>, <i>newfile:/path/to/file</i>, <i>stderr</i>, <i>console</i>.<br><br><b>--exit-idle-time=<I>SECONDS</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Terminate the daemon after the specified number of seconds of inactivity. A value of 0 means never exit on idle.<br><br><b>--no-exit-idle-time</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable automatic exit on idle. The daemon will run indefinitely until explicitly killed.<br><br><b>--disallow-module-loading</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevent loading modules dynamically after startup. All required modules must be loaded via configuration files.<br><br><b>--disallow-exit-on-failure</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not exit if a module fails to load during startup. Continue running with available modules.<br><br>


title: DESCRIPTION
content:
The <b>pulseaudio</b> command is the primary executable for the <I>PulseAudio</I> sound system daemon. PulseAudio is a network-capable sound server program that provides advanced audio mixing, routing, and processing capabilities on Linux and other Unix-like operating systems. It acts as a proxy between your applications and the low-level sound drivers (like ALSA or OSS), allowing multiple applications to play sound simultaneously, redirect audio to different devices, apply per-application volume control, and even stream audio across a network.<br><br>While users typically don't run <b>pulseaudio</b> directly (as it's often started automatically by desktop environments or systemd as a user service), the command allows for manual control, debugging, and configuration of the daemon. It can be used to start, kill, check the status of, or modify the behavior of the running PulseAudio server.


title: CAVEATS
content:
Manual invocation of <b>pulseaudio --start</b> is generally discouraged unless you are troubleshooting or explicitly managing the daemon. Most desktop environments and modern Linux distributions manage PulseAudio automatically via <i>systemd</i> user services or similar mechanisms.<br><br>Running PulseAudio with the <b>--system</b> flag can lead to security vulnerabilities and is not recommended for typical desktop usage. It can also make debugging more complex.<br><br>Issues with PulseAudio are often related to misconfigured ALSA drivers, incorrect permissions, or conflicting audio services. Troubleshooting usually involves checking logs and configuration files.


title: CONFIGURATION FILES
content:
PulseAudio's behavior is primarily controlled by configuration files located in <i>/etc/pulse/</i> and <i>~/.config/pulse/</i>. Key files include: <br><b>daemon.conf</b>: Global daemon settings.<br><b>default.pa</b>: User-specific startup script, defining modules to load and initial settings.<br><b>system.pa</b>: System-wide startup script (used with <b>--system</b> mode).


title: TYPICAL USAGE CONTEXT
content:
In a standard Linux desktop environment, the PulseAudio daemon is usually started automatically as a user service when you log in. You rarely need to interact directly with the <b>pulseaudio</b> command itself for day-to-day operations. Instead, users typically manage audio settings via desktop sound controls, or advanced users might use client utilities like <b>pactl</b> or <b>pacmd</b> to query status or change parameters dynamically.


title: HISTORY
content:
PulseAudio was initially released in 2004 under the name <i>Polypaudio</i> by <I>Lennart Poettering</I>, and was renamed to PulseAudio in 2006. Its development aimed to provide a modern, flexible sound server for Linux, addressing limitations of older audio systems like ALSA's direct hardware access for multiple applications. It rapidly gained adoption and became the default sound server for major Linux distributions like Ubuntu and Fedora. While highly influential, PulseAudio has faced criticism regarding its complexity and performance in some scenarios. As of recent years, it is gradually being superseded by <I>PipeWire</I>, a newer multimedia framework designed to handle audio, video, and hardware devices more efficiently.


title: SYNOPSIS
content:
<b>pulumi</b> [<i>GLOBAL_OPTIONS</i>] <<i>COMMAND</i>> [<i>COMMAND_OPTIONS</i>] [<i>ARGUMENTS</i>]<br><br>Common commands include:<br><i>up</i>: Deploy or update a stack.<br><i>destroy</i>: Tear down all resources in a stack.<br><i>new</i>: Create a new Pulumi project.<br><i>stack</i>: Manage stacks.<br><i>config</i>: Manage stack configuration.


title: PARAMETERS
content:
<b><b>--stack</b> <<i>name</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the stack name to operate on. If omitted, Pulumi attempts to use the currently selected stack.<br><br><b><b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose debug logging output to stderr, useful for troubleshooting.<br><br><b><b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose logging output to stderr, showing more details about operations than default.<br><br><b><b>--non-interactive</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable interactive prompts, making the command suitable for automation and scripting environments.<br><br><b><b>--color</b> <<i>auto|always|never</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Control the use of colorized output. 'auto' (default) enables colors if supported by the terminal, 'always' forces colors, 'never' disables them.<br><br><b><b>--cwd</b> <<i>path</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run Pulumi commands from a specific working directory, overriding the current directory.<br><br>


title: DESCRIPTION
content:
The <b>pulumi</b> command-line interface (CLI) is the primary tool for interacting with the Pulumi infrastructure as code (IaC) platform. Pulumi enables developers and operations teams to define, deploy, and manage cloud infrastructure using familiar programming languages like TypeScript, Python, Go, C#, Java, and YAML, instead of domain-specific languages or declarative configuration files.<br><br>It supports a wide range of cloud providers including AWS, Azure, Google Cloud Platform, Kubernetes, and many others, treating infrastructure components (e.g., virtual machines, databases, networks, serverless functions) as programmable constructs. The <b>pulumi</b> CLI orchestrates the deployment process, performs previews of changes, manages state, and allows for rolling updates and rollbacks. It provides commands for creating new projects, deploying updates (<b>up</b>), destroying resources (<b>destroy</b>), managing configuration (<b>config</b>), and inspecting stacks (<b>stack</b>), integrating seamlessly into existing CI/CD pipelines.


title: CAVEATS
content:
Pulumi requires a backend to store infrastructure state (e.g., Pulumi Service, local filesystem, S3, Azure Blob Storage), which must be configured and accessible for proper operation.<br><br>Users must be familiar with the chosen programming language and its runtime environment (e.g., Node.js for TypeScript, Python interpreter for Python) as Pulumi executes user-provided code.<br><br>Managing infrastructure state requires careful attention; direct manual changes to cloud resources outside of Pulumi can lead to 'drift' and inconsistencies between the desired state in code and the actual state.


title: CORE PHILOSOPHY: INFRASTRUCTURE AS SOFTWARE
content:
Pulumi's fundamental principle is to treat infrastructure as software. This means applying familiar software development practices like version control, testing, modularity, abstraction, and reuse to infrastructure definitions. It enables teams to use existing IDEs, debugging tools, and CI/CD pipelines for infrastructure code.


title: LANGUAGE SUPPORT
content:
Pulumi offers first-class support for a variety of popular programming languages including <i>TypeScript/JavaScript</i>, <i>Python</i>, <i>Go</i>, <i>C#</i>, and <i>Java</i>. It also supports defining infrastructure using <i>YAML</i> for simpler declarative scenarios, providing flexibility for different team skill sets and preferences.


title: BACKEND OPTIONS
content:
Pulumi can store the state of your infrastructure deployments in various backends. The default and recommended backend is the <i>Pulumi Cloud</i> (SaaS), which offers features like state management, secrets, and collaboration. Alternatively, users can configure self-managed backends using cloud storage services like <i>AWS S3</i>, <i>Azure Blob Storage</i>, <i>Google Cloud Storage</i>, or even a local filesystem (primarily for testing).


title: HISTORY
content:
Pulumi was founded in 2017 by Joe Duffy, an ex-Microsoft veteran, with the vision of treating infrastructure as software. The company, Pulumi Corp., released the open-source project to the public, aiming to provide a 'universal IaC' solution that leverages general-purpose programming languages. This approach was designed to bring familiar software engineering practices—like testing, reuse, and abstraction—to infrastructure management, addressing perceived limitations of existing DSL-based IaC tools.


title: PARAMETERS
content:
<b>--json</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Emit output as JSON, which is useful for programmatic consumption of diagnostic information.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show help for the 'about' command, detailing its usage and specific flags.<br><br><b>--color <mode></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Control output colorization. Options include 'always', 'auto', 'raw', or 'never'. This is a global Pulumi flag.<br><br><b>--cwd <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run pulumi as if it were executed in the specified directory. This might influence reported paths for project/stack. This is a global Pulumi flag.<br><br><b>--non-interactive</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable interactive prompts for input. While 'about' is typically non-interactive, this is a general safety flag for automation. This is a global Pulumi flag.<br><br>


title: DESCRIPTION
content:
The <b>pulumi about</b> command provides a comprehensive overview of your Pulumi CLI installation and the current operational environment. It's an indispensable tool for debugging and understanding the context in which Pulumi commands are executed. The output includes vital details such as the Pulumi CLI version, its Git SHA, the Go runtime version, the operating system and architecture. Furthermore, it details user-specific configuration like the Pulumi home directory, the currently active <i>stack</i> and <i>project</i>, and information about the configured backend (e.g., local filesystem, Pulumi Cloud, S3). This diagnostic summary is extremely valuable when troubleshooting issues or providing support, ensuring all necessary environmental variables and configurations are visible.


title: CAVEATS
content:
The information provided by <b>pulumi about</b> is a snapshot of the current environment and configuration at the time of execution. It does not reflect changes made after the command runs or details about remote state without explicit fetching. The exact content and format of the output might slightly vary across different Pulumi CLI versions or operating systems.


title: KEY OUTPUT SECTIONS
content:
The output of <b>pulumi about</b> typically includes sections for Pulumi CLI details (version, Git SHA, Go info), operating system and architecture, Pulumi home directory, and most importantly, the currently active <i>project</i>, <i>stack</i>, and <i>backend</i> information. This aggregated view is crucial for validating environment setup.


title: DEBUGGING AID
content:
This command is frequently requested by Pulumi support or maintainers when diagnosing user issues, as it provides a consolidated view of the environment that might be affecting Pulumi operations.


title: HISTORY
content:
The <b>pulumi about</b> command has been a foundational utility within the Pulumi CLI since its early development. Introduced as part of Pulumi's commitment to developer experience and diagnostic support, its primary purpose has remained consistent: to provide a quick, comprehensive snapshot of the CLI environment. As the Pulumi platform evolved, encompassing various backends and cloud providers, the 'about' command has adapted to display relevant details about the active configuration and backend, becoming an essential tool for troubleshooting and understanding the deployment context.


title: PARAMETERS
content:
<b><I>&#x3C;stack-name&#x3E;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the stack whose pending update or operation you wish to cancel. This is a required positional argument.<br><br><b><b>--yes</b>, <b>-y</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skip confirmation prompts and proceed directly with the cancellation. Use with caution, especially in automated scripts.<br><br><b><b>--message</b> <I>&#x3C;string&#x3E;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An optional message to associate with the cancellation, which will be recorded in the stack's history.<br><br><b><b>--stack</b> <I>&#x3C;string&#x3E;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the stack to operate on. Can be used as an alternative to the positional argument <i>&#x3C;stack-name&#x3E;</i>, or to explicitly specify a stack different from the current one.<br><br><b><b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose debug logging for the command's execution.<br><br><b><b>--json</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Emit output as JSON, suitable for programmatic consumption.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display help information for the <i>pulumi cancel</i> command.<br><br>


title: DESCRIPTION
content:
The <i>pulumi-cancel</i> command is used to terminate an ongoing Pulumi deployment operation, such as an <i>update</i>, <i>destroy</i>, or <i>refresh</i>. This is particularly useful if a deployment is stuck, taking an unexpectedly long time, or was initiated by mistake.<br><br>Upon execution, <i>pulumi-cancel</i> attempts to signal the Pulumi engine to stop the current operation and mark the stack's state as 'cancelled'. It does not automatically roll back any changes that have already occurred, meaning resources might be left in a partially deployed or inconsistent state. Subsequent <i>pulumi update</i> commands would then attempt to reconcile the stack to its desired state based on the current program. By default, it prompts for confirmation unless the <i>--yes</i> flag is provided.


title: CAVEATS
content:
1. <b>Partial State:</b> Cancelling an operation may leave your cloud resources in a partially deployed or inconsistent state. <i>pulumi-cancel</i> does not automatically roll back changes; it only stops the ongoing process.<br>2. <b>Best Effort:</b> Cancellation is a best-effort attempt. Depending on the state of the operation and the cloud provider, it might take some time for the process to fully stop, or resources might continue to be created/deleted briefly.<br>3. <b>Confirmation:</b> By default, the command prompts for confirmation. To bypass this, use the <i>--yes</i> or <i>-y</i> flag, which is useful for scripting but should be used carefully.


title: HISTORY
content:
The <i>pulumi-cancel</i> command has been a core part of the Pulumi CLI since its early versions, introduced to provide users with essential control over long-running or stuck deployments. It addresses the critical need to gracefully terminate operations that might otherwise consume excessive time or lead to unexpected resource provisioning, thus enhancing the reliability and manageability of infrastructure as code deployments.


title: SYNOPSIS
content:
<b>pulumi config</b> <I>command</I> [<I>options</I>]<br><b>pulumi config set</b> <I>key</I> [<I>value</I>] [<I>options</I>]<br><b>pulumi config get</b> <I>key</I> [<I>options</I>]<br><b>pulumi config rm</b> <I>key</I> [<I>options</I>]<br><b>pulumi config ls</b> [<I>options</I>]<br><b>pulumi config refresh</b> [<I>options</I>]


title: PARAMETERS
content:
<b><b>set</b> <I>key</I> [<I>value</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a configuration value for the current or specified stack. If no value is provided, it will be prompted interactively.<br><ul><li><i>--secret</i>: Encrypts the value as a secret.</li><li><i>--path</i>: Treats the key as a path (e.g., 'a.b.c' for nested objects).</li><li><i>--stack <stack-name></i>: Operate on a specific stack instead of the current one.</li></ul><br><br><b><b>get</b> <I>key</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Retrieves a configuration value from the current or specified stack.<br><ul><li><i>--path</i>: Treats the key as a path.</li><li><i>--stack <stack-name></i>: Operate on a specific stack.</li></ul><br><br><b><b>rm</b> <I>key</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes a configuration value from the current or specified stack.<br><ul><li><i>--path</i>: Treats the key as a path.</li><li><i>--stack <stack-name></i>: Operate on a specific stack.</li></ul><br><br><b><b>ls</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all configuration values for the current or specified stack.<br><ul><li><i>--json</i>: Outputs the configuration in JSON format.</li><li><i>--stack <stack-name></i>: Operate on a specific stack.</li></ul><br><br><b><b>refresh</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Refreshes the plaintext display of secret config values if the stack's encryption passphrase has changed or if secrets need re-encryption.<br><ul><li><i>--stack <stack-name></i>: Operate on a specific stack.</li></ul><br><br>


title: DESCRIPTION
content:
<i>pulumi config</i> is a core subcommand of the Pulumi Command Line Interface (CLI) designed for managing configuration settings specific to a Pulumi stack. It provides a robust mechanism to handle dynamic and environment-specific values, such as API keys, region settings, or resource-specific properties, which often differ between deployment environments (e.g., development, staging, production).<br><br>The command allows users to <b>set</b> new configuration values, <b>get</b> existing ones, <b>remove</b> unnecessary entries, and <b>list</b> all current settings. A key feature is its ability to handle sensitive data through the <i>--secret</i> option, ensuring that values like passwords or tokens are encrypted and stored securely, preventing them from being exposed in plaintext. This separation of configuration from code promotes reusability, enhances security, and simplifies the management of infrastructure-as-code projects across various operational contexts. Configuration changes typically necessitate running <i>pulumi up</i> to apply them to your deployed resources.


title: CAVEATS
content:
Configuration values are specific to each Pulumi stack. Changing configuration values, especially sensitive ones, typically requires a <i>pulumi up</i> operation to propagate these changes to your deployed cloud resources. Sensitive values encrypted with <i>--secret</i> can only be decrypted and displayed if the correct stack encryption passphrase is known and provided.


title: SECRETS MANAGEMENT
content:
The <i>--secret</i> option is vital for securing sensitive data such as API keys, database credentials, or private access tokens. When a value is set as a secret, Pulumi encrypts it before storing it in the stack's configuration file (e.g., <i>Pulumi.<stack-name>.yaml</i>). Decryption requires the stack's encryption passphrase, which can be managed by the Pulumi Cloud or provided by the user. This feature significantly enhances the security posture of infrastructure deployments.


title: PATH-BASED CONFIGURATION
content:
The <i>--path</i> option enables structuring configuration values hierarchically, similar to JSON paths. For example, <i>pulumi config set myService:database:url "mysql://localhost:3306/mydb" --path</i> allows you to define nested configuration objects. This approach improves organization and readability, especially in complex projects with many inter-related configuration settings.


title: HISTORY
content:
Pulumi, founded in 2017, developed the Pulumi CLI as a core tool for managing cloud infrastructure using familiar programming languages. The <i>pulumi config</i> command has been an integral part of the CLI since its early days, addressing the fundamental need for robust configuration management in infrastructure as code. It evolved with Pulumi's focus on secure and reproducible deployments, solidifying its role in handling environment-specific parameters and sensitive data.


title: PARAMETERS
content:
<b><i>[stack]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the stack to destroy. If omitted, the currently selected stack will be used.<br><br><b><b>--yes</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skip the confirmation prompt and proceed with the destroy operation automatically. Use with extreme caution, especially in automated scripts.<br><br><b><b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force deletion of protected resources. By default, Pulumi prevents accidental deletion of resources marked as protected. This flag overrides that protection. Use with extreme caution.<br><br><b><b>--target</b> <i><URN></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify one or more resource URNs (Uniform Resource Names) to selectively destroy only those resources. Can be specified multiple times.<br><br><b><b>--target-dependents</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When used with <b>--target</b>, also destroys resources that depend on the specified targets, even if they are not explicitly targeted themselves.<br><br><b><b>--exclude-protected</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not destroy resources that are marked as protected. This is the default behavior, but this flag explicitly reiterates it.<br><br><b><b>--message</b> <i><string></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attach an optional message to the destroy operation, which will be recorded in the stack's history.<br><br><b><b>--parallel</b> <i><number></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allow up to this many resource operations to run in parallel. Defaults to 15.<br><br><b><b>--diff</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a full diff (detailed changes) of the resources that will be destroyed, not just a summary. This is the default behavior for destroy.<br><br><b><b>--refresh</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform a state refresh operation before executing the destroy, ensuring the Pulumi state is in sync with the actual cloud provider state.<br><br><b><b>--skip-preview</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skip the interactive preview step and directly prompt for confirmation to destroy. Does not skip the final confirmation if <b>--yes</b> is not used.<br><br><b><b>--expect-no-changes</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Return an error if any changes are detected during the destroy operation preview. Useful in CI/CD to ensure idempotency or no unintended side effects.<br><br><b><b>--json</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Emit output as JSON. Useful for programmatic consumption.<br><br>


title: DESCRIPTION
content:
The <i>pulumi destroy</i> command is used to tear down all resources managed by a specific Pulumi stack within your cloud provider. When executed, Pulumi performs a preview to show which resources will be destroyed, prompting for confirmation before proceeding. This operation is irreversible and removes the infrastructure defined in your Pulumi program from the cloud, along with the corresponding state entries in the Pulumi state file. It is crucial to use this command with caution, especially in production environments, as it permanently deletes resources. The command interacts directly with your configured cloud provider (e.g., AWS, Azure, GCP, Kubernetes) using your credentials to delete the provisioned infrastructure. It is an essential part of the Pulumi lifecycle, allowing developers to clean up resources after development, testing, or when an environment is no longer needed.


title: CAVEATS
content:
The <i>pulumi destroy</i> command performs an irreversible operation that permanently deletes cloud resources. <br> <b>Data Loss:</b> Any data stored within the destroyed resources (e.g., databases, storage buckets) will be lost. Ensure backups are taken if necessary. <br> <b>Dependency Conflicts:</b> If resources managed by Pulumi have external dependencies not managed by the same stack, deleting them might break other systems. <br> <b>Protected Resources:</b> Use the <b>--force</b> flag with extreme caution, as it overrides built-in protections against accidental deletion of critical resources. It is recommended to understand the implications of this flag. <br> <b>Cloud Credentials:</b> The command requires valid cloud provider credentials configured in your environment to perform actions. <br> <b>State File:</b> While <i>destroy</i> removes resources from the cloud, the stack's state file will still exist (though empty of resources). To remove the stack entirely, follow up with <i>pulumi stack rm</i>.


title: CONFIRMATION PROMPT
content:
By default, <i>pulumi destroy</i> presents a detailed preview of all resources to be destroyed and prompts for explicit confirmation before proceeding. This interactive step is a critical safety measure to prevent accidental deletion of infrastructure. To bypass this prompt for automation purposes, the <b>--yes</b> flag can be used.


