# CommandSection

title: CONFIGURATION FILES
content:
<b>phpcs</b> supports project-specific configuration via XML files named <i>phpcs.xml</i> or <i>phpcs.xml.dist</i> located in the project's root directory. These files allow users to define default coding standards, include or exclude specific sniffs, ignore certain paths, and set various other options, ensuring consistent scanning behavior across different development environments.


title: INTEGRATION WITH IDES AND CI/CD
content:
<b>phpcs</b> is widely integrated into modern Integrated Development Environments (IDEs) like <i>PhpStorm</i> and <i>VS Code</i>, providing real-time linting and immediate feedback on coding standard violations as code is written. Furthermore, it is a common fixture in Continuous Integration and Continuous Delivery (CI/CD) pipelines (e.g., <i>Jenkins</i>, <i>GitHub Actions</i>), where it automates code quality checks as part of the build or deployment process, helping to maintain high code quality before merging or deploying code.


title: HISTORY
content:
<b>PHP_CodeSniffer</b> was originally developed by Squiz and first released in 2006, quickly becoming a fundamental tool for enforcing coding standards in the PHP ecosystem. Its development has been closely tied to the evolution of PHP coding practices, notably by incorporating and influencing standards from the <i>PHP-FIG (Framework Interop Group)</i>, such as <i>PSR-1</i>, <i>PSR-2</i>, and later <i>PSR-12</i>. Initially distributed via PEAR, its installation largely transitioned to Composer, reflecting modern PHP dependency management practices. Over the years, it has seen continuous improvement in performance, extensibility, and the breadth of its built-in sniffs, solidifying its position as the go-to utility for PHP code quality checks.


title: SEE ALSO
content:
<b>phpcbf</b>(1): PHP Code Beautifier and Fixer, the companion tool for automatically fixing detected coding standard violations., <b>grep</b>(1): A command-line utility for searching plain-text data sets for lines that match a regular expression. Useful for filtering <b>phpcs</b> output., <b>find</b>(1): Searches for files in a directory hierarchy. Can be used to generate lists of files for <b>phpcs</b> to scan., <b>xargs</b>(1): Builds and executes command lines from standard input. Often used with <b>find</b> to pipe file lists to <b>phpcs</b>.


title: PARAMETERS
content:
<b><i>&lt;module&gt;</i> [<i>&lt;module&gt;</i>...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more names of the PHP modules to be disabled (e.g., <i>xdebug</i>, <i>opcache</i>).<br><br><b>-v <i>&lt;version&gt;</i>, --version <i>&lt;version&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the PHP version for which the module should be disabled (e.g., <i>7.4</i>, <i>8.1</i>). Use <i>ALL</i> to affect all installed PHP versions.<br><br><b>-s <i>&lt;sapi_name&gt;</i>, --sapi <i>&lt;sapi_name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the SAPI (Server API) name for which the module should be disabled (e.g., <i>apache2</i>, <i>cli</i>, <i>fpm</i>). Use <i>ALL</i> to affect all configured SAPIs for the specified version.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief help message and exits.<br><br><b>-q, --quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses output messages during execution.<br><br>


title: DESCRIPTION
content:
The <b>phpdismod</b> command is a utility primarily found on Debian-based Linux distributions, part of the <i>php-common</i> package. It is used to disable PHP modules for one or more specific Server API (SAPI) configurations. This command acts as the counterpart to <b>phpenmod</b>, which is used to enable modules.<br><br>When a PHP module is installed, its configuration file (e.g., <i>opcache.ini</i>) is typically placed in a <i>mods-available</i> directory for each PHP version and SAPI. <b>phpdismod</b> works by removing the symbolic link from the <i>conf.d</i> directory (where PHP reads its active configurations) back to the <i>mods-available</i> directory, effectively disabling the module for the specified SAPI.<br><br>This tool simplifies PHP module management, especially in environments with multiple PHP versions or different SAPIs (like Apache, CLI, or FPM), by automating the process of enabling or disabling extensions without manual symlink manipulation. It requires superuser privileges to operate.


title: CAVEATS
content:
<ul><li><b>Permissions:</b> <b>phpdismod</b> requires root or superuser privileges to modify system configuration files. Use with <b>sudo</b>.</li><li><b>Server Reload:</b> After disabling a module, a web server (e.g., Apache, Nginx) or PHP-FPM service restart/reload is typically required for changes to take effect in the respective SAPI environments. CLI changes are immediate.</li><li><b>Module Availability:</b> The module configuration file must exist in the <i>mods-available</i> directory for <b>phpdismod</b> to manage it. If the module is not installed, the command cannot disable it.</li><li><b>'ALL' Usage:</b> Using <i>ALL</i> with <b>-v</b> or <b>-s</b> affects all relevant versions or SAPIs. Exercise caution to avoid unintended widespread changes.</li></ul>


title: WORKING MECHANISM
content:
<b>phpdismod</b> operates by managing symbolic links. For each PHP version and SAPI, module configuration files (e.g., <i>opcache.ini</i>) are stored in <i>/etc/php/&lt;version&gt;/mods-available/</i>. When a module is enabled by <b>phpenmod</b>, a symbolic link is created in the SAPI-specific configuration directory (e.g., <i>/etc/php/&lt;version&gt;/apache2/conf.d/</i>). <b>phpdismod</b>'s primary function is to remove this symbolic link, thus preventing PHP from loading the module for that specific SAPI, effectively disabling it.


title: IMPACT ON APPLICATIONS
content:
Disabling a PHP module can impact web applications or CLI scripts that rely on its functionality. For instance, disabling <i>mysqli</i> would prevent PHP scripts from connecting to MySQL databases using that extension, potentially causing application errors. Always ensure that the modules you disable are not critical for your running applications or services.


title: HISTORY
content:
<b>phpdismod</b> emerged as part of the <i>php-common</i> package within Debian and Ubuntu's PHP ecosystem. Its development aimed to standardize and simplify the process of managing PHP extensions across various PHP versions and Server APIs (SAPIs) without requiring manual manipulation of symbolic links or `.ini` files. It became an essential tool for system administrators and developers to toggle PHP modules efficiently, streamlining configuration management since its introduction alongside <b>phpenmod</b>.


title: PARAMETERS
content:
<b><b>--file</b> &lt;<i>file</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative XML configuration file to use, overriding the default <i>phpdox.xml</i>.<br><br><b><b>--source</b> &lt;<i>path</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the source directory containing PHP files to be analyzed, overriding the configuration file's setting.<br><br><b><b>--output</b> &lt;<i>path</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the directory where the generated documentation will be stored, overriding the configuration.<br><br><b><b>--template</b> &lt;<i>path</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a custom template directory or file to use for rendering the documentation.<br><br><b><b>--bootstrap</b> &lt;<i>file</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes a PHP file before the documentation generation process begins. Useful for custom autoloaders or environment setup.<br><br><b><b>--force-build</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces <i>phpdox</i> to perform a complete rebuild of the documentation, ignoring any cached data.<br><br><b><b>--config-only</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Validates the <i>phpdox.xml</i> configuration file and exits without generating documentation.<br><br><b><b>--skip-build</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Parses source code and generates the XML index but skips the actual documentation generation process.<br><br><b><b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses informational output, only showing warnings and errors.<br><br><b><b>--silent</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses all output, including warnings and errors.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the <i>phpdox</i> version information and exits.<br><br><b><b>--help</b>, <b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows a help message detailing command-line options.<br><br>


title: DESCRIPTION
content:
<i>phpdox</i> is a powerful and flexible documentation generator specifically designed for PHP projects. Unlike some other tools, it focuses on statically analyzing your PHP source code to extract API documentation without requiring external runtime execution. Its primary strength lies in generating an intermediate XML representation of your project's structure and DocBlocks, which can then be transformed into various human-readable formats like HTML, LaTeX, or Markdown using different templates or XSLT stylesheets.<br><br>It aims to provide a more streamlined and less configuration-heavy experience compared to some predecessors, making it ideal for integration into automated build processes and continuous integration/delivery (CI/CD) pipelines. By default, <i>phpdox</i> reads its configuration from a <i>phpdox.xml</i> file located in the project root, allowing for highly customizable documentation generation workflows.


title: CAVEATS
content:
<i>phpdox</i> relies heavily on the proper structuring of your PHP DocBlocks (e.g., PSR-5 conventions) for accurate documentation extraction. While it offers flexibility through its XML output, custom transformations require knowledge of XSLT or the chosen template engine (e.g., Twig). Complex projects will almost always require a dedicated <i>phpdox.xml</i> configuration file, as command-line options are primarily for overrides.


title: CONFIGURATION FILE (PHPDOX.XML)
content:
The central element for <i>phpdox</i> operation is the <i>phpdox.xml</i> configuration file, typically located in your project's root directory. This XML file defines everything from source code paths, output directories, excluded files, and custom templates to advanced settings for specific generators (e.g., HTML, XML). It allows for fine-grained control over the documentation generation process.


title: OUTPUT FLEXIBILITY
content:
While <i>phpdox</i> can directly generate HTML documentation, its core strength lies in producing a rich XML representation of your code's API. This XML output can then be transformed using XSLT or other templating engines (like Twig) into virtually any desired format, such as custom HTML layouts, LaTeX for PDF generation, or Markdown for READMEs. This 'transform-from-XML' approach provides superior customization and integration possibilities.


title: INTEGRATION WITH BUILD TOOLS
content:
<i>phpdox</i> is designed to be easily integrated into PHP's popular build and dependency management tools. It's commonly run as a Composer script (e.g., defined in your <i>composer.json</i>'s <code>scripts</code> section) or as a task within a Phing build file. This enables automated documentation updates as part of your project's build or deployment process.


title: HISTORY
content:
<i>phpdox</i> emerged as an alternative to more monolithic PHP documentation tools, aiming for simplicity, speed, and better integration into modern PHP development workflows. Its development focused on generating a machine-readable XML intermediate format, providing unparalleled flexibility for various output formats. It has become a popular choice for developers looking for a robust, configurable, and automated documentation generation solution, especially within CI/CD environments.


title: PARAMETERS
content:
<b><b>-s</b> <I>SAPI</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the PHP Server API (e.g., <i>cli</i>, <i>fpm</i>, <i>apache2</i>) for which the module should be enabled. If omitted, the module is enabled for all active SAPIs.<br><br><b><b>-v</b> <I>VERSION</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the PHP version (e.g., <i>7.4</i>, <i>8.0</i>) for which the module should be enabled. If omitted, the module is enabled for all active PHP versions.<br><br><b><b>-r</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Recommends enabling configuration for <i>php-cgi</i> instead of <i>apache2</i>. Less commonly used.<br><br><b><b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message and exits.<br><br><b><I>module</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the PHP module or extension to enable (e.g., <i>mysqli</i>, <i>gd</i>, <i>intl</i>). Multiple modules can be specified.<br><br>


title: DESCRIPTION
content:
<b>phpenmod</b> is a utility command used primarily on Debian-based Linux distributions to enable PHP modules or extensions for various PHP versions and Server API (SAPI) configurations. It simplifies the process of managing PHP settings by creating symbolic links from the <i>mods-available</i> directory (where module .ini files are stored) to the <i>conf.d</i> directories of specific PHP versions and SAPIs (e.g., <i>cli</i>, <i>fpm</i>, <i>apache2</i>). This ensures that the chosen module is loaded when PHP processes for those SAPIs are started.<br><br>It centralizes PHP module management, preventing the need to manually edit multiple .ini files. After using <b>phpenmod</b>, a restart of the web server (like Apache or Nginx with PHP-FPM) or PHP-FPM service is usually required for the changes to take effect. This command requires root privileges to execute.


title: CAVEATS
content:
This command is primarily available and used on Debian/Ubuntu and their derivative distributions. It requires root (sudo) privileges to modify system-wide PHP configurations. Enabling a module only creates configuration links; a restart of the associated web server (e.g., Apache, Nginx) or PHP-FPM service is necessary for the changes to become active.


title: COMMON USAGE
content:
To enable the <i>gd</i> module for PHP 8.1 FPM: <code>sudo phpenmod -v 8.1 -s fpm gd</code><br>To enable <i>mysqli</i> for all PHP versions and SAPIs: <code>sudo phpenmod mysqli</code>


title: CONFIGURATION FILES
content:
Enabled modules create symlinks in directories like <i>/etc/php/&lt;version&gt;/&lt;sapi&gt;/conf.d/</i> pointing to actual .ini files located in <i>/etc/php/&lt;version&gt;/mods-available/</i>.


title: HISTORY
content:
<b>phpenmod</b> is part of the <i>php-common</i> package, which was introduced in Debian/Ubuntu to standardize and simplify the management of PHP configurations across different PHP versions and SAPIs. Its development is tied to the evolution of PHP packaging within these distributions, aiming to provide a consistent and easy-to-use interface for administrators.


title: PARAMETERS
content:
<b><b>versions</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;List all PHP versions installed by <i>phpenv</i>, indicating the currently active version.<br><br><b><b>version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the currently active PHP version for the current shell or project.<br><br><b><b>global</b> <i>&lt;version&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the default (global) PHP version for all shells. This updates the `~/.phpenv/version` file.<br><br><b><b>local</b> <i>&lt;version&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the PHP version for the current directory and its subdirectories. This creates a `.phpenv-version` file in the current directory.<br><br><b><b>shell</b> <i>&lt;version&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the PHP version for the current shell session only. This overrides global and local settings temporarily.<br><br><b><b>rehash</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Rebuild the <i>phpenv</i> shims. Run this command after installing a new PHP version or any PHP-specific executable (e.g., Composer, Pecl) to make them available.<br><br><b><b>root</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the root directory where <i>phpenv</i> is installed (e.g., `~/.phpenv`).<br><br><b><b>prefix</b> <i>&lt;version&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the installation path for a specific PHP version.<br><br><b><b>which</b> <i>&lt;command&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the full path to the executable that <i>phpenv</i> will run for a given command (e.g., <b>php</b>, <b>composer</b>).<br><br><b><b>exec</b> <i>&lt;command&gt;</i> [ <i>&lt;args&gt;...</i> ]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Execute a command against the currently selected PHP version, bypassing shims.<br><br><b><b>init</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Configure the shell environment for <i>phpenv</i>. This command typically outputs shell initialization code that should be `eval`uated in your shell's startup files (e.g., `.bashrc`, `.zshrc`).<br><br>


title: DESCRIPTION
content:
<i>phpenv</i> is a lightweight command-line tool designed to manage multiple PHP versions on a single development machine. It provides a simple way to switch between different PHP versions globally, per-user, or on a per-project basis. Unlike system-wide installations or package managers, <i>phpenv</i> works by injecting itself into your PATH and using "shims" to intercept calls to PHP executables (like <b>php</b>, <b>composer</b>, <b>pear</b>, <b>pecl</b>). This allows <i>phpenv</i> to direct the command to the appropriate PHP version installed through it, without interfering with system-wide PHP installations. It's particularly useful for developers who need to test their applications against different PHP versions, ensuring compatibility and facilitating development across varied environments. <i>phpenv</i> itself does not install PHP; it often relies on companion tools like <b>php-build</b> or manual compilation for the actual PHP version installation.


title: CAVEATS
content:
<i>phpenv</i> itself does not include functionality to install PHP versions; it relies on companion tools like <b>php-build</b> or manual compilation. Users must ensure <i>phpenv</i> is correctly initialized in their shell's startup files (e.g., `eval "$(phpenv init -)"`) for shims and version switching to work properly. It is primarily designed for local development environments and is generally not recommended for managing PHP on production servers. Care must be taken to avoid conflicts with existing system-wide PHP installations or other PATH configurations.


title: INSTALLATION LOCATION
content:
<i>phpenv</i> is typically installed by cloning its Git repository into `~/.phpenv`. PHP versions are then installed into `~/.phpenv/versions/`.


title: HOW SHIMS WORK
content:
<i>phpenv</i> functions by creating 'shims' for PHP executables (e.g., <b>php</b>, <b>composer</b>) in `~/.phpenv/shims`. When a command is executed, the shim intercepts it, and <i>phpenv</i> determines the correct PHP version to use based on global settings, local project files (`.phpenv-version`), or shell-specific environment variables, directing the command to the appropriate installed PHP binary.


title: HISTORY
content:
<i>phpenv</i> emerged as a direct response to the growing need for flexible PHP version management in development environments, mirroring the success of tools like `rbenv` for Ruby and `pyenv` for Python. It was developed to provide a lightweight, non-intrusive method for developers to seamlessly switch between multiple PHP versions for different projects without conflicts or complex system configurations. Since its inception, its focus on simplicity and the use of shims has made it a popular choice for local development, enabling developers to easily test compatibility and manage diverse project requirements.


title: SEE ALSO
content:
pyenv(1): Python version management inspired by `rbenv`., rbenv(1): Ruby version management tool that inspired `phpenv`., nvm(1): Node.js version manager., php(1): The PHP command-line interpreter., composer(1): Dependency manager for PHP.


title: PARAMETERS
content:
<b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Displays a comprehensive help message for <b>phpize</b> usage.</i><br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Shows the version information of the <b>phpize</b> utility.</i><br><br><b><b>--clean</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Removes all files generated by a previous <b>phpize</b> run, such as <b>configure</b>, <b>aclocal.m4</b>, and <b>Makefile.in</b>.</i><br><br>


title: DESCRIPTION
content:
<i><b>phpize</b> is a utility script used to prepare the build environment for PHP extensions. When you have a PHP extension's source code (typically C files), it generates the necessary files, such as a <b>configure</b> script and <b>Makefile.in</b>, from a <b>config.m4</b> file. This process is essential for compiling the extension into a loadable PHP module. It's the crucial first step in the standard build procedure for PHP extensions, ensuring the extension is built against the correct PHP version and configuration. It automates the generation of the build system, making extension compilation straightforward.</i>


title: CAVEATS
content:
<i><b>phpize</b> requires PHP development headers and tools like <b>autoconf</b> and <b>automake</b> to be installed on the system. It only prepares the build system; actual compilation of the extension requires subsequent steps: running the generated <b>configure</b> script and then <b>make</b>. It is specifically designed for PHP extensions.</i>


title: <B>PECL INTEGRATION</B>
content:
<i><b>phpize</b> is fundamental for manually compiling and installing PECL extensions. While PECL often automates the process, <b>phpize</b> is the underlying utility it uses to prepare the extension for building.</i>


title: <B>TYPICAL BUILD WORKFLOW</B>
content:
<i>The typical workflow for compiling a PHP extension using <b>phpize</b> involves several steps:<br>1. Run <b>phpize</b> in the extension's source directory.<br>2. Execute the generated <b>./configure</b> script, optionally with specific PHP installation paths (e.g., <b>--with-php-config=/path/to/php-config</b>).<br>3. Run <b>make</b> to compile the extension.<br>4. Run <b>sudo make install</b> to install the compiled module into PHP's extension directory.</i>


title: HISTORY
content:
<i><b>phpize</b> emerged as a vital component of the PHP build system to standardize the compilation of PHP extensions. Before its widespread adoption, building extensions could be more manual or inconsistent. Its introduction streamlined the process, providing a consistent, automated way to generate build scripts (like <b>configure</b>) from an extension's <b>config.m4</b> file. This standardization greatly facilitated the distribution and installation of PHP extensions, particularly contributing to the ease of use of the PECL (PHP Extension Community Library) repository.</i>


title: PARAMETERS
content:
<b><b>--count-tests</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Counts methods named 'test*' or annotated with '@test' as test methods.<br><br><b><b>--exclude</b> <<i>dir</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Excludes the specified directory from the analysis. Can be used multiple times.<br><br><b><b>--names</b> <<i>pattern</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A comma-separated list of file names to include in the scan (e.g., '*.php').<br><br><b><b>--names-exclude</b> <<i>pattern</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A comma-separated list of file names to exclude from the scan (e.g., '*-old.php').<br><br><b><b>--suffixes</b> <<i>suffix</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A comma-separated list of file suffixes to include (e.g., 'php,inc').<br><br><b><b>--log-xml</b> <<i>file</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the analysis results in XML format to the specified file.<br><br><b><b>--log-csv</b> <<i>file</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the analysis results in CSV format to the specified file.<br><br><b><b>--progress</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a progress bar during the analysis.<br><br><b><b>--fuzzy</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables fuzzy calculation of cyclomatic complexity (experimental feature).<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the help message and exits.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the <b>phploc</b> version and exits.<br><br>


title: DESCRIPTION
content:
<b>phploc</b> is a command-line tool designed to quickly measure the size and analyze the structure of a PHP project. It counts various metrics such as physical lines of code (LOC), logical lines of code, comment lines, number of files, classes, interfaces, traits, methods, functions, and namespaces. Beyond basic counts, it provides insights into complexity by measuring things like cyclomatic complexity, number of dependencies, and usage of constants and anonymous functions. <b>phploc</b> is an invaluable tool for developers and teams seeking to understand the scale of their codebase, track progress, identify potential technical debt, and ensure maintainability. It supports analyzing entire directories or specific files and can output results in various formats, including plain text, XML, and CSV.


title: CAVEATS
content:
<b>phploc</b> is primarily designed for PHP projects and may not yield meaningful results for other languages. While powerful for structural metrics, it does not perform deep semantic analysis like dedicated static analyzers such as <i>PHPStan</i> or <i>Psalm</i>. Performance can be a concern on very large codebases if not configured to exclude irrelevant directories like '<i>vendor/</i>' or '<i>node_modules/</i>'. It requires PHP to be installed and <b>phploc</b> to be available, typically via Composer.


title: TYPICAL USE CASES
content:
<b>phploc</b> is frequently integrated into CI/CD pipelines to monitor code size and complexity trends over time. It's excellent for performing quick audits of new or legacy PHP projects to understand their scale and structure. The insights gained can guide refactoring efforts by highlighting large or overly complex components that might require attention for improved maintainability.


title: OUTPUT FORMATS
content:
By default, <b>phploc</b> provides a human-readable text output to the console. For machine readability and seamless integration with other tools or dashboards, it supports writing results in XML via the <b>--log-xml</b> option and CSV via the <b>--log-csv</b> option. These structured formats allow for easy parsing, historical data tracking, and visual representation of code metrics.


title: HISTORY
content:
<b>phploc</b> was created by <I>Sebastian Bergmann</I>, renowned for his work on <I>PHPUnit</I>, the de-facto standard unit testing framework for PHP. It emerged from the need for a simple, fast tool to get an overview of PHP project metrics, complementing more in-depth static analysis tools. Since its initial release, it has been regularly updated to support newer PHP versions and integrate into the broader PHP ecosystem, often used alongside other development tools like <I>PHP_CodeCoverage</I> and <I>PHP_Depend</I>. Its development reflects a focus on actionable metrics for code quality and maintainability.


title: SYNOPSIS
content:
<b>phpmd</b> <I>source</I> <I>format</I> <I>ruleset</I> [<I>options</I>]<br><br>Where:<br><I>source</I>: A comma-separated list of files and/or directories to analyze. Example: `src/,tests/unit/MyClass.php`<br><I>format</I>: The format of the report. Common formats include `xml`, `text`, `html`, `json`, `gitlab`, `github`, `checkstyle`.<br><I>ruleset</I>: A comma-separated list of built-in ruleset names or paths to custom XML ruleset files. Example: `cleancode,codesize,unusedcode` or `/path/to/my_rules.xml`


title: PARAMETERS
content:
<b><I>source</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A comma-separated list of files and/or directories to analyze (required).<br><br><b><I>format</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The output format of the report (e.g., `xml`, `text`, `html`, `json`) (required).<br><br><b><I>ruleset</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A comma-separated list of built-in ruleset names or paths to custom XML ruleset files (required).<br><br><b>--minimumpriority <integer></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reports problems with a priority at or higher than this value (1-5, 1 being highest).<br><br><b>--reportfile <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the generated report to the specified file instead of standard output.<br><br><b>--suffixes <extensions></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Comma-separated list of valid source code filename extensions (default: `php`).<br><br><b>--exclude <directories></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Comma-separated list of directories to exclude from analysis.<br><br><b>--strict</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not ignore exceptions occurring during analysis.<br><br><b>--ignore-errors</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ignore analysis errors and continue with the analysis.<br><br><b>--ignore-violations-on-exit</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not exit with a non-zero code if violations are found.<br><br><b>--generate-baseline <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a baseline file with current violations to ignore in future runs.<br><br><b>--baseline <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses the specified baseline file to ignore existing violations.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the help message and exits.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases verbosity of output messages.<br><br><b>-V, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays program version and exits.<br><br>


title: DESCRIPTION
content:
PHP Mess Detector (PHPMD) is a static analysis tool designed to inspect PHP source code for common programming errors, suboptimal code, complex code, and unused parameters, properties, and methods.<br><br>It helps developers identify and eliminate potential code smells, improving the overall quality, maintainability, and readability of their applications. PHPMD works by applying a set of configurable rulesets to the codebase and reporting any violations found, making it an invaluable tool for enforcing coding standards and best practices, especially within continuous integration/continuous delivery (CI/CD) pipelines.


title: CAVEATS
content:
PHPMD might occasionally produce <I>false positives</I>, flagging valid code as problematic. It also requires a PHP runtime environment to execute.<br><br>For very large codebases, the analysis can be time-consuming, and careful configuration of rulesets and exclusion patterns is necessary to yield relevant results and optimize performance.


title: RULESETS
content:
PHPMD ships with several built-in rulesets, each targeting a specific type of code smell:<br> - <I>cleancode</I>: Rules for common clean code violations.<br> - <I>codesize</I>: Rules for excessively long/complex code.<br> - <I>controversial</I>: Rules that might be subject to debate but often indicate issues.<br> - <I>design</I>: Rules for potential design flaws.<br> - <I>naming</I>: Rules for problematic naming conventions.<br> - <I>unusedcode</I>: Rules for detecting unused parameters, properties, and methods.<br><br>Users can also create custom rulesets in XML format to tailor analysis to their specific needs.


title: OUTPUT FORMATS
content:
PHPMD supports various output formats to integrate with different tools and workflows, including `xml`, `text`, `html`, `json`, `gitlab`, `github`, and `checkstyle`, allowing for flexible reporting and integration into IDEs or CI systems.


title: HISTORY
content:
PHPMD was created by Manuel Pichler as a companion tool to PHP_CodeSniffer, focusing on detecting "mess" rather than just coding standard violations.<br><br>It fills a crucial gap in the PHP quality assurance ecosystem, enabling developers to identify and refactor problematic code patterns early in the development cycle. Its usage has grown steadily, particularly in automated build and continuous integration environments, becoming a standard component of many PHP development workflows.


title: SYNOPSIS
content:
Since <i>phpQuery</i> is a PHP library, it is executed indirectly via the PHP interpreter. The general synopsis for using a PHP script that incorporates <i>phpQuery</i> from the command line is:<br><br><i><b>php</b></i> [<i>PHP_OPTIONS</i>] <i><b><I>your_script.php</I></b></i> [<i>SCRIPT_ARGUMENTS...</i>]<br><br>Here, <i><b><I>your_script.php</I></b></i> is a custom PHP file that includes and uses the <i>phpQuery</i> library to perform its tasks.


title: PARAMETERS
content:
<b><I>-f <FILENAME></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes the specified PHP <i><FILENAME></i>. This is the common way to run a PHP script using <i>phpQuery</i> from the command line.<br><br><b><I>-r <code></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes the given PHP <i><code></i> string directly. Useful for quick one-liners involving <i>phpQuery</i>, typically requiring the library to be autoloaded or explicitly included.<br><br><b><I>-- <ARG1> <ARG2>...</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Marks the end of PHP options and treats all subsequent arguments as script arguments. These are passed directly to your <i>phpQuery</i>-enabled script and can be accessed via the <i><B>$argv</B></i> array within the script.<br><br><b><i><I>Script-defined arguments</I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Any custom PHP script using <i>phpQuery</i> can define and parse its own command-line arguments (e.g., <i><I>--input-file</I></i>, <i><I>--selector</I></i>, <i><I>--output-format</I></i>). These are handled by the script's internal logic, not by <i>phpQuery</i> directly.<br><br>


title: DESCRIPTION
content:
<i>phpQuery</i> is a <b>powerful PHP library</b> that provides a fluent interface for <i>DOM traversal and manipulation</i>, highly inspired by the popular JavaScript library <i>jQuery</i>. Unlike a traditional Linux command-line tool, <i>phpQuery</i> is not a standalone executable. Instead, it is integrated into PHP scripts, allowing developers to programmatically interact with HTML and XML documents. Its primary use cases include <b>web scraping, parsing HTML data, modifying document structures, and extracting specific content</b> using familiar CSS selector syntax. When used from the command line, it involves executing a PHP script that utilizes the <i>phpQuery</i> library to process data piped into standard input, read from files, or fetched from URLs, providing a flexible way to automate web content processing tasks.


title: CAVEATS
content:
<ul><li><i><b>Library, Not Executable:</b></i> <i>phpQuery</i> is a PHP library. There is no standalone <i><b>phpquery</b></i> binary to execute directly. Usage requires a PHP interpreter and a PHP script that incorporates the library.</li><li><i><b>PHP Dependency:</b></i> Requires a working PHP installation (typically <i>PHP 5.3+</i>, though newer versions might have compatibility issues without polyfills, as the library is not actively maintained for the latest PHP releases).</li><li><i><b>Performance & Memory:</b></i> Parsing very large HTML/XML documents can be memory-intensive, as <i>phpQuery</i> builds an in-memory DOM representation.</li><li><i><b>Maintenance Status:</b></i> While still functional, <i>phpQuery</i> is not as actively maintained as it once was. More modern PHP alternatives like <i>Symfony DomCrawler</i> or <i>Goutte</i> (which builds on DomCrawler) are often preferred for new projects due to ongoing development and better support for modern PHP versions.</li></ul>


title: <I>INSTALLATION</I>
content:
<i>phpQuery</i> can be installed by downloading the library files and including them in your PHP project. The recommended method for modern PHP projects is via <i><b>Composer</b></i>, by adding <i><B>"electrolinux/phpquery": "*"</B></i> to your <i><B>composer.json</B></i> dependencies and then running <i><B>composer install</B></i>.


title: <I>BASIC COMMAND-LINE USAGE EXAMPLE</I>
content:
To demonstrate <i>phpQuery</i> usage from the command line, consider a PHP script named <i><B>parse_html.php</B></i>:<br><br><i>&lt;?php<br>require_once 'vendor/autoload.php'; // If using Composer<br>// Or: require_once 'phpQuery.php'; // Manual include<br><br>$html = file_get_contents('php://stdin'); // Read from stdin<br>$doc = phpQuery::newDocument($html);<br><br>// Find all &lt;a&gt; tags and print their href attributes<br>pq('a')->each(function($i, $el) {<br>    echo pq($el)->attr('href') . "\n";<br>});<br>?></i><br><br>You can then run this script from the command line like:<br><i><B>curl https://example.com | php parse_html.php</B></i><br>or<br><i><B>cat input.html | php parse_html.php</B></i><br>This example parses HTML from standard input and extracts all link <i><B>href</B></i> attributes.


title: HISTORY
content:
<i>phpQuery</i> was initially developed around <b>2008-2009</b>, drawing significant inspiration from the hugely successful <i>jQuery</i> JavaScript library. Its goal was to bring <i>jQuery</i>'s elegant and powerful DOM manipulation capabilities to the PHP environment, making it much easier for PHP developers to parse, traverse, and modify HTML/XML documents. It quickly gained popularity in the PHP community, particularly for <b>web scraping and content manipulation tasks</b>, due to its intuitive CSS selector syntax and chainable methods. While it played a crucial role in its time, its development slowed down in the mid-2010s, with newer, more actively maintained libraries emerging as preferred alternatives for modern PHP applications.


title: SYNOPSIS
content:
<b>phpspec</b> [<i>global_options</i>] [<i>command</i>] [<i>command_arguments</i>]<br><br>Common commands:<br><b>phpspec run</b> [<i>options</i>] [<i>spec_path</i>]<br><b>phpspec desc</b> <<i>class_name</i>> [<i>options</i>]<br><b>phpspec init</b>


title: PARAMETERS
content:
<b><b>--help</b>, <b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help for the current command.<br><br><b><b>--quiet</b>, <b>-q</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not output any message.<br><br><b><b>--verbose</b>, <b>-v|-vv|-vvv</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increase the verbosity of messages. <b>-v</b> for normal output, <b>-vv</b> for more verbose output, <b>-vvv</b> for debug.<br><br><b><b>--version</b>, <b>-V</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the application version.<br><br><b><b>--ansi</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force ANSI output.<br><br><b><b>--no-ansi</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable ANSI output.<br><br><b><b>--no-interaction</b>, <b>-n</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not ask any interactive question.<br><br><b><b>--config</b>, <b>-c</b> <<i>path</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a custom path to the configuration file (e.g., <i>phpspec.yml</i>).<br><br><b><b>--no-progress</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not show the progress bar during spec execution.<br><br><b><b>--format</b>, <b>-f</b> <<i>format</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the output format for the 'run' command (e.g., <i>pretty</i>, <i>junit</i>, <i>html</i>).<br><br><b><b>--stop-on-failure</b>, <b>--fail-fast</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stop running upon the first encountered failure.<br><br><b><b>--no-code-generation</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents <i>phpspec</i> from generating missing classes or methods during the 'run' command.<br><br><b><b>--filter</b> <<i>pattern</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filter specifications to run based on a regular expression pattern.<br><br>


title: DESCRIPTION
content:
<i>phpspec</i> is a Behavior-Driven Development (BDD) framework for PHP. Unlike traditional unit testing frameworks that focus on testing individual units of code, <i>phpspec</i> helps developers describe and verify the behavior of their applications from the perspective of their specifications.<br><br>It encourages a design-first approach, where specifications (written as executable examples) drive the development process. <i>phpspec</i> focuses on how objects collaborate and respond to messages, making it excellent for understanding object interactions and designing robust, well-defined APIs.<br><br>A key feature is its ability to generate code (classes and methods) based on the specifications, facilitating a red-green-refactor cycle. It also provides powerful test doubles (called 'spec doubles') to isolate the code under specification from its dependencies, promoting clean, testable design. By focusing on behavior, <i>phpspec</i> helps ensure that code not only works but also meets the intended requirements and expectations.


title: CAVEATS
content:
<i>phpspec</i> is typically installed via Composer as a dev dependency within a project. It focuses strongly on Behavior-Driven Development and design by example, which may require a shift in mindset compared to traditional unit testing. While it can verify individual units, its strength lies in defining and verifying object collaborations and behaviors.


title: CONFIGURATION FILE (PHPSPEC.YML)
content:
<i>phpspec</i> typically uses a <i>phpspec.yml</i> or <i>phpspec.yml.dist</i> file in the project root for configuration. This file allows you to define suites, formatters, code generation rules, and other global settings, tailoring <i>phpspec</i>'s behavior to your project's needs.


title: CODE GENERATION WORKFLOW
content:
One of <i>phpspec</i>'s unique features is its ability to generate code. When you run a spec (e.g., <b>phpspec run</b>) for a class or method that doesn't exist, <i>phpspec</i> will prompt you to create it. This 'red-green' workflow encourages you to define the desired behavior first (red test), then generate the necessary code (passing the test), and finally refactor.


title: SPEC DOUBLES (TEST DOUBLES)
content:
<i>phpspec</i> uses 'spec doubles' (similar to mocks or stubs) to manage dependencies. These are objects that stand in for real dependencies, allowing you to isolate the behavior under test. You define their expected interactions and return values, ensuring that your specifications focus solely on the object being specified, not its collaborators' internal workings.


title: HISTORY
content:
<i>phpspec</i> was created by Konstantin Kudryashov, the same developer behind <i>Behat</i>. It was inspired by <i>RSpec</i> from the Ruby world, bringing similar BDD principles to PHP development. Initially gaining traction in the early 2010s, it provided an alternative to PHPUnit for developers wanting to adopt a more behavior-driven approach to testing and design, emphasizing specifications and example-based development over pure unit isolation.


title: SYNOPSIS
content:
<b>phpstorm</b> [<i>OPTIONS</i>] [<i>PATH</i>]<br><b>phpstorm</b> [<i>OPTIONS</i>] <i>FILE</i>[:<i>LINE</i>[:<i>COLUMN</i>]]<br><b>phpstorm</b> <i>--diff</i> <i>PATH1</i> <i>PATH2</i>


title: PARAMETERS
content:
<b>[PATH] or .</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens a project located at <i>PATH</i> or the current directory ('.').<br><br><b>FILE[:LINE[:COLUMN]]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens a specific file, optionally navigating to a specific line and column within that file.<br><br><b>--help, -h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message with available command-line options.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the PhpStorm version information.<br><br><b>--diff <PATH1> <PATH2></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens a file comparison window for the two specified files or directories.<br><br><b>--line <NUMBER></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with <i>FILE</i> to specify the line number to open. Requires a file path argument.<br><br><b>--column <NUMBER></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with <i>FILE</i> and <i>--line</i> to specify the column number to open. Requires a file path and line number.<br><br><b>--wait</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Keeps the shell process running until the IDE is closed. Useful for integration with external tools (e.g., Git hooks).<br><br><b>--temp-project</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens the specified directory as a temporary project, without adding it to the recent projects list.<br><br><b>--project <PATH></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens the IDE with a specific <i>.ipr</i> or <i>.idea</i> project file located at <i>PATH</i>.<br><br><b>--args <JVM_ARGUMENT></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Passes arguments directly to the Java Virtual Machine (JVM) that runs PhpStorm. For advanced use cases.<br><br><b>--disable-plugin <PLUGIN_ID></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables a specific plugin by its ID upon startup.<br><br><b>--settings <PATH_TO_SETTINGS_FILE></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative path to the IDE's settings directory for portable or specialized configurations.<br><br>


title: DESCRIPTION
content:
The <b>phpstorm</b> command is the primary entry point for launching the JetBrains PhpStorm integrated development environment (IDE) on Linux. PhpStorm is a powerful, cross-platform IDE specifically designed for PHP and web development. It provides intelligent code completion, on-the-fly error checking, debugging, refactoring tools, version control integration, and support for various web technologies like HTML, CSS, JavaScript, TypeScript, and popular frameworks.<br><br>When executed without arguments, <b>phpstorm</b> typically opens the IDE to the last opened project or the welcome screen. Users can specify paths to projects, files, or directories to open them directly within the IDE. The command also supports various options to control IDE behavior, such as opening files at specific lines, performing diff operations, or waiting for the IDE to close before returning control to the terminal. It's often located in <i>/usr/local/bin</i> or within the installation directory's <i>bin</i> subdirectory, and its availability depends on whether PhpStorm has been installed and its executable linked to the system's PATH.


title: CAVEATS
content:
<b>GUI Requirement:</b> PhpStorm is a graphical application; thus, running the <b>phpstorm</b> command requires an active graphical user interface (GUI) environment. It cannot be run purely from a command-line interface without display capabilities.<br><b>Installation Path:</b> The <b>phpstorm</b> command must be accessible in your system's PATH environment variable. If not, you might need to execute it from its installation directory (e.g., <i>/opt/PhpStorm/bin/phpstorm.sh</i>) or create a symbolic link.<br><b>Resource Intensive:</b> As a full-featured IDE, PhpStorm can be resource-intensive, requiring significant RAM and CPU, especially for large projects.<br><b>Licensing:</b> PhpStorm is a commercial product and requires a valid license after a trial period.


title: CONFIGURATION DIRECTORY
content:
PhpStorm stores its configuration, caches, and logs in specific directories, typically under <i>~/.config/JetBrains/PhpStorm&lt;version&gt;</i> and <i>~/.cache/JetBrains/PhpStorm&lt;version&gt;</i> on Linux. These directories can sometimes be useful for troubleshooting or resetting IDE settings.


title: SHELL SCRIPT WRAPPER
content:
The <b>phpstorm</b> command on Linux is often a shell script (e.g., <i>phpstorm.sh</i>) located in the <i>bin</i> subdirectory of the installation. This script sets up the Java environment and launches the actual Java application, allowing for environment variable manipulation before launching the IDE.


title: JETBRAINS TOOLBOX APP
content:
JetBrains provides a 'Toolbox App' for managing and updating its IDEs. When installed via Toolbox, the command-line launchers for IDEs like PhpStorm are typically managed automatically and placed in a convenient location in the user's PATH, simplifying setup and updates.


title: HISTORY
content:
PhpStorm is developed by JetBrains, a Czech software development company. The first public release of PhpStorm was in 2009. It was built on top of the IntelliJ IDEA platform, which itself was first released in 2001. This lineage means PhpStorm benefits from a mature and robust IDE architecture, sharing many core features, user interface elements, and plugin capabilities with other JetBrains IDEs. Its development has continuously focused on deep understanding of PHP language features, frameworks, and web technologies, evolving alongside the PHP ecosystem to provide cutting-edge development tools. The command-line interface has been a consistent feature across JetBrains IDEs, allowing for integration with various developer workflows and external tools.


title: PARAMETERS
content:
<b><b>-p</b>, <b>--prompt</b> <I>TEXT</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the prompt text displayed to the user when the console is locked.<br><br><b><b>-t</b>, <b>--timeout</b> <I>SECONDS</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an unlock timeout in seconds. If no input is received within this time, the system can be configured to take a specific action (e.g., suspend).<br><br><b><b>-u</b>, <b>--users</b> <I>USERS</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A comma-separated list of users who are allowed to unlock the console. Defaults to <i>root</i> and the current user.<br><br><b><b>-s</b>, <b>--suspend</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suspends the system (to RAM) after successfully locking the console. This is a very common use case for <b>physlock</b>.<br><br><b><b>-f</b>, <b>--force-suspend</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces system suspend, even if the underlying console locking command fails. Use with caution.<br><br><b><b>-L</b>, <b>--lock-command</b> <I>COMMAND</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the command to execute for locking the console. Defaults to <i>vlock --all</i>.<br><br><b><b>-U</b>, <b>--unlock-command</b> <I>COMMAND</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a command to execute immediately <i>before</i> the console is unlocked.<br><br><b><b>-e</b>, <b>--exec-on-unlock</b> <I>COMMAND</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes the specified command immediately <i>after</i> successful unlock.<br><br><b><b>-x</b>, <b>--exit-on-unlock</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exits <b>physlock</b> after successful unlock (this is often the default behavior).<br><br><b><b>-c</b>, <b>--clear-screen</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Clears the screen before displaying the lock prompt, ensuring no previous output is visible.<br><br><b><b>-D</b>, <b>--disable-dpms</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables DPMS (Display Power Management Signaling) while the console is locked, preventing the screen from turning off.<br><br><b><b>-d</b>, <b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables debug output, which can be useful for troubleshooting issues.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message with command usage and options, then exits.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information for <b>physlock</b>, then exits.<br><br>


title: DESCRIPTION
content:
<b>physlock</b> is a lightweight utility designed to securely lock a physical console (TTY) on a Linux system, often used in conjunction with suspend or hibernation operations. Unlike graphical screen lockers, <b>physlock</b> operates at the console level, preventing unauthorized access to the TTYs when the system resumes.<br><br>It acts as a wrapper around underlying console locking mechanisms like <i>vlock</i>, ensuring that a password is required before the console can be used again. This is particularly useful for systems configured with full disk encryption (e.g., LUKS), where the console might otherwise be accessible without re-entering the passphrase after a suspend-to-RAM operation. Its primary goal is to maintain physical security for the console, especially when the system is in a low-power state.


title: CAVEATS
content:
<ul><li><b>physlock</b> primarily targets <i>physical console</i> (TTYs) locking and is not a graphical screen locker. For X11 or Wayland sessions, use dedicated graphical lockers like <i>i3lock</i> or <i>gnome-screensaver</i>.</li><li>It typically relies on external utilities like <i>vlock</i> to perform the actual console locking. Ensure these utilities are installed and functional on your system.</li><li>Effective console locking usually requires root privileges or appropriate capabilities to interact with TTY devices securely.</li><li>While useful for preventing unauthorized access after suspend, <b>physlock</b> does not encrypt or protect data in RAM during suspend-to-RAM operations. For that, consider suspend-to-disk (hibernate) with full disk encryption.</li></ul>


title: TYPICAL USE CASE WITH SUSPEND
content:
A common scenario for <b>physlock</b> is to integrate it with system suspend/hibernate. For example, a systemd service or a custom script can be configured to execute <i>physlock --suspend</i> just before the system goes to sleep. Upon resume, <b>physlock</b> will present a password prompt, requiring authentication before the console becomes usable again. This significantly enhances security for systems with disk encryption, as it prevents bypassing the encryption passphrase simply by suspending and resuming.


title: HISTORY
content:
<b>physlock</b> was developed to address a critical security gap in Linux systems that utilize full disk encryption (like LUKS) and suspend to RAM. Without a console locker, resuming from suspend could expose an unprotected console, potentially allowing unauthorized access to the system without re-entering the disk encryption passphrase. <b>physlock</b> emerged as a simple, effective solution to bridge this gap, often integrated into system suspend hooks or pre-suspend scripts, ensuring that the console is locked before the system enters a low-power state.


title: PARAMETERS
content:
<b>-p <digits></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the number of decimal places for Pi's output. Defaults to a reasonable standard precision if not specified.<br><br><b>-r</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the raw numerical value of Pi without additional formatting (e.g., newline).<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;Displays version information and exits.<br><br>


title: DESCRIPTION
content:
The `pi` command, <i>while not a standard utility found in most Linux distributions</i>, is conceptualized as a simple command-line tool dedicated to outputting the numerical value of the mathematical constant Pi (π). Its primary function would be to provide this constant readily for various computational, scripting, or educational purposes. Users would likely have the option to specify the desired precision, allowing for a wide range of decimal places, from a few for quick checks to hundreds or thousands for high-precision calculations. The command could also offer formatting options, such as raw numerical output, scientific notation, or potentially unit-aware representations. Its existence would streamline accessing Pi compared to using general-purpose calculators like <b>bc</b> or <b>awk</b> with specific mathematical functions, offering a direct and focused utility. This type of functionality is often achieved via custom shell scripts or aliases.


title: CAVEATS
content:
The `pi` command is <i>not a standard or commonly pre-installed utility</i> in most mainstream Linux distributions. Users typically calculate Pi using commands like <b>bc -l</b> (e.g., <br><code>echo "scale=50; 4*a(1)" | bc -l</code>) or by leveraging mathematical functions in programming languages or scripting environments. Any direct `pi` command would likely be a custom script, an alias, or part of a specialized mathematical software suite. Its availability and features would depend entirely on its specific implementation.


title: CALCULATING PI WITH BC
content:
To obtain Pi with high precision using the standard <b>bc</b> command, you can use the formula <br><code>echo "scale=N; 4*a(1)" | bc -l</code>,<br>where 'N' is the desired number of decimal places. The <code>-l</code> option loads the standard math library, which includes the arctangent function <code>a()</code>.


title: SCRIPTING PI
content:
Users often create simple shell scripts named <code>pi</code> in their personal <code>~/bin</code> directory. These scripts typically accept a precision argument and then use <b>bc</b> internally to compute and print the value, making it appear as if a direct <code>pi</code> command exists in their environment.


title: HISTORY
content:
The concept of a dedicated `pi` command stems from the frequent need for the constant Pi in various computations. While early Unix-like systems and modern Linux distributions provide powerful mathematical tools like <b>bc</b> and <b>awk</b>, a direct command for Pi streamlines access. Historically, users would often write small shell scripts or functions to wrap <b>bc</b> commands (e.g., <br><code>pi() { echo "scale=$1; 4*a(1)" | bc -l; }</code>) to achieve similar functionality. A standalone `pi` command would represent a specialization of this common computational task into a single, dedicated utility, reflecting a user-driven demand for simplicity in accessing fundamental mathematical constants.


title: DESCRIPTION
content:
The <b>pi3topbm</b> command is a specialized utility included within the comprehensive Netpbm suite of graphics tools. Its primary function is to convert image files from the Macintosh PICT version 3 format into the Portable Bitmap (PBM) format, a fundamental component of the Netpbm image standards. The command operates by reading the input PICT file, which can be provided via standard input or as a specified filename argument, and subsequently writes the resulting PBM image data to standard output. This tool is specifically designed to handle PICT version 3 files that encapsulate bitmap or pixmap data. It's important to note that <b>pi3topbm</b> does not support PICT files that rely on Quickdraw opcodes for rendering or those that contain vector graphics. Furthermore, in cases where a PICT file might contain multiple distinct images, <b>pi3topbm</b> is designed to process and convert only the very first image found within the input file.


title: CAVEATS
content:
<b>pi3topbm</b> has the following limitations:<br>- Only Macintosh PICT version 3 files containing bitmap or pixmap data are supported. PICT files with Quickdraw opcodes or vector graphics are not converted.<br>- If the input PICT file contains multiple images, <b>pi3topbm</b> will only process and convert the very first image found within the file.


title: HISTORY
content:
<b>pi3topbm</b> is part of the Netpbm project, a long-standing suite of graphics utilities. Netpbm originated from Jef Poskanzer's Pbmplus toolkit in the late 1980s. Over the years, it has evolved to support a wide range of image formats and operations, including specialized converters like <b>pi3topbm</b> for handling specific historical or platform-dependent image formats such as Macintosh PICT. Its development reflects the need for interoperability and conversion capabilities across various image standards.


title: PARAMETERS
content:
<b>connect</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Initiates a connection to the Private Internet Access VPN service.</i><br><br><b>disconnect</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Terminates the active VPN connection.</i><br><br><b>status</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Displays the current connection status, including connected region, protocol, and other tunnel details.</i><br><br><b>set region &lt;region_id&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Sets the preferred VPN region for future connections. Use 'piactl get regions' to list available regions.</i><br><br><b>get region</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Retrieves the currently selected VPN region.</i><br><br><b>set protocol &lt;protocol&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Configures the VPN protocol to be used (e.g., 'openvpn', 'wireguard').</i><br><br><b>get protocol</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Shows the currently configured VPN protocol.</i><br><br><b>set port &lt;port&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Sets the port for the VPN connection.</i><br><br><b>get port</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Displays the currently configured VPN port.</i><br><br><b>login</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Authenticates with the PIA service, typically requiring username and password.</i><br><br><b>logout</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Logs out from the PIA service, clearing authentication tokens.</i><br><br><b>reload</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Reloads the PIA client configuration.</i><br><br><b>help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Displays help information for piactl or a specific subcommand.</i><br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Shows the version of the piactl utility and the PIA client.</i><br><br>


title: DESCRIPTION
content:
<i>piactl</i> is a command-line utility designed to control and interact with the Private Internet Access (PIA) VPN desktop client on Linux systems. It allows users to manage their VPN connection without needing to open the graphical user interface. With <i>piactl</i>, you can connect or disconnect from the VPN, check the connection status, switch VPN regions, change connection protocols (like OpenVPN or WireGuard), and adjust other network settings directly from the terminal. It provides a programmatic interface for automating VPN management tasks, making it useful for scripting or headless server environments where the PIA client is installed. The command acts as a wrapper around the underlying PIA service, translating user commands into actions for the VPN client.


title: CAVEATS
content:
<i>piactl</i> is not a standard Linux command; it is part of the Private Internet Access VPN client software package. Therefore, it must be installed as part of the PIA client, and its availability depends on the client's installation. Functionality might vary slightly with different versions of the PIA client. It requires the PIA service to be running in the background.


title: COMMON USAGE EXAMPLE
content:
To connect to the VPN using <i>piactl</i>, you would typically use:<br><b>piactl connect</b><br><br>To check the status of your connection:<br><b>piactl status</b><br><br>To change your region to 'us_east':<br><b>piactl set region us_east</b><br><br>After changing a setting, you might need to reconnect or reload for changes to take full effect.


title: LISTING REGIONS
content:
To see a list of all available VPN regions that you can connect to, use the command:<br><b>piactl get regions</b><br>This is crucial for using the 'set region' command effectively.


title: HISTORY
content:
<i>piactl</i> emerged as a command-line interface component of the Private Internet Access (PIA) VPN client for Linux. Its development is tied directly to the evolution of the PIA desktop application, providing an alternative, scriptable method for users to manage their VPN connections and settings, especially useful in server environments or for users who prefer terminal interaction over a GUI. It has evolved to support new features and protocols like WireGuard as they were integrated into the main PIA client.


title: SYNOPSIS
content:
<b>pic</b> [<I>-CVtwz</I>] [<I>-F directory</I>] [<I>-D number</I>] [<I>-S number</I>] [<I>-T name</I>] [<I>-U unit</I>] [<I>file</I>...]


title: PARAMETERS
content:
<b><I>file</I>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more input files containing <i>pic</i> language commands. If no files are specified, <i>pic</i> reads from standard input.<br><br><b><I>-C</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable compatibility mode with the AT&T <i>pic</i>, allowing some non-standard commands.<br><br><b><I>-T name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the output device for <i>groff</i> (e.g., <b>ps</b>, <b>dvi</b>, <b>html</b>). This influences the generated output format.<br><br><b><I>-F directory</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add <i>directory</i> to the font search path. This is primarily for <i>groff</i>'s font handling.<br><br><b><I>-U unit</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the default unit for dimensions in the <i>pic</i> input (e.g., <b>in</b> for inches, <b>cm</b> for centimeters, <b>pt</b> for points).<br><br><b><I>-V</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the version number of <i>pic</i> to standard error.<br><br>


title: DESCRIPTION
content:
<i>pic</i> is a domain-specific language and a preprocessor for the <i>groff</i> (or <i>troff</i>) typesetting system. It enables users to define simple line drawings and diagrams using a textual description. <i>pic</i> interprets these descriptions, which specify geometric objects like boxes, circles, ellipses, lines, and arcs, along with their positions and relationships (e.g., <b>"box A at (1,1)"</b>, <b>"line from A.bottom to B.top"</b>). The output of <i>pic</i> is a stream of <i>groff</i> (or <i>troff</i>) commands that, when processed by <i>groff</i>, render the specified drawing. This allows for easy embedding of diagrams directly within documents, making it popular for technical documentation and manual pages. It provides a programmatic way to create repeatable and scalable vector graphics without direct manipulation of graphical tools.


title: CAVEATS
content:
<i>pic</i> is a preprocessor, meaning its output needs further processing by <i>groff</i> or <i>troff</i> to produce a viewable document.<br>It is primarily designed for simple, schematic diagrams rather than complex, artistic illustrations.<br>The <i>pic</i> language is procedural, requiring a textual description of objects and their relationships, which can be less intuitive for users accustomed to graphical drawing tools. It does not produce standalone image files like JPEG or SVG directly.


title: TYPICAL USAGE WITH <I>GROFF</I>
content:
<i>pic</i> code is typically embedded directly within a <i>groff</i> document, enclosed by the `<b>.PS</b>` (Pic Start) and `<b>.PE</b>` (Pic End) macros. For example:<br>`<b>.PS</b>`<br>`<b>box "Hello";</b>`<br>`<b>line;</b>`<br>`<b>circle;</b>`<br>`<b>.PE</b>`<br>When <i>groff</i> processes the document, it automatically passes the content between these macros to <i>pic</i> for processing, then integrates the resulting drawing commands back into the main document flow.


title: HISTORY
content:
<i>pic</i> was originally developed by Brian Kernighan at Bell Labs as part of the <i>troff</i> typesetting system. It was designed to provide a simple, programmatic way to include diagrams in technical documents without needing to rely on external graphics software. Its integration with <i>troff</i> (and later <i>groff</i>) made it a powerful tool for creating self-contained, reproducible documents. It became a standard utility in Unix-like systems and is still actively maintained as part of the GNU <i>groff</i> project. Its design emphasizes textual descriptions, aligning with the philosophy of plain text processing common in early Unix environments.


title: PARAMETERS
content:
<b><b>-G</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use default graph attributes for the output <i>dot</i> graph.<br><br><b><b>-g</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use default node attributes for the output <i>dot</i> nodes.<br><br><b><b>-l</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Layout the generated graph as a simple list. This option typically affects how node names are assigned and how they might be connected implicitly.<br><br><b><b>-n</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Process <i>pic</i> names as <i>dot</i> nodes. This allows direct mapping of <i>pic</i> object names to <i>dot</i> node identifiers.<br><br><b><b>-p</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output the processed <i>pic</i> code instead of <i>dot</i> code. Useful for debugging or inspecting the internal representation before <i>dot</i> conversion.<br><br><b><b>-S</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress the outer <i>digraph</i> or <i>graph</i> boilerplate from the output. This is useful when embedding the generated <i>dot</i> code within a larger <i>dot</i> file.<br><br><b><b>-P</b><i>name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the default node prefix to <i>name</i>. This prefix is used for automatically generated node names.<br><br><b><b>-N</b><i>name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the default node name to <i>name</i>. This can be used to assign a common name to nodes created without explicit names.<br><br><b><b>-E</b><i>name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the default edge name to <i>name</i>. Similar to <b>-N</b>, but for edges.<br><br>


title: DESCRIPTION
content:
The <b>pic2graph</b> command is a utility from the Graphviz suite designed to translate text-based diagram descriptions written in the <i>pic</i> language into the <i>dot</i> language. <i>pic</i> is a widely used language for drawing diagrams, particularly within the troff/groff typesetting system. While <i>pic</i> is very versatile, <b>pic2graph</b> focuses on extracting and converting graph-like structures (nodes and edges).<br><br>It interprets <i>pic</i> objects such as <i>box</i>, <i>circle</i>, <i>ellipse</i>, <i>line</i>, and <i>arrow</i>, transforming them into corresponding <i>dot</i> nodes and edges. This allows users to leverage the powerful layout algorithms of Graphviz (like <i>dot</i>, <i>neato</i>, etc.) to render complex diagrams that were originally described in <i>pic</i>. The output <i>dot</i> file can then be processed by other Graphviz tools to generate visual representations in various formats (e.g., SVG, PNG, PDF).


title: CAVEATS
content:
<b>pic2graph</b> is <i>not</i> a full-fledged <i>pic</i> interpreter. It specifically targets graph-like structures and may not correctly translate complex <i>pic</i> diagrams involving arbitrary shapes, complex text positioning, or advanced <i>pic</i> features that do not map directly to <i>dot</i> graph constructs. It's best suited for converting structural diagrams into Graphviz's format for layout and rendering.


title: TYPICAL WORKFLOW
content:
A common workflow involves creating a <i>pic</i> file, then converting it to <i>dot</i> using <b>pic2graph</b>, and finally rendering the <i>dot</i> file into an image:<br><i>$ pic2graph input.pic > output.dot</i><br><i>$ dot -Tpng output.dot > output.png</i><br>This allows users to combine the descriptive power of <i>pic</i> with the sophisticated layout capabilities of Graphviz.


title: INPUT FORMAT
content:
The input to <b>pic2graph</b> is a file (or standard input) containing <i>pic</i> language commands. It expects a subset of <i>pic</i> constructs that describe objects and their connections, suitable for translation into a node-and-edge graph representation.


title: HISTORY
content:
<b>pic2graph</b> is part of the open-source Graphviz (Graph Visualization Software) project, which originated at Bell Labs. Graphviz tools, including <b>pic2graph</b>, were developed to provide flexible and powerful methods for visualizing structural information described in text-based formats. Its development is ongoing, maintained by the Graphviz community.


title: SYNOPSIS
content:
<code>java -jar <I>/path/to/picard.jar</I> <B>TOOL_NAME</B> [<I>OPTION1=VALUE1 OPTION2=VALUE2 ...</I>]</code><br>Example: <code>java -jar picard.jar <B>MarkDuplicates</B> <I>I=input.bam O=output.bam M=metrics.txt</I></code>


title: PARAMETERS
content:
<b><i>(General Note)</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;This section describes common parameters used across Picard tools. Picard is a suite, and each <b>TOOL_NAME</b> has its own specific set of arguments.<br><br><b><b>I=</b><I>&lt;FILE&gt;</I> or <b>INPUT=</b><I>&lt;FILE&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the input file path, typically a SAM, BAM, or CRAM alignment file.<br><br><b><b>O=</b><I>&lt;FILE&gt;</I> or <b>OUTPUT=</b><I>&lt;FILE&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output file path where results will be written.<br><br><b><b>M=</b><I>&lt;FILE&gt;</I> or <b>METRICS_FILE=</b><I>&lt;FILE&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used by certain tools to output a metrics file summarizing the operation.<br><br><b><b>VALIDATION_STRINGENCY=</b><I>&lt;LEVEL&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls how strictly input data is validated. Common levels include <I>STRICT</I>, <I>LENIENT</I>, or <I>SILENT</I>.<br><br><b><b>TMP_DIR=</b><I>&lt;DIRECTORY&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a directory for temporary files created during processing.<br><br><b><b>CREATE_INDEX=</b><I>&lt;true|false&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A boolean flag common to tools that produce BAM/CRAM output, to create an index file (<i>.bai</i> or <i>.crai</i>).<br><br>


title: DESCRIPTION
content:
Picard is a Java-based command-line toolkit developed by the Broad Institute for processing high-throughput sequencing (HTS) data, particularly in genomic research. It provides a wide array of tools for manipulating SAM/BAM/CRAM files (sequence alignment/map formats), VCF files (variant call format), and performing quality control metrics. Common tasks include marking PCR duplicates, adding or replacing read groups, sorting and indexing alignment files, and collecting various sequencing quality metrics. Picard is a critical component in many bioinformatics pipelines, often used in conjunction with other tools like GATK and Samtools, and is integral to preparing data for variant calling.


title: CAVEATS
content:
<b>Java Dependency:</b> Picard is a Java application and requires a Java Runtime Environment (JRE) or Java Development Kit (JDK) (version 8 or newer is usually recommended) to be installed on the system.<br><b>Resource Intensive:</b> Processing large genomic datasets can be computationally intensive, requiring significant RAM and CPU resources. I/O performance is also crucial.<br><b>Not a native Linux Command:</b> Unlike standard Linux commands (e.g., <code>ls</code>, <code>grep</code>), Picard is typically invoked via <code>java -jar</code> and is not usually found directly in system PATHs without a wrapper script.


title: INSTALLATION AND USAGE
content:
Picard is distributed as a single executable JAR file. To use it, download the <code>picard.jar</code> from the official Broad Institute GATK website. It's then invoked using <code>java -jar picard.jar</code> followed by the desired tool name and its specific arguments. It's common practice to create a shell alias or wrapper script for convenience, e.g., <code>alias picard='java -jar /path/to/picard.jar'</code>.


title: KEY SUBCOMMANDS (TOOLS)
content:
Picard is a collection of many individual tools. Some of the most frequently used include:<br><b>MarkDuplicates</b>: Identifies and marks duplicate reads in a BAM file.<br><b>AddOrReplaceReadGroups</b>: Adds or replaces read group information in a BAM file.<br><b>CollectWgsMetrics</b>: Gathers whole-genome sequencing metrics like coverage.<br><b>SortSam</b>: Sorts SAM/BAM files by coordinate or query name.<br><b>BuildBamIndex</b>: Creates a BAM index (<i>.bai</i>) file for random access.<br><b>MergeSamFiles</b>: Merges multiple SAM/BAM files into one.


title: HISTORY
content:
Picard was developed by the Broad Institute of MIT and Harvard, initially as an internal toolset to support their large-scale genomic sequencing efforts. It became an open-source project and quickly gained widespread adoption in the bioinformatics community due to its robust handling of common HTS data manipulation tasks. It is frequently updated and maintained, often in conjunction with the GATK (Genome Analysis Toolkit), forming a cornerstone of many standard genomic data processing pipelines, particularly those used for human genome sequencing.


title: SYNOPSIS
content:
<b>picgo</b> <i>&lt;command&gt;</i> [<i>options</i>] [<i>arguments</i>]<br><b>picgo</b> <i>&lt;subcommand&gt;</i> [<i>options</i>]


title: PARAMETERS
content:
<b><i>command</i>: <b>upload</b> [<i>files...</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uploads specified image files or images from the clipboard.<br><br><b><i>option for upload</i>: <b>-o</b>, <b>--output</b> <i>&lt;dir&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output directory for uploaded image URLs.<br><br><b><i>option for upload</i>: <b>-b</b>, <b>--baseDir</b> <i>&lt;dir&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the base directory for relative paths in uploaded URLs.<br><br><b><i>option for upload</i>: <b>-d</b>, <b>--dir</b> <i>&lt;dir&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uploads images into a specific directory on the host.<br><br><b><i>option for upload</i>: <b>--clip</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uploads the current image content from the clipboard.<br><br><b><i>command</i>: <b>install</b> <i>&lt;plugin&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Installs a PicGo plugin from npm.<br><br><b><i>command</i>: <b>uninstall</b> <i>&lt;plugin&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uninstalls a previously installed PicGo plugin.<br><br><b><i>command</i>: <b>use</b> <i>&lt;plugin/uploader/transformer&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Switches to use a specific plugin, uploader, or transformer.<br><br><b><i>command</i>: <b>set</b> <i>&lt;config-key&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Configures settings for PicGo or a specific uploader.<br><br><b><i>command</i>: <b>init</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Initializes the PicGo configuration file.<br><br><b><i>command</i>: <b>config</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the path to the PicGo configuration file.<br><br><b><i>command</i>: <b>plugin list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all currently installed PicGo plugins.<br><br><b><i>command</i>: <b>update</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Updates the PicGo CLI itself to the latest version.<br><br><b><i>command</i>: <b>help</b> [<i>&lt;command&gt;</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the main command or a specific subcommand.<br><br><b><i>command</i>: <b>version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the current version of PicGo CLI.<br><br><b><i>Global Option</i>: <b>--config</b> <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative path to the PicGo configuration file.<br><br><b><i>Global Option</i>: <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the invoked command.<br><br><b><i>Global Option</i>: <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version of PicGo CLI.<br><br>


title: DESCRIPTION
content:
The <b>picgo</b> command-line tool provides a powerful and flexible way to automate image uploading to a multitude of cloud storage services and image hosting platforms. Originally known for its desktop GUI application, <b>picgo-cli</b> extends its functionality to the terminal, allowing users to integrate image uploads into scripts, build processes, and other automated workflows. It supports a wide array of popular services including GitHub, Imgur, Amazon S3, Alibaba Cloud OSS, Tencent Cloud COS, and many more, often via a rich plugin ecosystem. Users can easily configure different uploaders, manage clipboard uploads, and specify output formats, making it an invaluable tool for bloggers, developers, and anyone needing to quickly host images from the command line without manual intervention.


title: CAVEATS
content:
PicGo CLI requires <b>Node.js</b> and <b>npm</b> to be installed on the system. Its functionality heavily relies on a correctly configured <i>~/.picgo/config.json</i> file, which can sometimes be intricate, especially when dealing with various third-party image hosting services that require API keys or complex authentication. While powerful, its setup might present a learning curve for new users unfamiliar with Node.js environments or API configurations.


title: CONFIGURATION FILE
content:
PicGo stores its configuration, including uploader settings and plugin configurations, in a JSON file typically located at <i>~/.picgo/config.json</i> (on Linux and macOS). This file is crucial for defining how images are uploaded and where they are hosted.


title: PLUGIN ECOSYSTEM
content:
A significant strength of PicGo is its robust plugin system. Users can install third-party plugins to add support for new image hosts, implement custom processing steps (e.g., compression, watermarking), or integrate with other tools. Plugins are managed via <b>npm</b> and can greatly extend the CLI's capabilities.


title: HISTORY
content:
PicGo originated as a popular desktop application for macOS and Windows, designed to simplify the process of uploading images and obtaining their URLs. The command-line interface, <b>picgo-cli</b>, was introduced later to cater to developers and users who needed to integrate image uploading capabilities into automated scripts, CI/CD pipelines, or other non-GUI workflows. This evolution transformed PicGo from a pure desktop utility into a versatile tool available across different environments, leveraging Node.js for its cross-platform compatibility and extensive plugin system.


title: SYNOPSIS
content:
As <i>pickle</i> is a Python module and not a standalone executable, there is no direct "pickle" command to run in a Linux shell. Its functionality is accessed through Python scripts or the Python interpreter.<br><br>To use <i>pickle</i>, you typically invoke the Python interpreter:<br><code><b>python</b> [<i>options</i>] <i>script.py</i> [<i>arguments</i>]</code><br>Or for direct interaction:<br><code><b>python</b></code><br>Inside the Python environment, you would import and use the <i>pickle</i> module's functions, such as <i>pickle.dump()</i>, <i>pickle.load()</i>, <i>pickle.dumps()</i>, or <i>pickle.loads()</i>.


title: PARAMETERS
content:
<b><i>pickle.dump(obj, file, protocol=None, *, fix_imports=True, buffer_callback=None)</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the pickled representation of <i>obj</i> to the open <i>file</i> object.<br><br><b><i>pickle.load(file, *, fix_imports=True, encoding='ASCII', errors='strict', buffers=None)</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads a pickled object representation from the open <i>file</i> object and reconstructs it.<br><br><b><i>pickle.dumps(obj, protocol=None, *, fix_imports=True, buffer_callback=None)</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Returns the pickled representation of <i>obj</i> as a bytes object.<br><br><b><i>pickle.loads(bytes_object, *, fix_imports=True, encoding='ASCII', errors='strict', buffers=None)</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads a pickled object representation from <i>bytes_object</i> and reconstructs it.<br><br><b><i>protocol</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An integer, specifying the pickle protocol version to use (e.g., 0-5). Higher protocols are generally more efficient and newer.<br><br>


title: DESCRIPTION
content:
The <i>pickle</i> module is a fundamental component of the Python standard library, used for serializing and deserializing Python object structures. It converts a Python object hierarchy into a byte stream, a process known as <i>"pickling"</i> or <i>"serialization"</i>. Conversely, it can reconstruct the original Python object hierarchy from that byte stream, a process called <i>"unpickling"</i> or <i>"deserialization"</i>.<br><br>While not a standalone Linux command, <i>pickle</i> is extensively used within Python scripts executed on Linux systems. Its primary purpose is to allow Python objects to be stored on disk, transferred across a network, or otherwise persisted. Unlike JSON or XML, <i>pickle</i> is Python-specific, meaning it can serialize complex Python data types that these more universal formats might not support directly, such as custom class instances, functions, or sets. However, this specificity also comes with a significant security caveat: deserializing untrusted <i>pickle</i> data can execute arbitrary code.


title: CAVEATS
content:
<ul><li><b>Security Vulnerability:</b> <i>Unpickling</i> data from an untrusted source is a significant security risk. Maliciously crafted <i>pickle</i> data can lead to arbitrary code execution on the system. Never unpickle data unless you are absolutely certain of its origin and integrity.</li><li><b>Python Version Dependency:</b> <i>Pickle</i> protocols can evolve. Data pickled with a newer Python version's protocol might not be compatible with older Python versions, and vice-versa. Best practice is to use a consistent Python version for pickling and unpickling.</li><li><b>Not Human-Readable:</b> Pickled data is a binary format and is not designed to be human-readable or easily edited, unlike formats such as JSON or YAML.</li></ul>


title: PICKLE PROTOCOLS
content:
The <i>pickle</i> module supports several protocol versions (0 through 5 as of Python 3.8+). Newer protocols generally offer better performance and smaller output sizes. Protocol 0 is the original human-readable (text-based) protocol, while higher protocols are binary. The latest recommended protocol is typically the highest available, specified by <i>pickle.DEFAULT_PROTOCOL</i> or <i>pickle.HIGHEST_PROTOCOL</i> for maximum compatibility/efficiency.


title: MODULE VS. COMMAND
content:
It is crucial to understand that <i>pickle</i> is a Python module, not a standalone shell command. You cannot type <code>pickle &lt;filename&gt;</code> directly in a Linux terminal. Its functionality is accessed by writing Python code that imports and uses the <code>pickle</code> module.


title: HISTORY
content:
The <i>pickle</i> module has been a core part of the Python standard library since its early versions (first introduced in Python 1.5.2). Its development has primarily focused on introducing new, more efficient, and robust protocol versions while maintaining backward compatibility where possible. Each new protocol version aims to improve performance, reduce the size of the pickled data, or handle more complex data structures. The module's design has remained consistent, providing the primary functions for serialization and deserialization, serving as a reliable mechanism for persisting Python objects.


title: SYNOPSIS
content:
<b>pico</b> [<I>options</I>] [<I>file</I>...]<br><br><I>Examples:</I><br><b>pico</b> <I>myfile.txt</I><br><b>pico</b> <I>-w</I> <I>config.conf</I>


title: PARAMETERS
content:
<b><I>file</I>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies one or more files to open for editing. If the file does not exist, a new empty file will be created.<br><br><b><b>-w</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables word wrapping. Long lines will extend off-screen rather than wrapping to the next line.<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens the file in view-only (read-only) mode, preventing accidental modifications.<br><br><b><b>+<I>N</I>,<I>C</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts the editor with the cursor at line <I>N</I> and column <I>C</I> (e.g., <I>pico +10,5 myfile.txt</I>). Note: This specific option syntax is more commonly associated with <I>nano</I>.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a summary of command-line options and exits.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays version information about the <b>pico</b> (or <b>nano</b>) editor and exits.<br><br>


title: DESCRIPTION
content:
<i>pico</i> is a lightweight, <i>cursor-based</i> text editor designed for ease of use, originally developed as part of the Pine email client. It stands for "Program for Internet Communications." Unlike more complex editors like <i>Vi</i> or <i>Emacs</i>, <i>pico</i> focuses on simplicity and a low learning curve, making it ideal for quick edits, configuration file modifications, or basic note-taking directly within the terminal.<br><br>Its most distinctive feature is the persistent display of common commands at the bottom of the screen, eliminating the need to memorize complex keybindings. Users navigate with arrow keys and perform actions using <i>Control</i> key combinations (e.g., <i>Ctrl+X</i> to exit, <i>Ctrl+O</i> to save). While lacking advanced features found in other editors, <i>pico</i> remains a popular choice for beginners or those requiring a straightforward editing experience on Unix-like systems. On many modern Linux distributions, the <i>pico</i> command is actually a symbolic link to the <i>nano</i> editor, which was created as a free software clone of <i>pico</i>.


title: CAVEATS
content:
On most modern Linux distributions, the <b>pico</b> command is a symbolic link to the <b>nano</b> editor. This means that invoking <b>pico</b> actually executes <b>nano</b>, and its behavior, features, and command-line options are those of <b>nano</b>.<br><br><b>pico</b> lacks many advanced features found in other powerful editors like <b>Vim</b> or <b>Emacs</b>, including advanced scripting, regular expression search/replace, multiple buffers, and windowing. Its primary strength lies in its simplicity rather than its feature set.


title: BASIC USAGE & KEY BINDINGS
content:
Inside <b>pico</b>, common operations are performed using <I>Control</I> key combinations, which are conveniently displayed at the bottom of the screen. Some of the most frequently used bindings include:<br><ul><li><I>Ctrl+G</I>: Get Help (displays a comprehensive list of commands).</li><li><I>Ctrl+X</I>: Exit (prompts to save changes if unsaved).</li><li><I>Ctrl+O</I>: Write Out (save current changes to the file).</li><li><I>Ctrl+R</I>: Read File (insert contents of another file).</li><li><I>Ctrl+K</I>: Cut Text (cut the current line).</li><li><I>Ctrl+U</I>: Uncut Text (paste the last cut text).</li><li><I>Ctrl+W</I>: Where Is (search for text).</li><li><I>Ctrl+T</I>: To Spell (invokes spell checker).</li></ul><br>Navigation is typically done using arrow keys.


title: HISTORY
content:
The <b>pico</b> editor was originally developed by the University of Washington for the <I>Pine</I> (Program for Internet News and Email) email client, first released in 1992. Its design prioritized ease of use and a shallow learning curve, making it accessible to non-technical users within the command-line environment. The name <b>pico</b> itself is an acronym for "Program for Internet Communications."<br><br>Due to licensing restrictions associated with the <I>Pine</I> and <b>pico</b> software, a free software clone named <I>nano</I> (Nano's ANOther editor) was created in 1999 to provide an open-source alternative with similar functionality. Over time, <I>nano</I> gained widespread adoption in the Linux ecosystem, and many distributions now provide <b>pico</b> as a symbolic link to <b>nano</b>, effectively replacing the original <b>pico</b> with its open-source counterpart while maintaining command compatibility.


title: PARAMETERS
content:
<b><I>device</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the serial port device (e.g., <I>/dev/ttyUSB0</I> or <I>/dev/ttyS0</I>).<br><br><b><b>--baud</b> <I>rate</I>, <b>-b</b> <I>rate</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the serial port communication speed, typically in bits per second (e.g., 9600, 115200).<br><br><b><b>--parity</b> <I>type</I>, <b>-p</b> <I>type</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Configures parity for data integrity checking. Options are 'n' (none), 'o' (odd), or 'e' (even).<br><br><b><b>--databits</b> <I>bits</I>, <b>-d</b> <I>bits</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the number of data bits per byte (usually 7 or 8).<br><br><b><b>--flow</b> <I>type</I>, <b>-f</b> <I>type</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the flow control method: 'n' (none), 'x' (Xon/Xoff software flow control), or 'h' (hardware RTS/CTS flow control).<br><br><b><b>--escape</b> <I>char</I>, <b>-e</b> <I>char</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the escape character used to issue commands to picocom. The default is <b>Ctrl+a</b>.<br><br><b><b>--nolock</b>, <b>-l</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents picocom from creating a lock file for the serial device, allowing other processes to access it concurrently (use with caution).<br><br><b><b>--initstring</b> <I>string</I>, <b>-i</b> <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sends an initialization string to the serial device immediately upon connection.<br><br><b><b>--echo</b>, <b>-c</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables local character echo, meaning characters typed on the keyboard are immediately displayed on the screen.<br><br><b><b>--no-init</b>, <b>-o</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables picocom's default serial port initialization. Useful if the device is already configured by another application.<br><br><b><b>--send-cmd</b> <I>cmd</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the external command to execute when sending a file (e.g., 'sz' for Zmodem), invoked by <b>Ctrl+a Ctrl+s</b>.<br><br><b><b>--receive-cmd</b> <I>cmd</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the external command to execute when receiving a file (e.g., 'rz' for Zmodem), invoked by <b>Ctrl+a Ctrl+r</b>.<br><br><b><b>--version</b>, <b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information of picocom and exits.<br><br><b><b>--help</b>, <b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the help message and exits.<br><br>


title: DESCRIPTION
content:
Picocom is a lightweight and simple serial communication program for Linux, often used to connect to embedded systems, modems, or network devices via their serial console ports. Unlike more feature-rich terminals like <b>minicom</b>, picocom focuses on providing basic, reliable serial access without complex menus, scripting, or integrated file transfer protocols. It supports common serial port settings such as baud rate, parity, data bits, and flow control. Its simplicity makes it ideal for quick debugging sessions or direct console access where a full-fledged terminal emulator is overkill.


title: CAVEATS
content:
Picocom offers limited functionality compared to feature-rich terminal emulators like <b>minicom</b>, notably lacking built-in file transfer protocols (like Zmodem or Ymodem) or complex scripting capabilities. Users must manually manage file transfers via external commands configured with <b>--send-cmd</b> and <b>--receive-cmd</b>. Additionally, interacting with the serial port usually requires appropriate user permissions, such as being part of the 'dialout' or 'uucp' group, or using <b>sudo</b>.


title: COMMON USAGE AND EXITING
content:
To connect to a serial device, you typically specify the device path and desired baud rate. For example, to connect to <I>/dev/ttyUSB0</I> at 115200 baud, you would use: <br><b>picocom -b 115200 /dev/ttyUSB0</b><br><br>To exit picocom gracefully, use the default escape sequence: press <b>Ctrl+a</b> (the escape character), then immediately <b>Ctrl+x</b>. Other commands can be issued after <b>Ctrl+a</b>, such as <b>Ctrl+s</b> to send a file or <b>Ctrl+r</b> to receive one (if <b>--send-cmd</b> or <b>--receive-cmd</b> are configured).


title: HISTORY
content:
Picocom emerged as a streamlined alternative to more complex serial terminal programs like <b>minicom</b>, designed for simplicity and minimal resource usage. Its development focused on providing core serial communication capabilities without the overhead of graphical interfaces or advanced features, making it particularly popular for embedded systems development and quick console access tasks on Linux.


title: PARAMETERS
content:
<b><b>--backend</b> <<i>backend</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the rendering backend to use. Common options include <i>glx</i> (hardware accelerated) and <i>xrender</i> (software rendering).<br><br><b><b>--config</b> <<i>path</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the path to the configuration file. Defaults to <i>~/.config/picom/picom.conf</i> or <i>/etc/xdg/picom.conf</i>.<br><br><b><b>--shadow</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable drawing of shadows for windows.<br><br><b><b>--no-fading-openclose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable fading in/out when windows are opened or closed.<br><br><b><b>--vsync</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable VSync support to prevent screen tearing.<br><br><b><b>--inactive-opacity</b> <<i>value</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the opacity of inactive windows, a value between 0.0 and 1.0 (e.g., 0.8 for 80% opacity).<br><br><b><b>--opacity-rule</b> <<i>rule</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Define rules for window opacity based on various window properties (e.g., class, title). Can be specified multiple times.<br><br><b><b>--log-level</b> <<i>level</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the logging level. Possible values include <i>trace</i>, <i>debug</i>, <i>info</i>, <i>warn</i>, <i>error</i>.<br><br><b><b>--daemon</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run <b>picom</b> in the background as a daemon.<br><br><b><b>--no-daemon</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not daemonize the process (useful for debugging or running in a terminal).<br><br>


title: DESCRIPTION
content:
<b>picom</b> is a lightweight and highly configurable standalone compositor for the X Window System. It enhances the visual appearance of your desktop by adding effects such as <i>shadows</i>, <i>fading</i>, and <i>transparency</i> to windows.<br><br>Originally forked from <b>compton</b>, <b>picom</b> aims to provide a more maintainable codebase and modern features, serving as a popular choice for users of tiling window managers like <i>i3</i>, <i>bspwm</i>, and <i>AwesomeWM</i>. Beyond aesthetics, it also plays a crucial role in preventing screen tearing by enabling <i>VSync</i>.<br><br>It processes window contents before they are displayed, applying various transformations based on user-defined rules. Its extensive configuration options, typically managed via a `picom.conf` file, allow users to fine-tune every aspect of its behavior, making it adaptable to diverse desktop setups and performance requirements.


title: CAVEATS
content:
<b>picom</b> requires the X Window System to function and is not designed for Wayland-based desktop environments. Incorrect configuration can sometimes lead to visual glitches or performance issues, especially with certain applications that bypass the X server's compositing manager or with incompatible graphics drivers. Users should back up their configuration file before making significant changes.


title: CONFIGURATION FILE
content:
<b>picom</b> is heavily configured through a configuration file, typically located at <i>~/.config/picom/picom.conf</i> or <i>/etc/xdg/picom.conf</i>. This file allows for fine-grained control over shadows, fading, opacity rules, VSync settings, and more. It is highly recommended to customize this file to suit individual preferences and system performance.


title: BACKEND OPTIONS
content:
<b>picom</b> supports different rendering backends, most commonly <i>xrender</i> (software rendering, widely compatible) and <i>glx</i> (hardware accelerated, often faster but may require specific OpenGL drivers). Users can select the preferred backend using the <i>--backend</i> option or in the configuration file, depending on their hardware and desired performance characteristics.


title: HISTORY
content:
<b>picom</b> originated as a fork of <b>compton</b>, which itself evolved from earlier compositors like <b>dcompmgr</b> and <b>xcompmgr-dana</b>. The primary motivation for the <b>picom</b> fork was to address issues in <b>compton</b>'s codebase, improve maintainability, and introduce new features and modern rendering capabilities. Over time, <b>picom</b> has largely superseded <b>compton</b> as the preferred standalone X compositor for many users due to its active development and robust feature set.


title: SYNOPSIS
content:
<i>picom-trans</i> [<b>-f</b>|<b>-c</b> <i>CLASS</i>|<b>-n</b> <i>NAME</i>|<b>-p</b> <i>PID</i>|<b>-i</b> <i>ID</i>] [<i>VALUE</i>]<br><i>picom-trans</i> [<b>-t</b>|<b>-F</b>|<b>-I</b> <i>VALUE</i>|<b>-D</b> <i>VALUE</i>|<b>-u</b>] [<i>ID</i>]<br><i>picom-trans</i> [<b>-v</b>|<b>-h</b>]


title: PARAMETERS
content:
<b><i>&lt;ID&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Target a window by its hexadecimal X window ID. This is the default action if no other targeting option is specified.<br><br><b><b>-f</b>, <b>--focus</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Operate on the currently focused window.<br><br><b><b>-c</b> <i>&lt;CLASS&gt;</i>, <b>--class</b> <i>&lt;CLASS&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Target windows matching the specified X window class name.<br><br><b><b>-n</b> <i>&lt;NAME&gt;</i>, <b>--name</b> <i>&lt;NAME&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Target windows matching the specified X window name (title).<br><br><b><b>-s</b> <i>&lt;VALUE&gt;</i>, <b>--set</b> <i>&lt;VALUE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the target window's opacity to <i>VALUE</i> (0-100, where 100 is fully opaque).<br><br><b><b>-t</b>, <b>--toggle</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Toggle the target window's opacity between its current state and a default opaque state.<br><br><b><b>-I</b> <i>&lt;VALUE&gt;</i>, <b>--increment</b> <i>&lt;VALUE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increase the target window's current opacity by <i>VALUE</i>.<br><br><b><b>-D</b> <i>&lt;VALUE&gt;</i>, <b>--decrement</b> <i>&lt;VALUE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Decrease the target window's current opacity by <i>VALUE</i>.<br><br><b><b>-u</b>, <b>--unfade</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Restore the target window to its default opaque state, overriding any previous transparency.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display version information and exit.<br><br>


title: DESCRIPTION
content:
<i>picom-trans</i> is a dedicated command-line utility for interacting with the <i>picom</i> X compositor, specifically designed to control the transparency (opacity) of windows. It offers a powerful and flexible way to dynamically modify window visibility, allowing users to set an exact opacity value, toggle between opaque and transparent states, or gradually increase/decrease transparency. Windows can be targeted using various identifiers, including their numerical window ID, their application class name (e.g., &quot;Terminator&quot;), their window title/name, or the process ID that owns the window. A particularly useful feature is the ability to target the currently focused window without needing its specific identifier. This utility is invaluable for desktop customization, enabling users to create keyboard shortcuts for on-the-fly opacity adjustments, integrate opacity changes into shell scripts, or simply fine-tune the look and feel of their workspace. By leveraging <i>picom</i>'s capabilities, <i>picom-trans</i> provides seamless control over window appearance, making it a crucial tool for those seeking to enhance their visual desktop environment.


title: CAVEATS
content:
<i>picom-trans</i> requires an X compositor, specifically <i>picom</i> or a compatible alternative, to be running for its functionality to have any effect. The effectiveness and precise behavior may depend on the compositor's configuration and the type of window being manipulated. Window IDs are typically hexadecimal values and can be obtained using tools like <i>xwininfo</i>.


title: INTERACTION MECHANISM
content:
<i>picom-trans</i> communicates with the <i>picom</i> compositor (or compatible alternatives) primarily by setting specific X window properties, such as <b>_NET_WM_WINDOW_OPACITY</b>. These properties are then interpreted and rendered by the running compositor to achieve the desired visual effect. Some versions or configurations might also leverage D-Bus for more direct communication with the compositor's running instance.


title: HISTORY
content:
<i>picom-trans</i> emerged as a companion utility alongside the development of X compositors like <i>compton</i> (a fork of <i>xcompmgr</i>) and later <i>picom</i> (a fork of <i>compton</i>). Its purpose has always been to provide a command-line interface for dynamically manipulating window opacity, a key feature offered by these compositors. Its evolution has mirrored the progress of its parent projects, focusing on offering robust and flexible control over window appearance within X11 desktop environments.


title: PARAMETERS
content:
<b>-f <i>FROM_CHARSET</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the input character encoding. If omitted, it often defaults to the current locale's encoding.<br><br><b>-t <i>TO_CHARSET</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output character encoding. If omitted, it often defaults to the current locale's encoding.<br><br><b>-c</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Discards characters that cannot be converted from the input character set to the output character set, without printing a warning.<br><br><b><i>INPUT_FILE</i>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more input files to convert. If no files are specified, <b>piconv</b> reads from standard input.<br><br>


title: DESCRIPTION
content:
<b>piconv</b> is a lightweight utility designed for converting text from one character encoding to another. It serves as a simplified version of the more comprehensive <b>iconv</b> command, often found in resource-constrained environments like BusyBox.<br><br>The primary function of <b>piconv</b> is to read input text in a specified <i>source character set</i> and output it in a designated <i>target character set</i>. This is crucial for handling international characters, ensuring proper display of text files, or compatibility between systems using different encodings. It reads from standard input if no files are provided and writes the converted output to standard output.


title: CAVEATS
content:
<b>piconv</b> is typically a stripped-down version of <b>iconv</b>, meaning it may not support all the advanced options or extensive character set listings that the full <b>iconv</b> utility provides. Its availability and exact behavior can vary depending on the specific Linux distribution or embedded system (e.g., BusyBox) where it is found.


title: CHARACTER SET NAMES
content:
Character set names can be specified as canonical names (e.g., <i>UTF-8</i>, <i>ISO-8859-1</i>) or common aliases. The list of supported character sets depends on the specific <b>piconv</b> implementation.


title: STANDARD I/O
content:
When no <i>INPUT_FILE</i> is provided, <b>piconv</b> reads data from standard input (<i>stdin</i>) and writes the converted output to standard output (<i>stdout</i>). This allows it to be used effectively in shell pipelines.


title: HISTORY
content:
The concept of <b>piconv</b> emerged as a simplified or placeholder implementation of the standard <b>iconv</b> utility, particularly within embedded systems and lightweight Linux environments like BusyBox. Its development focuses on providing essential character set conversion functionality while minimizing binary size and resource consumption.


title: SYNOPSIS
content:
<b>picotool</b> [<i>options</i>] [<i>file.uf2</i>]<br><b>picotool</b> --flash <<i>file.uf2</i>> [<i>options</i>]<br><b>picotool</b> --reboot<br><b>picotool</b> --info


title: PARAMETERS
content:
<b>-f, --flash <file.uf2></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Flash the specified UF2 file to the connected RP2040 device.<br><br><b>-r, --reboot</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reboot the connected RP2040 device into its normal application mode.<br><br><b>-b, --boot</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reboot the connected RP2040 device into BOOTSEL mode.<br><br><b>-u, --usb <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the USB device path for interaction (e.g., <i>/dev/sdb</i>).<br><br><b>-m, --memory</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show detailed memory usage information of the device.<br><br><b>-i, --info</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display detailed information about the connected RP2040 device.<br><br><b>-l, --list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;List all currently connected RP2040 devices in BOOTSEL mode.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output, providing more detailed logs for operations.<br><br><b>--size <file.uf2></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the size of the given UF2 file without flashing it.<br><br><b>--verify</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Verify the flash operation after writing the UF2 file.<br><br><b>--address <addr></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a flash address for read or write operations.<br><br><b>--offset <offset></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an offset for flash operations, often used with --address.<br><br><b>--dump <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Dump the contents of the device's flash memory to the specified file.<br><br><b>--clear-bootsel-pin</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Clear the BOOTSEL pin state, typically for persistent bootloader bypass.<br><br><b>--set-bootsel-pin</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the BOOTSEL pin state, forcing the device into BOOTSEL on reboot.<br><br>


title: DESCRIPTION
content:
<i>picotool</i> is a command-line utility designed by Raspberry Pi to interact with RP2040 microcontrollers, particularly the Raspberry Pi Pico, when they are in BOOTSEL mode.<br>This mode presents the device as a USB Mass Storage device, allowing <i>picotool</i> to easily flash new firmware (in UF2 format), query device information, reboot the microcontroller, and perform memory inspections.<br>It's an essential tool for developers working with RP2040-based boards, providing a convenient way to program and debug without needing complex debugging hardware. It streamlines the firmware deployment process, especially for rapid iteration during development.


title: CAVEATS
content:
<i>picotool</i> requires the target RP2040 device to be in BOOTSEL mode, which means it appears as a USB Mass Storage device. Ensure the device is connected and in this mode before running commands.<br>Depending on your system's udev rules and user permissions, you might need to run <i>picotool</i> with <b>sudo</b> for it to detect and interact with the device correctly. It primarily interacts with the device's bootloader, not the running application.


title: TYPICAL USAGE WORKFLOW
content:
A common workflow involves compiling your RP2040 firmware into a UF2 file.<br>Then, hold the BOOTSEL button on your Pico while plugging it into USB to enter BOOTSEL mode. The device will appear as a USB drive.<br>You can then use <i><b>picotool --flash your_firmware.uf2 --reboot</b></i> to quickly flash and run your new code. This rapid iteration is crucial for embedded development.


title: HISTORY
content:
<i>picotool</i> was developed by the Raspberry Pi Foundation as an integral part of the Raspberry Pi Pico SDK. It was released alongside the Raspberry Pi Pico and the RP2040 microcontroller in January 2021, providing a dedicated and user-friendly tool for flashing and interacting with the new chip's unique BOOTSEL mode.<br>Its development aimed to simplify the firmware update process for developers and users of the RP2040, making rapid prototyping and deployment more accessible.


title: SYNOPSIS
content:
<i>picttoppm</i> [-alpha] [-background &lt;color&gt;] [-gamma &lt;n&gt;] [-invert] [-verbose] [<i>pictfile</i>]


title: PARAMETERS
content:
<b>-alpha</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Extracts the <B>alpha channel</B> (transparency) from the PICT image as a <B>PGM</B> (Portable Graymap) image. This output is separate from the main PPM image.<br><br><b>-background &lt;color&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the <B>background color</B> for images with transparency or non-rectangular shapes. Areas not explicitly defined by the PICT image will be filled with this color. The color can be a name (e.g., "red"), a hexadecimal RGB value (e.g., "#RRGGBB"), or a Netpbm color name.<br><br><b>-gamma &lt;n&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a <B>gamma correction</B> of <i>n</i> to the output image. This can be used to adjust the brightness and contrast of the image.<br><br><b>-invert</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Inverts the <B>colors</B> of the output image (negative effect).<br><br><b>-verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints <B>verbose information</B> about the PICT file structure and the conversion process to standard error.<br><br><b><i>pictfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the Apple PICT file to be converted. If omitted, <i>picttoppm</i> reads the PICT data from <B>standard input</B>.<br><br>


title: DESCRIPTION
content:
<i>picttoppm</i> is a utility from the <B>Netpbm</B> suite of graphics programs. Its primary function is to convert image files in the <B>Apple Macintosh PICT</B> format into the Netpbm <B>Portable Pixmap (PPM)</B> format.<br><br>PICT files can contain various types of graphical data, including bitmaps, vector graphics, and text. <i>picttoppm</i> focuses on rendering the bitmap portions and converting them into a pixel-based image format that is easily manipulable by other Netpbm tools.<br><br>The <B>PPM</B> format is a simple, uncompressed representation of a color image, making it an excellent intermediate format for further processing, such as converting to GIF, JPEG, or PNG using other Netpbm converters. This command is particularly useful for users dealing with legacy Macintosh image files in a Unix-like environment. It supports both <B>PICT 1</B> and <B>PICT 2</B> formats.


title: CAVEATS
content:
<i>picttoppm</i> might not perfectly render all complex elements of PICT files, especially intricate vector graphics, certain text styles, or advanced QuickDraw operations, as its primary focus is on bitmap conversion.<br><br>It is designed for older PICT formats; newer macOS image formats or formats used by modern Apple applications are generally <B>not supported</B>.<br><br>The output is an uncompressed PPM, which can result in <B>large file sizes</B>. Users commonly pipe the output to other Netpbm tools for compression (e.g., <i>picttoppm file.pict | ppmtogif &gt; file.gif</i>).


title: STANDARD INPUT/OUTPUT
content:
If no <i>pictfile</i> is specified as an argument, <i>picttoppm</i> will automatically read the PICT data from <B>standard input</B>. The converted PPM data is always written to <B>standard output</B>. This design makes <i>picttoppm</i> highly suitable for <B>piping operations</B> in shell scripts, allowing seamless integration with other command-line utilities for further image processing or compression.


title: COLOR HANDLING
content:
The command intelligently handles various color depths present within PICT files, converting them to the full <B>24-bit color space</B> of the PPM format. The <B>-background</B> option is particularly useful when the PICT file contains transparency or non-rectangular regions, providing the user control over what color fills these areas in the resulting output image.


title: HISTORY
content:
<i>picttoppm</i> is an integral part of the <B>Netpbm</B> package, a long-standing and widely used toolkit for graphics manipulation on Unix-like systems. Netpbm traces its roots back to the <i>pbmplus</i> package created by Jef Poskanzer in the late 1980s.<br><br><i>picttoppm</i> was specifically developed to handle the conversion of <B>Apple Macintosh PICT</B> files, which were a prevalent image exchange format on that platform during the pre-Internet and early Internet eras. Its continued existence reflects the ongoing need to process legacy image formats in modern computing environments, making older Macintosh graphics accessible.


title: PARAMETERS
content:
<b><i>program</i> ...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more program names for which to find PIDs. <b>pidof</b> typically matches the exact command name (<i>argv[0]</i>) of the running process, which includes its path if specified.<br><br><b><i>-s</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Single shot) Return only one PID, even if multiple instances of the program are running. The specific PID returned may vary and is not guaranteed to be the oldest or newest.<br><br><b><i>-c</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Comm mode) Search for processes whose command name (as found in the <i>comm</i> field of <i>/proc/PID/stat</i>) matches the given <i>program</i>. The <i>comm</i> field is typically truncated to 15 characters, which can make this option more restrictive than the default <i>argv[0]</i> matching.<br><br><b><i>-x</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Scripts) Also return PIDs of processes that are running a shell script specified by name. This is useful for identifying running instances of scripts that are executed via an interpreter (e.g., <i>bash script.sh</i>).<br><br><b><i>-o omitpid</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Omit PID) Omit specific PIDs from the output. <i>omitpid</i> can be a single PID or a comma-separated list of PIDs.<br><br><b><i>-q</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Quiet) Suppress any error messages from being displayed. Only the PIDs will be outputted to standard output.<br><br>


title: DESCRIPTION
content:
The <b>pidof</b> command finds the process IDs (PIDs) of one or more running programs. It takes program names as arguments and returns a space-separated list of PIDs corresponding to those programs.<br><br>Unlike <i>pgrep</i>, which uses regular expressions and can search various process attributes, <b>pidof</b> primarily matches the exact command name (<i>argv[0]</i>) of the running executable. This makes it particularly useful in shell scripts where you need to quickly obtain the PID of a known process for further action, such as sending a signal with <i>kill</i>.


title: CAVEATS
content:
<b>pidof</b> relies on the <i>/proc</i> filesystem for process information. It is generally less flexible than <i>pgrep</i> as it doesn't support regular expressions for matching program names. When multiple instances of a program are running, <b>pidof</b> will list all their PIDs unless the <i>-s</i> option is used. The default matching behavior is on <i>argv[0]</i>, which might include the full path to the executable (e.g., <i>/usr/bin/nginx</i>).


title: EXIT STATUS
content:
<b>pidof</b> returns an exit status of 0 if one or more PIDs are found for the specified programs, and a non-zero status (typically 1) if no PIDs are found or an error occurs. This makes it suitable for conditional execution in shell scripts.


title: USE CASES
content:
Commonly used in shell scripts to check if a process is running, to obtain a PID for sending signals (e.g., stopping a service), or for managing daemon processes. For example: <br><i>if pidof myserver > /dev/null; then echo "myserver is running"; fi</i>


title: HISTORY
content:
<b>pidof</b> has been a standard utility on many Linux distributions. On some systems, particularly those using <i>sysvinit-utils</i>, <b>pidof</b> is often implemented as a symbolic link to the <i>killall5</i> command. While their primary functions differ (<i>killall5</i> typically sends signals to all processes except kernel processes and its own children), this historical link reflects its common use in system initialization scripts and process management.


title: SYNOPSIS
content:
<br><b>pidstat</b> [ <I>options</I> ] [ <I>interval</I> [ <I>count</I> ] ]<br><br>Example: <b>pidstat -u 1 5</b> (CPU stats every second for 5 reports)<br>Example: <b>pidstat -d -p 1234</b> (I/O stats for PID 1234)<br>Example: <b>pidstat -H -t -p 5678 2</b> (Thread stats for PID 5678 every 2 seconds continuously)<br>


title: PARAMETERS
content:
<b><b>-d</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Report I/O statistics, including kilobytes read/written per second (kB_rd/s, kB_wr/s) and canceled write bytes (kB_ccwr/s).<br><br><b><b>-H</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Report statistics for individual threads of a process. When used with <b>-p</b>, it implies <b>-t</b>, showing thread-level data.<br><br><b><b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a short help message and exit.<br><br><b><b>-l</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the full command line arguments of the tasks being monitored, not just the command name.<br><br><b><b>-p</b> <I>PID[,...] | ALL</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Report statistics only for the specified process IDs. Use <I>ALL</I> to report for all currently active tasks.<br><br><b><b>-r</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Report memory statistics, such as minor/major page faults per second (minflt/s, majflt/s), virtual memory size (VSZ), and resident set size (RSS).<br><br><b><b>-s</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Report stack usage statistics, including stack size (StkSize) and stack segment references (StkRef).<br><br><b><b>-t</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Report statistics for individual threads. This option is implicitly set when <b>-H</b> and <b>-p</b> are used together.<br><br><b><b>-u</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Report CPU utilization statistics. This is the default behavior if no specific report option is given.<br><br><b><b>-V</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the version number of the <b>pidstat</b> command and exit.<br><br><b><b>-w</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Report context switch statistics, showing voluntary (cswch/s) and non-voluntary (nvcswch/s) context switches per second.<br><br><b><b><I>interval</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The time interval in seconds between each report. If omitted, <b>pidstat</b> prints a single report.<br><br><b><b><I>count</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The number of reports to display. If specified with <I>interval</I>, <b>pidstat</b> will exit after <I>count</I> reports. Otherwise, it runs continuously.<br><br>


title: DESCRIPTION
content:
<b>pidstat</b> is a command-line tool used to monitor and report detailed statistics for individual Linux tasks, including processes and threads. It provides insights into CPU utilization, memory consumption, I/O activity, context switches, and stack usage for specific PIDs or all active processes. This tool is invaluable for performance tuning, troubleshooting, and understanding process behavior on a system. As part of the <I>sysstat</I> utility collection, <b>pidstat</b> helps pinpoint resource bottlenecks at a granular process level, making it essential for system administrators and developers alike.


title: CAVEATS
content:
<b>pidstat</b> relies on data from the <I>/proc</I> filesystem, so its accuracy and available metrics depend on the kernel version and configuration.<br>It requires the <I>sysstat</I> package to be installed on the system.<br>High monitoring frequencies with many processes can impose minor system overhead.<br>Some advanced metrics might require specific kernel capabilities or root privileges.


title: <B>DEFAULT BEHAVIOR</B>
content:
If no specific options are provided, <b>pidstat</b> defaults to reporting CPU utilization statistics (as if <b>-u</b> was specified) for all active processes, presenting a single snapshot.


title: <B>CONTINUOUS MONITORING</B>
content:
When <b><I>interval</I></b> is specified without <b><I>count</I></b>, <b>pidstat</b> provides continuous reports until interrupted (e.g., by <b>Ctrl+C</b>). This is useful for real-time monitoring of process activity.


title: <B>INTERPRETING OUTPUT</B>
content:
The output columns of <b>pidstat</b> vary based on the options used. Common columns include PID, %usr, %system, %CPU (CPU utilization), minflt/s, majflt/s (memory faults), kB_rd/s, kB_wr/s (I/O), cswch/s, nvcswch/s (context switches). Refer to the man page for full column descriptions.


title: HISTORY
content:
<b>pidstat</b> is part of the <I>sysstat</I> utilities, a suite of performance monitoring tools for Linux. It was introduced to provide detailed, per-process statistics, complementing the system-wide reports offered by tools like <I>sar</I> and <I>iostat</I>. The <I>sysstat</I> project, maintained by Sébastien Godard, has been under continuous development since 1999, with <b>pidstat</b> evolving to offer increasingly granular insights into process behavior.


title: SYNOPSIS
content:
<b>pig</b> [<i>-f script_file</i>] [<i>-x execution_mode</i>] [<i>-p name=value</i>]... [<i>-D property=value</i>]... [<i>arguments...</i>]<br><i><br>To launch the Grunt shell:</i><br><b>pig</b> [<i>-x execution_mode</i>] [<i>-D property=value</i>]...


title: PARAMETERS
content:
<b><i>-x local|mapreduce|tez|spark</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies the execution mode for Pig. `local` runs on the local filesystem, `mapreduce` uses Hadoop MapReduce, `tez` uses Apache Tez, and `spark` uses Apache Spark as the execution engine.</i><br><br><b><i>-f script_file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Executes the Pig Latin script specified by `script_file`.</i><br><br><b><i>-p name=value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Sets a parameter within the Pig script, allowing for dynamic values. Can be specified multiple times.</i><br><br><b><i>-D property=value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Sets a system property for the Pig execution, overriding default configurations. Can be specified multiple times.</i><br><br><b><i>-l log_file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies the path for the Pig log file.</i><br><br>


title: DESCRIPTION
content:
<i>The <B>pig</B> command is the primary interface for Apache Pig, a high-level platform designed for analyzing large datasets using Hadoop. It provides a powerful scripting language called Pig Latin, which abstracts the complexities of MapReduce programming. Users can leverage the <B>pig</B> command to execute Pig Latin scripts in batch mode, or to interactively explore and process data using the Grunt shell. Pig is particularly useful for ETL (Extract, Transform, Load) operations, data warehousing, and general data analysis on massive datasets stored in HDFS or other compatible file systems. It translates Pig Latin scripts into a series of MapReduce jobs, enabling scalable and fault-tolerant data processing across a Hadoop cluster. The command supports various execution modes, including local mode for development and testing, and Tez or Spark modes for production environments, offering flexibility in how data transformations are performed.</i>


title: CAVEATS
content:
<i><br>The <B>pig</B> command requires a Java Runtime Environment (JRE) and typically a Hadoop installation to function correctly, especially for distributed execution modes. Its performance is heavily dependent on the underlying Hadoop cluster configuration and resource availability. Debugging Pig scripts can sometimes be challenging due to the compilation into MapReduce jobs.</i>


title: <I>GRUNT SHELL</I>
content:
<i>When the <B>pig</B> command is invoked without a script file (e.g., `pig -x local`), it launches the Grunt shell. This interactive command-line interface allows users to execute Pig Latin commands one by one, test queries, and inspect data. It's an invaluable tool for prototyping and debugging Pig scripts.</i>


title: <I>PIG LATIN</I>
content:
<i>Pig Latin is the high-level data flow language used by Apache Pig. It provides relational-style operators like JOIN, GROUP, ORDER BY, and FILTER, as well as functions for data manipulation. Pig Latin scripts are compiled into MapReduce jobs, or jobs for other execution engines, by the Pig framework.</i>


title: HISTORY
content:
<i>Apache Pig was developed at Yahoo! in 2006 to provide a higher-level abstraction for writing and optimizing MapReduce programs on Hadoop. It was open-sourced to the Apache Software Foundation in 2007 and became a top-level Apache project in 2009. The initial motivation was to enable researchers and analysts to quickly process large datasets without needing to write complex Java MapReduce code, focusing on data flow instead. Its usage became widespread in big data analytics environments before the rise of Spark and other frameworks.</i>


title: PARAMETERS
content:
<b>-d, --decompress, --uncompress</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Decompress. This is the default action if <i>pigz</i> is invoked as <i>unpigz</i>.<br><br><b>-z, --compress</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Compress. This is the default action if no operation option is specified.<br><br><b>-c, --stdout, --to-stdout</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Write output to standard output, keep original files unchanged. No progress indicator is displayed when writing to stdout.<br><br><b>-k, --keep</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Keep (don't delete) input files during compression or decompression.<br><br><b>-f, --force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force overwrite of existing output files. Also allows compressing symbolic links.<br><br><b>-p <NUM>, --processes <NUM>, --threads <NUM></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use <i>NUM</i> processors (threads) for compression/decompression. Default is the number of online processors. <i>NUM</i>=0 means use all online processors.<br><br><b>-r, --recursive</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Recurse into directories. If input is a directory, <i>pigz</i> will compress all files within it.<br><br><b>-l, --list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;List the contents of a compressed file. This option implies <i>-d</i>.<br><br><b>-t, --test</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Test compressed file integrity. This option implies <i>-d</i>.<br><br><b>-q, --quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress all warnings.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output. Displays information about compression ratios, processing files, etc.<br><br><b>-N, --name</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When compressing, retain the original name and timestamp in the compressed file header.<br><br><b>-n, --no-name</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When compressing, do not save the original name and timestamp.<br><br><b>-0 to -9</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Compression level, where <i>-1</i> is fastest compression (less compression ratio), and <i>-9</i> is best compression (slowest, but smallest file size). Default is <i>-6</i>.<br><br><b>--fast</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Equivalent to <i>-1</i>.<br><br><b>--best</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Equivalent to <i>-9</i>.<br><br><b>-b <SIZE>, --blocksize <SIZE></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the block size for compression. Suffixes like <i>K</i>, <i>M</i>, <i>G</i> can be used (e.g., <i>128K</i>). Default is 128K. Larger blocks can increase compression ratio but may use more memory.<br><br><b>-R, --rsyncable</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Produce an <i>rsync</i>-friendly archive. This adds a performance penalty and results in a slightly larger compressed file, but allows <i>rsync</i> to efficiently update parts of the compressed file.<br><br><b>--suffix <SUFFIX></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use <i>SUFFIX</i> instead of <i>.gz</i> as the compressed file name suffix.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display help message and exit.<br><br><b>-V, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display version information and exit.<br><br>


title: DESCRIPTION
content:
<p><i>pigz</i> is a parallel implementation of <i>gzip</i> that compresses and decompresses files using multiple processors and threads. While <i>gzip</i> is limited to a single CPU core, <i>pigz</i> leverages all available cores to significantly speed up compression and decompression operations, especially on large files or archives.</p><br><p>It is designed to be a drop-in replacement for <i>gzip</i>, producing a compatible <i>gzip</i> (.gz) file format, allowing files compressed by <i>pigz</i> to be decompressed by <i>gzip</i> and vice-versa. <i>pigz</i> achieves parallelism by splitting the input data into independent blocks, compressing each block concurrently, and then concatenating the compressed blocks. This makes it an invaluable tool in environments where high-performance data processing is critical, such as data centers, cloud computing, and big data applications.</p>


title: CAVEATS
content:
<ul><li><i>pigz</i> benefits most from multi-core processors and large files. For very small files, the overhead of parallelism might negate performance gains or even make it slightly slower than <i>gzip</i>.</li><li>The speedup is also limited by disk I/O performance. If your disk cannot keep up with the processing speed, <i>pigz</i> may become I/O bound.</li><li>The <i>--rsyncable</i> option is useful for incremental backups with <i>rsync</i>, but it incurs a performance overhead and can result in slightly larger compressed files.</li></ul>


title: ENVIRONMENT VARIABLE
content:
The <b>PIGZ</b> environment variable can be used to specify default options for <i>pigz</i>. For example, <b>PIGZ='-p 8'</b> would make <i>pigz</i> always use 8 threads by default.


title: PARALLEL DECOMPRESSION
content:
While <i>pigz</i> uses multiple threads for compression by splitting data into blocks, it can also parallelize decompression for files that were compressed by <i>pigz</i> itself (which include block headers). For files compressed by <i>gzip</i> or other tools without such headers, decompression remains largely single-threaded.


title: HISTORY
content:
<p><i>pigz</i> was created by <b>Mark Adler</b>, a prominent figure in data compression (also a co-author of the <i>zlib</i> library and the <i>gzip</i> specification). It was first released around 2007-2008 to address the increasing demand for faster compression on multi-core systems, as the original <i>gzip</i> was inherently single-threaded.</p><br><p>Its development focused on making it a direct, high-performance replacement for <i>gzip</i>, maintaining file format compatibility while significantly reducing processing times by leveraging parallelism. This made it quickly adopted in environments handling large datasets where compression speed was a bottleneck.</p>


title: SYNOPSIS
content:
<b>pihole</b> [<i>&lt;global-options&gt;</i>] <i>&lt;command&gt;</i> [<i>&lt;command-arguments&gt;</i>]


title: PARAMETERS
content:
<b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the main command or a specific subcommand.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the installed versions of Pi-hole core, web interface, and FTL components.<br><br><b><b>-d</b>, <b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Initiates a Pi-hole debug session, collecting diagnostic information for troubleshooting.<br><br><b><b>status</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the current operational status of the Pi-hole DNS blocker.<br><br><b><b>enable</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Activates Pi-hole's DNS blocking functionality.<br><br><b><b>disable</b> [<i>&lt;time&gt;</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deactivates Pi-hole's DNS blocking. An optional time (e.g., "<i>10s</i>", "<i>5m</i>", "<i>2h</i>") can be provided for temporary disabling.<br><br><b><b>whitelist</b> <i>&lt;domain&gt;</i> [<i>&lt;comment&gt;</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds domains to the whitelist, allowing them to bypass Pi-hole's blocking. Use <b>--del</b> to remove.<br><br><b><b>blacklist</b> <i>&lt;domain&gt;</i> [<i>&lt;comment&gt;</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds domains to the blacklist, ensuring they are blocked by Pi-hole. Use <b>--del</b> to remove.<br><br><b><b>updateGravity</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Downloads and updates the core ad-blocking lists (gravity database) from configured sources. This is a critical step for effective blocking.<br><br><b><b>restartdns</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Restarts the Pi-hole DNS resolver service (FTL).<br><br><b><b>flush</b> [<i>&lt;options&gt;</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Clears Pi-hole's DNS cache (<b>dns</b>) or its query logs (<b>logs</b>), or both (<b>all</b>).<br><br><b><b>tail</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the real-time stream of the Pi-hole FTL DNS query log.<br><br><b><b>updatePihole</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Updates the Pi-hole core software, web interface, and FTL components to their latest versions.<br><br><b><b>uninstall</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes the Pi-hole software from the system.<br><br>


title: DESCRIPTION
content:
Pi-hole is a popular, open-source Linux network-level advertisement and Internet tracker blocking application. It functions as a DNS sinkhole, intercepting DNS requests and blocking unwanted content for all devices connected to a network that uses Pi-hole as its DNS server.<br><br>The <b>pihole</b> command is the primary command-line interface for managing and interacting with your Pi-hole instance. It allows administrators to perform various tasks such as enabling or disabling blocking, adding domains to whitelist or blacklist, updating ad lists, viewing operational status, checking DNS query logs, and performing system-level updates for the Pi-hole software itself. This command consolidates many administrative functions, making it easy to control your network-wide ad blocking solution.


title: CAVEATS
content:
The <b>pihole</b> command typically requires elevated privileges (<i>sudo</i>) for most operations as it interacts with system services and network configurations. It is designed to manage an already installed Pi-hole system and will not function without a prior installation. Incorrect usage, particularly with commands like <b>updateGravity</b> or <b>flush</b>, can temporarily disrupt network connectivity if the DNS service is affected. Being a network-level tool, its effectiveness depends on client devices on the network being configured to use Pi-hole as their DNS server.


title: WEB INTERFACE
content:
Many of the administrative functions available via the <b>pihole</b> command-line tool can also be managed through Pi-hole's intuitive web interface, typically accessible at <i>http://&lt;Pi-hole-IP&gt;/admin</i> from a web browser on your network.


title: INSTALLATION
content:
The <b>pihole</b> command itself is part of the Pi-hole software suite, which is commonly installed via a single command executed on a compatible Linux system: <i>curl -sSL https://install.pi-hole.net | bash</i>. This script handles all necessary dependencies and initial configuration.


title: HISTORY
content:
Pi-hole was created by Jacob Salmela in 2015 as an open-source project designed to block ads on the network level. It quickly gained popularity as an effective, low-resource solution for ad-blocking across an entire network, often leveraging inexpensive hardware like the Raspberry Pi. The project has since grown into a robust, community-maintained ecosystem, with continuous development and feature additions, making it a widely adopted tool for network-wide ad and tracker blocking.


title: SYNOPSIS
content:
<b><I>pine</I></b> [<b><I>options</I></b>] [<b><I>address</I></b>]<br><b><I>pine</I></b> <b><I>-f</I></b> <b><I>folder</I></b><br><b><I>pine</I></b> <b><I>-a</I></b> <b><I>address</I></b>


title: PARAMETERS
content:
<b><b><I>-f &lt;folder&gt;</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a mail folder to open immediately upon starting <b><I>pine</I></b>.<br><br><b><b><I>-a &lt;address&gt;</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts <b><I>pine</I></b> in compose mode, pre-addressing a new message to the specified email address.<br><br><b><b><I>-i</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces <b><I>pine</I></b> to start in the main folder view, regardless of other command-line options.<br><br><b><b><I>-k</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Activates Kiosk mode, which restricts certain user actions for public terminal use.<br><br><b><b><I>-P &lt;file&gt;</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative configuration file to load instead of the default <b><I>.pinerc</I></b>.<br><br><b><b><I>-A &lt;account&gt;</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies which configured email account to use for the session, if multiple are set up.<br><br><b><b><I>-D</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables debugging output for troubleshooting purposes, typically logging to <b><I>stderr</I></b>.<br><br><b><b><I>-e</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces <b><I>pine</I></b> to use the external editor for message composition, even if an internal composer is configured.<br><br><b><b><I>-v</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the current version information of <b><I>pine</I></b> and then exits.<br><br><b><b><I>-h</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows a summary of command-line options and then exits.<br><br>


title: DESCRIPTION
content:
<b><I>pine</I></b> (Program for Internet News and Email) is a full-screen, text-based email and news client designed for ease of use. Developed at the University of Washington, it gained significant popularity in the 1990s as a user-friendly alternative to more complex mail programs. <b><I>pine</I></b> provides a simple, menu-driven interface, making it accessible even for novice users navigating email via a terminal. Key features include composing, reading, replying to, and forwarding email messages, along with robust address book management, folder organization, and support for MIME attachments. Its intuitive navigation, often relying on simple commands and context-sensitive help, contributed to its widespread adoption, especially in educational and Unix environments. While largely superseded by its open-source successor, <b><I>alpine</I></b>, and graphical email clients, <b><I>pine</I></b> remains a notable part of Linux and Unix history for its significant contribution to accessible terminal-based communication.


title: CAVEATS
content:
While historically significant, <b><I>pine</I></b> is largely unmaintained and has been superseded by its open-source successor, <b><I>alpine</I></b>. Using <b><I>pine</I></b> on modern systems might pose compatibility issues or security risks due to lack of updates for new protocols or vulnerabilities. It may also require manual compilation or be unavailable in standard package repositories for many contemporary Linux distributions.


title: <B>INTERFACE AND NAVIGATION</B>
content:
<b><I>pine</I></b> operates with a clear, menu-driven interface at the bottom of the screen, providing context-sensitive options and keybindings. Navigation is typically performed using arrow keys, page up/down, and common Emacs-like key combinations, making it relatively easy to learn for new users.


title: <B>CONFIGURATION</B>
content:
User preferences and account settings in <b><I>pine</I></b> are managed through the <b><I>.pinerc</I></b> file, usually located in the user's home directory. This file allows for extensive customization of behavior, display, and server configurations, including server details, display options, and signature settings.


title: HISTORY
content:
<b><I>pine</I></b> was developed by the University of Washington in the early 1990s, with its first public release around 1992. It quickly gained traction due to its innovative, user-friendly interface in a landscape dominated by more complex command-line mail readers like <b><I>elm</I></b> and <b><I>mailx</I></b>. Its development was largely driven by the need for an intuitive email client for university students and staff. Over time, licensing restrictions on <b><I>pine</I></b>'s components led to the creation of <b><I>alpine</I></b>, an open-source version, ensuring its legacy and continued development under a free software license. The last official release of <b><I>pine</I></b> was version 4.64 in 2005.


title: SYNOPSIS
content:
<code>python3 ping.py [OPTIONS] DESTINATION</code><br>or if executable:<br><code>./ping.py [OPTIONS] DESTINATION</code><br><br><code>DESTINATION</code> can be an IP address (e.g., <b>8.8.8.8</b>) or a hostname (e.g., <b>google.com</b>).


title: PARAMETERS
content:
<b><b>-c COUNT</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stop after sending <code>COUNT</code> echo request packets.<br><br><b><b>-i INTERVAL</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Wait <code>INTERVAL</code> seconds between sending each packet.<br><br><b><b>-s PACKETSIZE</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the number of data bytes to be sent. Default is 56 (64 ICMP data + IP header).<br><br><b><b>-t TTL</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the IP <i>Time To Live (TTL)</i> for outgoing packets. <code>TTL</code> specifies the maximum number of IP routers that the packet can traverse.<br><br><b><b>-W TIMEOUT</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Time in seconds to wait for a reply for each packet. If a reply is not received within this timeout, the packet is considered lost.<br><br>


title: DESCRIPTION
content:
<code>ping.py</code> is conceptualized as a Python script that replicates the core functionality of the ubiquitous <code>ping</code> command. Its primary purpose is to test the reachability of a host on an Internet Protocol (IP) network and to measure the round-trip time (RTT) for messages sent from the originating host to a destination computer. The script would typically send <i>Internet Control Message Protocol (ICMP)</i> echo request packets to the target host and await ICMP echo replies.<br><br>Upon receiving replies, <code>ping.py</code> would display statistics including the RTT (minimum, average, maximum), packet loss percentage, and TTL (Time To Live) of the received packets. This information is invaluable for network troubleshooting, diagnosing connectivity issues, assessing network latency, and verifying DNS resolution. While the standard <code>ping</code> command is a compiled binary, a Python implementation like <code>ping.py</code> allows for greater flexibility, scripting integration, and educational purposes, potentially leveraging Python's network libraries like <code>socket</code> or <code>scapy</code> for raw socket operations.


title: CAVEATS
content:
<ul><li><b>Raw Socket Permissions:</b> On Linux, sending and receiving raw ICMP packets typically requires root privileges (or specific capabilities like <code>CAP_NET_RAW</code>). A <code>ping.py</code> script might require <code>sudo</code> to run effectively.</li><li><b>Firewall Blocking:</b> Many firewalls block ICMP echo requests (ping) for security or privacy reasons, which can lead to false negatives regarding host reachability.</li><li><b>Accuracy:</b> While <code>ping</code> provides RTT, it's an estimate and can be affected by network congestion, server load, and intermediate devices.</li><li><b>Script Limitations:</b> A Python implementation might not support all advanced features or optimizations of the native <code>ping</code> utility, depending on its complexity and library usage.</li></ul>


title: ICMP PROTOCOL
content:
<code>ping.py</code> heavily relies on the <i>Internet Control Message Protocol (ICMP)</i>. ICMP is a core protocol of the Internet Protocol Suite, used by network devices to send error messages and operational information indicating, for example, that a requested service is not available or that a host or router could not be reached. ICMP echo requests and replies are the specific message types used by <code>ping</code>.


title: COMMON USE CASES
content:
Beyond basic connectivity checks, <code>ping.py</code> (like its native counterpart) is used to:<br> - Quickly verify if a server is online.<br> - Measure network latency to a specific host.<br> - Detect packet loss on a network path.<br> - Troubleshoot DNS resolution issues (by pinging both IP and hostname).


title: HISTORY
content:
The original <code>ping</code> utility was written by <i>Mike Muuss</i> in December 1983 at the US Army Ballistic Research Laboratory. He named it after the sound of a sonar, which uses acoustic pulses to detect underwater objects. It quickly became an indispensable tool for network diagnostics. While <code>ping.py</code> is not a historical command itself, Python implementations of network utilities like <code>ping</code> are commonly developed for educational purposes, rapid prototyping, and scenarios where a scripting language offers advantages over compiled binaries, often leveraging Python's rich ecosystem of networking libraries.


title: PARAMETERS
content:
<b>-c <I>count</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stop after sending <I>count</I> ECHO_REQUEST packets.<br><br><b>-s <I>packetsize</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the number of data bytes to be sent in the packets.<br><br><b>-i <I>interval</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Wait <I>interval</I> seconds between sending each packet.<br><br><b>-h <I>hoplimit</I> / -t <I>hoplimit</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the IPv6 hop limit for the packets.<br><br><b>-v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Verbose output.<br><br><b>-q</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Quiet output, showing only summary lines.<br><br><b>-n</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Numeric output only. No reverse DNS lookup for host addresses.<br><br><b>-D</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print timestamps before each line.<br><br><b>-M <I>pmtudisc_option</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path MTU Discovery options (e.g., <I>do</I>, <I>dont</I>, <I>probe</I>).<br><br><b>-I <I>interface_or_address</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the source interface or address to send packets from.<br><br><b>-L</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress loopback of multicast packets.<br><br><b>-P</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Don't fragment packets (sets the 'Don't Fragment' bit).<br><br><b>-w <I>timeout</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exit after <I>timeout</I> seconds, regardless of packets sent or received.<br><br><b>-W <I>timeout</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Time in seconds to wait for a reply for each packet.<br><br>


title: DESCRIPTION
content:
The <b>ping6</b> command is the <I>IPv6 equivalent</I> of the traditional <b>ping</b> utility. It is used to diagnose the reachability of an IPv6 host on an Internet Protocol (IP) network and to measure the round-trip time for packets sent from the local host to a destination computer. <br><br>It operates by sending <I>ICMPv6 Echo Request</I> packets to the target host and listening for <I>ICMPv6 Echo Reply</I> packets. <b>ping6</b> provides vital information such as packet loss percentage, minimum, average, and maximum round-trip times, which are crucial for identifying network performance bottlenecks, routing issues, or firewall configurations that might be blocking traffic over an IPv6 network.


title: CAVEATS
content:
<b>Root Privileges:</b> May require <I>root privileges</I> for certain operations (e.g., opening raw sockets on older systems), though many modern Linux distributions allow non-root users to execute it.<br><br><b>Firewall Blocking:</b> Firewalls (both host-based and network-based) can block <I>ICMPv6</I> packets, leading to perceived packet loss or unreachable hosts, even if other traffic might pass.<br><br><b>Local Connectivity Only:</b> Only measures connectivity from the <I>local host</I>; it doesn't indicate if other hosts can reach the target.<br><br><b>Packet Loss Causes:</b> High packet loss can indicate network congestion, misconfiguration, or an unreachable host.


title: ICMPV6 ECHO MECHANISM
content:
At its core, <b>ping6</b> utilizes <I>ICMPv6 Echo Request</I> (Type 128) and <I>Echo Reply</I> (Type 129) messages. These messages are fundamental for network diagnostics, allowing a host to determine if another host is reachable and how long it takes for a packet to make a round trip.


title: OUTPUT INTERPRETATION
content:
Understanding the output of <b>ping6</b> is crucial. Key metrics include the <I>round-trip time</I> (min/avg/max), which indicates latency, and the <I>packet loss percentage</I>, which signals potential network congestion or reachability issues. Messages like 'Destination Unreachable' or 'Hop Limit Exceeded' provide further diagnostic clues.


title: HISTORY
content:
The original <I>ping</I> utility was created by Mike Muuss in 1983. As <I>IPv6</I> gained prominence and became essential for modern networking, the need for an equivalent diagnostic tool arose. <b>ping6</b> was developed as part of the <I>iputils</I> package to provide identical functionality for <I>IPv6</I> networks, ensuring consistency in network troubleshooting practices across both IP versions. Its development reflects the ongoing evolution and adoption of <I>IPv6</I> globally.


title: SYNOPSIS
content:
<b>python3</b> <b>ping6.py</b> [OPTIONS] <I>destination</I><br>or<br><b>./ping6.py</b> [OPTIONS] <I>destination</I> (if executable and shebang is present)


title: PARAMETERS
content:
<b><I>destination</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The target IPv6 address or hostname to send ICMPv6 Echo Request packets to. This is typically a mandatory argument.<br><br><b><b>-c</b> <I>count</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the number of Echo Request packets to send. The command will exit after sending this many packets and receiving their replies or timing out.<br><br><b><b>-t</b> <I>timeout</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum time in seconds to wait for a reply to a single Echo Request. If a reply is not received within this period, the packet is considered lost.<br><br><b><b>-i</b> <I>interval</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the interval in seconds between sending each Echo Request packet. This prevents flooding the network.<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, displaying more detailed information about the sent and received packets, including ICMPv6 header details or specific error messages.<br><br>


title: DESCRIPTION
content:
The <b>ping6.py</b> command, typically a custom or educational Python script, provides a basic implementation of the Internet Control Message Protocol version 6 (ICMPv6) Echo Request and Echo Reply mechanism. Similar in functionality to the standard <b>ping6</b> utility, it is used to test the reachability of an IPv6 host on an IP network and and to measure the round-trip time for messages sent from the originating host to a destination computer. Unlike the compiled C-based <b>ping6</b> executable, <b>ping6.py</b> leverages Python's networking capabilities, often utilizing raw sockets or specialized libraries like Scapy, to construct and dissect ICMPv6 packets. Its primary purpose is to diagnose network connectivity issues, verify host availability, and assess network latency for IPv6-only or dual-stack environments. The exact features and options available in <b>ping6.py</b> can vary significantly depending on its specific implementation, as it is not a universally standardized command found in Linux distributions. It serves as an excellent tool for learning network programming or for specialized testing scenarios where a lightweight, scriptable IPv6 ping utility is desired.


title: CAVEATS
content:
As <b>ping6.py</b> is typically a custom Python script, its exact functionality, available options, and behavior can vary widely. It may require specific Python libraries (e.g., <b>scapy</b>, <b>socket</b>) to be installed. Running <b>ping6.py</b> often requires root privileges due to the need to create raw sockets for ICMPv6 packet manipulation, similar to the standard <b>ping6</b> command. Error handling and performance might not be as robust or optimized as the system's compiled <b>ping6</b> utility. Users should consult the script's source code or any provided documentation for precise usage details.


title: EXECUTION REQUIREMENTS
content:
<b>ping6.py</b> typically requires the Python interpreter (usually Python 3) to be installed on the system. Depending on its implementation, it may also necessitate specific third-party Python libraries, such as <b>scapy</b> for advanced packet crafting, which need to be installed via <b>pip</b>. Due to the nature of ICMP packet manipulation, the script often needs to be run with elevated privileges (e.g., using <b>sudo</b>) to create and bind raw sockets.


title: USE CASES
content:
Beyond basic connectivity testing, <b>ping6.py</b> can be particularly useful in educational settings for demonstrating IPv6 networking principles, in development environments for testing custom network stacks, or in security contexts for building specialized scanning or reconnaissance tools where scriptable control over ICMPv6 packets is desired. Its Pythonic nature makes it easily extensible and integratable into larger automation scripts.


title: HISTORY
content:
The concept of <b>ping</b> originated in 1983, created by Mike Muuss, to troubleshoot network problems. With the advent and growth of IPv6, the need for an equivalent tool emerged, leading to the development of <b>ping6</b> for IPv6 networks. While the official <b>ping6</b> utility is typically a compiled C program, the rise of Python as a powerful scripting language for network automation and security led to various independent implementations of <b>ping6</b> in Python. These <b>ping6.py</b> scripts are not part of the standard Linux distribution but are commonly developed for educational purposes, rapid prototyping, custom network testing, or as components of larger network analysis frameworks (e.g., using libraries like Scapy or raw socket programming). Their history is tied to the general evolution of network diagnostics and the increasing popularity of Python for network-related tasks.


title: PARAMETERS
content:
<b><b>-l</b>, <b>--long</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><b>Use the long output format, providing more detailed information about users.</b></i><br><br><b><b>-s</b>, <b>--short</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><b>Use the short output format. This is the default behavior when no arguments are given.</b></i><br><br><b><b>-b</b>, <b>--birth</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><b>Display the user's birth date, if available.</b></i><br><br><b><b>-h</b>, <b>--home</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><b>Show the user's home directory.</b></i><br><br><b><b>-p</b>, <b>--plan</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><b>Display the content of the user's <b>.plan</b> file.</b></i><br><br><b><b>-a</b>, <b>--all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><b>Show all available information for a user, excluding <b>.plan</b> and <b>.project</b> files.</b></i><br><br><b><b>-f</b>, <b>--full</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><b>Display the user's full name rather than just the first name.</b></i><br><br><b><b>-q</b>, <b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><b>Suppress the header line that normally appears at the top of the output.</b></i><br><br>


title: DESCRIPTION
content:
<i><b>pinky</b></i> is a program that provides basic information about users currently logged into the system or specified users. It serves as a stripped-down, lighter version of the more verbose <i><b>finger</b></i> command. While <i><b>finger</b></i> often displays extensive details, <i><b>pinky</b></i> focuses on delivering essential user data quickly and efficiently.<br><br>By default, when invoked without any arguments, <i><b>pinky</b></i> lists the login names, real names, terminal lines, idle times, and login times of all logged-in users. When one or more usernames are provided as arguments, it displays similar information specifically for those users. Its lightweight nature makes it ideal for environments where minimal output and resource usage are preferred, or when a quick glance at user activity is needed without the full overhead of <i><b>finger</b></i>. It's a common utility found in most Linux distributions as part of the <i><b>util-linux</b></i> package.


title: CAVEATS
content:
<i><b>pinky</b></i> typically provides less information by default compared to the more comprehensive <i><b>finger(1)</b></i> command.<br><br>The amount and type of information displayed (e.g., birth date, office location, <i><b>.plan</b></i> file content) are dependent on how the system is configured and what privacy settings users have enabled or disabled.<br><br>Unlike <i><b>finger(1)</b></i>, <i><b>pinky</b></i> is primarily designed for querying local user information and does not support querying remote finger servers directly.


title: HISTORY
content:
The <i><b>pinky</b></i> command originated as a stripped-down alternative to the traditional <i><b>finger(1)</b></i> command. It was developed to offer a more lightweight and privacy-conscious way of retrieving basic user information on Unix-like systems. It is part of the widely used <i><b>util-linux</b></i> project, a collection of essential system utilities found on most Linux distributions. Its development reflects a trend towards providing leaner, more focused tools for common administrative and informational tasks, reducing overhead and potential information exposure.


title: SYNOPSIS
content:
<b>pinout</b> [<i>OPTIONS</i>] [<i>DEVICE_OR_BOARD</i>]<br>Common Usage:<br><b>pinout</b> <i><board_name></i><br><b>pinout</b> <i><board_name></i> --json<br><b>pinout</b> --list<br><b>pinout</b> --help


title: PARAMETERS
content:
<b><i>DEVICE_OR_BOARD</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the specific board or device for which to display the pinout. If omitted, and no --board or --device is specified, it may default to a common board or prompt for selection.<br><br><b><b>--help</b>, <b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message detailing command usage and available options.<br><br><b><b>--version</b>, <b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the program's current version number.<br><br><b><b>--list</b>, <b>-l</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all available boards and devices that <b>pinout</b> can recognize and display.<br><br><b><b>--board</b> <i>&lt;BOARD_NAME&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly specifies the board name for which to show the pinout. Useful when a board name might conflict with a device name or for clarity.<br><br><b><b>--device</b> <i>&lt;DEVICE_NAME&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly specifies the device name for which to show the pinout.<br><br><b><b>--json</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the pinout data in JSON format, suitable for programmatic parsing.<br><br><b><b>--svg</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates the pinout diagram as an SVG (Scalable Vector Graphics) file. Requires the 'svglib' library.<br><br><b><b>--png</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates the pinout diagram as a PNG (Portable Network Graphics) image. This usually requires the 'librsvg' library and 'cairo' or similar rendering backend to be installed on the system.<br><br><b><b>--style</b> <i>&lt;STYLE_NAME&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a specific visual style to the generated diagram. Available styles may vary depending on the installation.<br><br><b><b>--config</b> <i>&lt;FILE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative configuration file to use instead of the default.<br><br><b><b>--verbose</b>, <b>-V</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, showing more detailed information about the command's execution and any encountered issues.<br><br><b><b>--search</b> <i>&lt;TERM&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Searches for boards or devices matching the provided term in their name or description.<br><br>


title: DESCRIPTION
content:
The <b>pinout</b> command-line tool provides a convenient way to display pinout diagrams for various embedded boards and devices directly in your terminal. It leverages a comprehensive database of hardware, including popular Single Board Computers (SBCs) like Raspberry Pi, BeagleBone, and various microcontrollers. Users can query specific boards or devices to retrieve their pin configurations, including signal names, functions, and physical locations. Beyond interactive terminal display (often using ASCII art), <b>pinout</b> supports exporting diagrams into machine-readable formats like JSON, or graphical formats such as SVG and PNG, making it invaluable for documentation and integration into other tools. This utility streamlines the process of referencing complex hardware interfaces, aiding developers, students, and hobbyists in rapid prototyping and troubleshooting tasks without needing to consult external datasheets or websites.


title: CAVEATS
content:
The <b>pinout</b> command is typically a Python-based utility and is not a core Linux command, meaning it usually needs to be installed separately (e.g., via <i>pip</i>).<br>PNG output functionality often depends on external system libraries like <i>librsvg</i> and potentially <i>cairo</i> for rendering, which may need to be installed manually.<br>The accuracy and completeness of pinout diagrams depend on the underlying database of boards and devices, which is maintained by the community and can vary over time. Terminal display quality can be affected by terminal font, encoding, and window width.


title: OUTPUT FORMATS
content:
<b>pinout</b> is versatile in its output. By default, it renders an ASCII art diagram directly in the terminal. However, it can also generate JSON for structured data access, or high-quality graphical outputs like SVG (Scalable Vector Graphics) and PNG (Portable Network Graphics) for integration into documents or web pages. This flexibility allows users to choose the most suitable format for their specific needs, from quick lookups to detailed documentation.


title: EXTENSIBILITY AND CONFIGURATION
content:
A key strength of <b>pinout</b> is its extensibility. It allows users to manage and expand its database of boards and devices, making it adaptable to new hardware. Users can also define custom styles to change the visual presentation of diagrams. Configuration files allow for persistent settings, including default boards, output formats, and stylistic preferences, enhancing user experience and productivity.


title: HISTORY
content:
The <b>pinout</b> utility emerged from the embedded systems and open-source hardware communities, notably championed by initiatives like Adafruit. Developed primarily in Python, it addresses the common challenge of quickly referencing pin assignments on various Single Board Computers (SBCs) and microcontrollers without constantly consulting extensive documentation. Its development reflects the growing popularity of DIY electronics and embedded Linux, providing an accessible command-line interface for what was previously a manual, often tedious, lookup process. It aims to standardize and simplify access to essential hardware interface information for developers and hobbyists alike.


title: SEE ALSO
content:
<b>lshw</b>(1) - List hardware, <b>lspci</b>(8) - List all PCI devices, <b>lsusb</b>(8) - List USB devices


title: SYNOPSIS
content:
<i>No standard synopsis available for a universally recognized 'pint' Linux command.</i> Its usage would be entirely dependent on its specific implementation or context.


title: PARAMETERS
content:
<b><i>N/A</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>As 'pint' is not a standard command, there are no universally defined parameters or options. Any parameters would be specific to its particular implementation or script.</i><br><br>


title: DESCRIPTION
content:
The command 'pint' is <b>not a standard, universally recognized utility</b> found in typical Linux distributions like Ubuntu, Fedora, or Debian. Unlike commands such as <i>ls</i> or <i>grep</i>, 'pint' does not have a predefined man page or a common presence in the default system PATH. It is highly probable that 'pint' refers to a component or executable specific to a particular software package, a custom script, or a specialized environment.<br><br>For instance, 'pint' might be associated with:<br><ul><li>A Python library named 'pint' used for unit manipulation, which is consumed within Python scripts rather than being a standalone command-line tool.</li><li>A plugin or internal utility within a larger system like FreeIPA, which might expose 'pint' as a subcommand or an internal component.</li><li>A locally developed script or alias named 'pint' that performs specific tasks on a user's or organization's system.</li></ul><br>Without further context regarding its origin or specific software association, providing a general analysis of 'pint' as a standalone Linux command is not feasible.


title: CAVEATS
content:
This command is <b>not part of standard Linux distributions</b>. Any information provided is based on potential non-standard usage or as a component of specific software packages. Users encountering 'pint' should investigate its origin within their specific system or environment (e.g., check custom scripts, installed software packages, or developer documentation for specific applications).


title: HISTORY
content:
<i>No public history exists for 'pint' as a standalone, general-purpose Linux command.</i> Its origins would be tied to the specific project or individual that created it for a particular purpose.


title: PARAMETERS
content:
<b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message with command-line options and exits.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the Pinta application version information and exits.<br><br><b><b>--new</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Launches Pinta and creates a new, blank image document.<br><br><b><b>--open</b> <i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens the specified image <i>FILE</i> in Pinta. This is the default action if a file path is provided without this option.<br><br>


title: DESCRIPTION
content:
<br>Pinta is a free, open-source drawing and image editing program for Linux, Windows, and macOS. Inspired by Paint.NET, it aims to provide a powerful yet intuitive interface for various image manipulation tasks. Key features include support for image layers, a wide range of adjustment tools (brightness, contrast, hues), over 35 effects, and a history window to easily undo or redo changes. Pinta is designed to be accessible for casual users while still offering capabilities for more advanced editing, making it a popular choice for quick edits, basic drawing, and photo retouching.


title: CAVEATS
content:
<br>Pinta is primarily a graphical user interface (GUI) application. Its command-line options are limited to launching the application, opening specific files, or displaying basic information. Extensive image manipulation is performed interactively within the GUI, not via command-line arguments. It relies on the Mono framework for execution.


title: GUI-CENTRIC OPERATION
content:
<br>While Pinta can be launched from the command line, its full functionality for drawing, editing, and applying effects is exclusively available through its interactive graphical user interface. Users primarily interact with Pinta through its toolbars, menus, and canvas, rather than through command-line arguments.


title: LAYER SUPPORT
content:
<br>A core feature of Pinta is its support for image layers, allowing users to organize different elements of an image independently. This enables non-destructive editing and complex compositions, a capability often found in more advanced image manipulation software.


title: HISTORY
content:
<br>Pinta was originally created by Jonathan Pobst in 2010 as an open-source alternative inspired by the popular Windows application Paint.NET, which lacked a native Linux version. The goal was to provide a simple, powerful, and cross-platform image editor. It is written in C# and utilizes the GTK toolkit, running on the Mono framework. Over the years, it has gained a steady following for its ease of use and essential features.


title: SYNOPSIS
content:
<b>pio</b> [<i>options</i>] <i>command</i> [<i>command_options</i>]<br><br>Common <i>commands</i> include:<br><b>run</b>: Build and upload project.<br><b>build</b>: Compile project firmware.<br><b>upload</b>: Upload firmware to a device.<br><b>test</b>: Run project tests.<br><b>lib</b>: Manage project libraries.<br><b>board</b>: List and inspect development boards.<br><b>project</b>: Manage PlatformIO projects.<br><b>device</b>: Manage connected serial devices.<br><b>home</b>: Open PlatformIO Home GUI.<br><b>account</b>: Manage PlatformIO account.<br><b>settings</b>: Manage PlatformIO settings.<br><b>update</b>: Update installed platforms and libraries.<br><b>upgrade</b>: Upgrade PlatformIO Core.


title: PARAMETERS
content:
<b>-v, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the version information for PlatformIO Core.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show a help message and exit. Can be used with a <i>command</i> to show specific help (e.g., <b>pio run -h</b>).<br><br><b>--force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the operation to proceed without confirmation.<br><br><b>--json-output</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the output in JSON format, useful for scripting and integration.<br><br><b>--keep-symbols</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Keep debugging symbols in the compiled firmware (if supported by the platform).<br><br><b>--no-ansi</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable ANSI escape codes in the output.<br><br><b>--no-color</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable colored output.<br><br><b>--no-progress</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable the progress bar during operations like downloading or compiling.<br><br>


title: DESCRIPTION
content:
The <b>pio</b> command is the command-line interface (CLI) for PlatformIO, an open-source ecosystem designed for professional embedded and IoT development.<br>It provides a comprehensive set of tools to simplify software development for a vast range of microcontrollers and single-board computers.<br>With <b>pio</b>, developers can manage project scaffolding, build and compile firmware, upload binaries to devices, handle library dependencies, and configure various development boards and platforms.<br>PlatformIO aims to make embedded development more accessible, reproducible, and portable across different operating systems by abstracting away complex toolchain configurations and offering a unified build system.


title: CAVEATS
content:
The <b>pio</b> command is not a standard Linux utility; it is part of the PlatformIO ecosystem and typically installed via Python's <b>pip</b> package manager.<br>It requires a Python environment to run.<br>Initial setup or project creation may involve downloading significant amounts of data, including toolchains, frameworks, and platform packages, which can consume disk space and bandwidth.<br>While powerful, its abstraction layers can sometimes obscure underlying build system details, making advanced debugging or customization challenging for beginners.


title: PROJECT ENVIRONMENTS
content:
PlatformIO uses project environments, defined in the <i>platformio.ini</i> configuration file, to specify different build configurations for a single project.<br>Each environment can target a specific board, framework, or even a different toolchain, allowing developers to easily switch between targets or build for multiple devices from the same codebase. This promotes modularity and reproducibility.


title: LIBRARY MANAGEMENT
content:
<b>pio</b> provides a robust library management system that simplifies dependency resolution and installation.<br>Developers can declare project dependencies in <i>platformio.ini</i>, and <b>pio</b> will automatically download and link the necessary libraries from the PlatformIO Registry, Git repositories, or local paths.<br>This ensures consistent builds and easier collaboration among developers.


title: HISTORY
content:
PlatformIO was founded in 2014 by Ivan Kravets with the goal of creating a unified, open-source development environment for embedded systems. The <b>pio</b> CLI has been central to its design from the outset, providing a flexible and powerful way to automate common embedded development tasks.<br>Over the years, the project has grown significantly, expanding its support for a vast array of development boards, microcontrollers, and IoT frameworks, transitioning from a simple build system to a full-fledged ecosystem that includes an IDE (VSCode integration), a rich library registry, and a remote development feature. The <b>pio</b> command remains the core interface for interacting with this ecosystem.


title: PARAMETERS
content:
<b><i>&lt;pio_device_id&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The identifier for the PIO device and state machine. This usually corresponds to the minor device number of <i>/dev/rp2040-pioX</i>. For example, '0' refers to <i>/dev/rp2040-pio0</i>, and '1' refers to <i>/dev/rp2040-pio1</i>. The command manages access to all state machines within that specific PIO block.<br><br><b><i>&lt;permission&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The action to perform: <b>allow</b> to grant access to non-root users, or <b>deny</b> to revoke it.<br><br>


title: DESCRIPTION
content:
The <i>pio-access</i> command on Linux systems (primarily Raspberry Pi OS) is used to control user-space access permissions to the Programmable I/O (PIO) state machines on RP2040-based devices. These state machines are crucial for low-level, high-speed hardware interaction.<br><br>By default, access to PIO devices like <i>/dev/rp2040-pio0</i> and <i>/dev/rp2040-pio1</i> might be restricted to the root user. <i>pio-access</i> allows an administrator to grant (or revoke) access for non-root users to specific PIO state machines, typically to facilitate the operation of development tools or custom applications that need direct control over the PIO hardware. This is essential for tools like <i>picotool</i> or <i>pico-debug</i> which often require direct interaction with the RP2040's PIO peripherals.


title: CAVEATS
content:
<b>•</b> Requires <b>root privileges</b> to execute, typically by using <i>sudo</i>.<br><b>•</b> Specific to <b>Raspberry Pi RP2040</b> based systems. It will not work on other Linux systems lacking the necessary hardware and kernel modules.<br><b>•</b> Modifying PIO access can impact system stability or security if not managed carefully, as it grants direct hardware control.<br><b>•</b> The respective <i>/dev/rp2040-pioX</i> device file must exist for the command to operate on it.


title: DEVICE FILES
content:
The command operates on kernel device files, typically found as <i>/dev/rp2040-pio0</i> and <i>/dev/rp2040-pio1</i>. These files represent the PIO blocks on the RP2040 chip, each containing multiple state machines.


title: TYPICAL USE CASE
content:
Often invoked as a pre-requisite for development tools such as <i>picotool</i> or <i>pico-debug</i>, which need direct communication with the RP2040 over USB or SWD (Serial Wire Debug) interfaces, often facilitated via PIO. Enabling access allows these tools to run without requiring root privileges themselves for every operation.


title: HISTORY
content:
The <i>pio-access</i> command emerged with the increasing popularity of the Raspberry Pi RP2040 microcontroller and the need for robust user-space tooling. It is part of the broader ecosystem developed to support the RP2040, providing a standardized way to manage critical hardware access that often requires root privileges. Its development is closely tied to projects like <i>libjaylink</i> and <i>openocd</i>, which are fundamental for debugging and flashing RP2040 devices.


title: PARAMETERS
content:
<b>--json</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Returns the command output in JSON format, useful for scripting and programmatic parsing.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message for the <i>pio account</i> command, detailing its usage, options, and available subcommands.<br><br><b>login</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Authenticates with a PlatformIO account. This subcommand typically prompts for email/username and password to establish a session.<br><br><b>logout</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Logs out from the currently authenticated PlatformIO account, removing local authentication credentials.<br><br><b>token</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manages PlatformIO account API tokens. This subcommand itself has further subcommands to create, list, and revoke tokens.<br><br>


title: DESCRIPTION
content:
The <i>pio account</i> command is a crucial subcommand of the PlatformIO command-line interface (CLI), designed to facilitate user interaction with PlatformIO's cloud services. It primarily manages user authentication, allowing users to <b>log in</b> to their PlatformIO accounts, <b>log out</b>, and securely manage API <b>tokens</b>.<br><br>This command is indispensable for developers utilizing PlatformIO's advanced features, such as remote development, private package registries, continuous integration/continuous delivery (CI/CD) pipelines, and syncing project data across environments. By handling authentication credentials and API tokens locally, <i>pio account</i> ensures secure and seamless access to these cloud-dependent functionalities, making it an integral part of a comprehensive embedded development workflow.


title: CAVEATS
content:
The command typically invoked is <i>pio account</i>, not <i>pio-account</i>. <i>pio-account</i> as a standalone binary is not standard within the PlatformIO ecosystem.<br>Requires PlatformIO Core CLI to be installed and accessible in the system's PATH. Full functionality requires an active PlatformIO account.


title: SUBCOMMANDS OF 'PIO ACCOUNT TOKEN'
content:
The <i>token</i> subcommand within <i>pio account</i> offers further operations for managing API tokens:<br><br><b>pio account token create</b>: Creates a new API token for programmatic access to PlatformIO services.<br><b>pio account token list</b>: Lists all active API tokens associated with the account.<br><b>pio account token revoke</b>: Revokes a specific API token, invalidating it immediately.


title: HISTORY
content:
The PlatformIO CLI, including its account management capabilities, has evolved significantly since its inception. The <i>pio account</i> functionality was introduced and enhanced as PlatformIO expanded its ecosystem to include cloud-based services like remote development, private registries, and CI/CD integration. Its development reflects the growing need for seamless and secure authentication to these online features, becoming a core component for users leveraging PlatformIO's broader capabilities.


title: SYNOPSIS
content:
<b>pio boards</b> [<i>OPTIONS</i>]<br><b>pio boards</b> <i>search</i> &lt;<i>query</i>&gt;<br><b>pio boards</b> <i>show</i> &lt;<i>ID</i>&gt;


title: PARAMETERS
content:
<b><i>--json-output</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output the command's results in machine-readable JSON format. Useful for scripting and integration with other tools.<br><br><b><i>--skip-description</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When listing boards, do not print the full description for each board, resulting in a more concise output.<br><br><b><i>--platform &lt;platform&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filter the list of boards to show only those supported by a specific development <i>platform</i> (e.g., <i>espressif32</i>, <i>ststm32</i>, <i>teensy</i>). The platform ID must be exact.<br><br><b><i>search &lt;query&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform a search for development boards where the board name or description contains the specified <i>query</i> string. This provides a flexible way to find boards without knowing their exact ID.<br><br><b><i>show &lt;ID&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display comprehensive, detailed information for a single development board identified by its unique <i>ID</i> (e.g., <i>nodemcuv2</i>, <i>esp32dev</i>). This includes hardware specifications, debugging capabilities, and supported frameworks.<br><br><b><i>--id &lt;ID&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Alternative to <i>show</i>) Display detailed information for a specific development board using its unique <i>ID</i>. This option can be used directly with the <b>pio boards</b> command.<br><br><b><i>--name &lt;name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filter and display boards where the board's name matches the specified <i>name</i>. This can be a partial match, making it useful for narrowing down results.<br><br>


title: DESCRIPTION
content:
The <b>pio-boards</b> command is an essential part of the PlatformIO Core CLI, designed to manage and display information about the vast collection of development boards supported by PlatformIO. <br>It empowers embedded developers to efficiently identify and select suitable hardware for their projects. Users can list all available boards, apply filters based on specific criteria like development platform, search for boards using keywords or partial names, or retrieve comprehensive, detailed specifications for a particular board by its unique ID. <br>This command provides critical insights into board capabilities, including the microcontroller unit (MCU), clock frequency, available memory (Flash and RAM), debugging interfaces, and supported development frameworks, making it indispensable for proper project setup and hardware selection.


title: CAVEATS
content:
The <b>pio-boards</b> command requires the PlatformIO Core CLI to be installed and accessible in the system's PATH.<br>Listing all boards without filters can produce a very extensive output, often hundreds of entries.<br>Board IDs used with <i>show</i> or <i>--id</i> are case-sensitive.


title: FILTERING AND SEARCHING CAPABILITIES
content:
Beyond simply listing, <b>pio boards</b> offers robust filtering via <i>--platform</i> and <i>--name</i>, and powerful keyword searching with the <i>search</i> subcommand. These features are indispensable for efficiently navigating the thousands of supported boards to find the exact hardware needed for a project.


title: COMPREHENSIVE BOARD DETAILS
content:
When using <i>show &lt;ID&gt;</i> or <i>--id &lt;ID&gt;</i>, the command provides an in-depth breakdown of a board's specifications. This includes details like the microcontroller unit (MCU), clock frequency, flash and RAM memory sizes, built-in debugging capabilities, and the specific development frameworks (e.g., Arduino, ESP-IDF) supported, which is vital for project configuration.


title: HISTORY
content:
<b>PlatformIO</b> was launched to address the complexities of embedded development. The <b>pio-boards</b> command has been a fundamental component of the PlatformIO CLI since its early days, continuously evolving to include support for an ever-growing list of microcontrollers and development boards. Its development parallels the rapid expansion of the IoT and embedded systems market, providing developers with an updated and comprehensive hardware catalog directly from the command line.


title: SYNOPSIS
content:
<code>pio debug [<I>OPTIONS</I>]</code><br>This command is executed within a PlatformIO project directory. It typically compiles the project in debug mode, uploads the firmware (if necessary), and then initiates a debug session, usually by launching a GDB client connected to the target.


title: PARAMETERS
content:
<b><code>--target &lt;target&gt;</code>, <code>-t &lt;target&gt;</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the debug target, e.g., <code>debug</code> (default), <code>upload</code> (program only), or <code>test</code>.<br><br><b><code>--environment &lt;env_name&gt;</code>, <code>-e &lt;env_name&gt;</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects a specific build environment from the <code>platformio.ini</code> file for the debug session.<br><br><b><code>--interface &lt;type&gt;</code>, <code>-i &lt;type&gt;</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the debug probe interface type, such as <code>jlink</code>, <code>stlink</code>, <code>cmsis-dap</code>, or <code>auto</code>.<br><br><b><code>--exit-after-upload</code>, <code>-x</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exits the debugger immediately after successfully uploading the firmware to the device.<br><br><b><code>--debugger-path &lt;path&gt;</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides the full path to the GDB executable to be used for debugging.<br><br><b><code>--init-break &lt;func&gt;</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets an initial breakpoint at the specified function name upon debugger startup.<br><br><b><code>--upload-port &lt;port&gt;</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the upload port for targets that require it (e.g., serial for some uploads).<br><br><b><code>--silent</code>, <code>-s</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses non-error output during the debug process.<br><br><b><code>--verbose</code>, <code>-v</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, showing detailed information about the debug session and commands.<br><br>


title: DESCRIPTION
content:
The <code>pio debug</code> command is a powerful utility within the PlatformIO Core, an open-source ecosystem designed for cross-platform embedded development. It provides a streamlined interface for debugging firmware directly on embedded devices, abstracting away much of the underlying complexity of debug probe configurations and GDB interactions. Developers can use <code>pio debug</code> to set breakpoints, inspect variables, step through code, and analyze runtime behavior for a wide range of microcontrollers. It supports various debug probes like J-Link, ST-Link, and CMSIS-DAP, and integrates seamlessly with external debuggers like GDB. This command is instrumental for identifying and resolving complex issues in embedded C/C++ applications, enhancing productivity for IoT and embedded system developers.


title: CAVEATS
content:
Debugging with <code>pio debug</code> requires the correct hardware setup, including a compatible debug probe connected to both the host computer and the target embedded device. The command's behavior is heavily influenced by the <code>[env:]</code> debug settings within the project's <code>platformio.ini</code> file. Debugging capabilities can vary significantly between different microcontroller architectures and debug probes, and some configurations may require specific drivers or firmware updates for the debug probe.


title: CONFIGURATION WITH <CODE>PLATFORMIO.INI</CODE>
content:
The <code>platformio.ini</code> project configuration file plays a central role in customizing <code>pio debug</code> sessions. Developers can specify the debug tool, port, speed, and other debug-related options under the <code>[env:]</code> sections. For example, <code>debug_tool = jlink</code>, <code>debug_port = /dev/ttyUSB0</code>, or custom <code>debug_build_flags</code> can be set here, allowing for fine-tuned control over the debugging environment without needing command-line arguments for every session.


title: GDB INTEGRATION
content:
<code>pio debug</code> primarily operates as a wrapper around the GNU Debugger (GDB). It automatically downloads and configures the correct GDB executable for the target architecture. When a debug session starts, <code>pio debug</code> launches GDB, connects it to the debug probe (often via a debug server like OpenOCD or J-Link GDB Server), and loads the compiled firmware. Users can then interact with the GDB prompt for advanced debugging commands or use an IDE's graphical debugger interface that communicates with this GDB instance.


title: VSCODE INTEGRATION
content:
PlatformIO's VSCode extension provides a rich graphical interface for <code>pio debug</code>. Within VSCode, developers can start debugging sessions with a single click, set breakpoints visually, inspect variables, view call stacks, and control program execution (step over, step into, continue). This integration significantly enhances the user experience by providing a familiar and intuitive debugging environment, making embedded debugging as accessible as debugging traditional software applications.


title: HISTORY
content:
PlatformIO was conceived to simplify embedded development. The <code>pio debug</code> command was developed as a crucial component to address the inherent complexities of embedded debugging. Historically, debugging microcontrollers involved manual configuration of GDB, debug servers (like OpenOCD), and specific hardware probes, which was error-prone and time-consuming. <code>pio debug</code> significantly abstracted this process, integrating these tools into a seamless workflow. Its evolution has focused on expanding support for diverse hardware platforms, debugging probes, and improving user experience, especially within the PlatformIO VSCode extension.


title: SYNOPSIS
content:
The conceptual <B>pio-device</B> functionality is accessed via the <B>pio device</B> command within the PlatformIO CLI.<br><br><B>pio device</B> <I>&lt;command&gt;</I> [<I>OPTIONS</I>]<br><br>Examples:<br><I>pio device list</I><br><I>pio device monitor -p /dev/ttyUSB0 -b 115200</I>


title: PARAMETERS
content:
<b><I>-p, --port</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the serial port to use for monitoring or other operations, e.g., <I>/dev/ttyUSB0</I> on Linux/macOS or <I>COM1</I> on Windows.<br><br><b><I>-b, --baud</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the baud rate for serial communication when monitoring, e.g., <I>9600</I>, <I>115200</I>.<br><br><b><I>-e, --echo</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Echoes local characters typed in the serial monitor back to the console.<br><br><b><I>-f, --filter</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies one or more filters to the serial monitor output, useful for processing or enhancing data, e.g., <I>colorize</I>, <I>time</I>, <I>default</I>.<br><br><b><I>--rts</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls the Request To Send (RTS) line state (0=off, 1=on) of the serial port.<br><br><b><I>--dtr</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls the Data Terminal Ready (DTR) line state (0=off, 1=on) of the serial port.<br><br><b><I>--exit-char</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the character sequence to exit the serial monitor, defaults to <I>Ctrl+C</I>.<br><br>


title: DESCRIPTION
content:
The <B>pio device</B> command is a subcommand of the PlatformIO (PIO) Core command-line interface. It provides essential tools for interacting with serial ports and connected hardware devices, which are fundamental for embedded systems and IoT development. Developers primarily use it to list available serial ports on the system, and to monitor serial communication from microcontrollers or other devices. This command is crucial for debugging firmware, viewing runtime output, and verifying device connectivity within the PlatformIO ecosystem. It significantly simplifies the process of interacting with hardware targets by abstracting away low-level serial port configurations and offering a user-friendly interface.


title: CAVEATS
content:
The <B>pio-device</B> command itself does not exist as a standalone executable in Linux. The functionality is provided by the <B>pio device</B> subcommand within the PlatformIO Core CLI. Users must have PlatformIO Core installed.<br><br>On Linux, access to serial ports typically requires the user to be part of the <I>dialout</I> or <I>uucp</I> group to prevent permission errors.


title: KEY SUBCOMMANDS
content:
The <B>pio device</B> command is primarily used with specific subcommands to perform actions:<br><br><B>list</B>: Lists all available serial ports on the system, providing details such as hardware ID, description, and vendor. This is useful for identifying the correct port for your device.<br><br><B>monitor</B>: Opens a serial monitor connection to a specified device, displaying data received over the serial port. This is the most frequently used subcommand for debugging embedded applications by viewing their runtime output.


title: HISTORY
content:
PlatformIO (PIO) was founded by Ivan Kravets and released its first public version around 2014. The <B>pio device</B> subcommand has been an integral part of the PIO Core CLI since its early stages, providing essential functionalities for interacting with hardware targets. Its development has mirrored the growth of embedded systems and IoT, continuously adapting to new hardware and communication protocols to support a wide range of development boards and frameworks.


title: PARAMETERS
content:
<b><i>--port &lt;port&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the TCP/IP port for the web server (default is 8008).<br><br><b><i>--host &lt;host&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the TCP/IP host address for the web server (default is 127.0.0.1 or localhost).<br><br><b><i>--no-open</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents PlatformIO Home from automatically opening in the web browser.<br><br><b><i>--shutdown-timeout &lt;seconds&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the timeout for the server shutdown process (default is 5 seconds).<br><br><b><i>--no-startup-check</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skips the check for a running PlatformIO Home instance at startup.<br><br><b><i>--force-feature-display</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the display of all PlatformIO Home features, even if they are not enabled by default.<br><br><b><i>--help</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the help message and exits.<br><br>


title: DESCRIPTION
content:
<i>pio home</i> is a sub-command of the <i>pio</i> (PlatformIO Core) command-line interface. It launches <b>PlatformIO Home</b>, which is a powerful web-based user interface (UI) designed to streamline embedded systems development.<br><br>PlatformIO Home provides a centralized dashboard for managing projects, boards, libraries, and development environments. Users can access features like project creation and management, browsing available boards and frameworks, installing and updating development platforms, exploring and managing libraries, and utilizing a built-in serial port monitor.<br><br>It runs a local web server (usually on <i>localhost:8008</i> by default) and automatically opens the UI in the default web browser. This graphical interface simplifies many tasks that could otherwise be complex or require multiple command-line operations, making embedded development more accessible and efficient for both beginners and experienced developers. It integrates seamlessly with the PlatformIO Core CLI, allowing users to switch between GUI and CLI workflows as needed.


title: CAVEATS
content:
Requires an active internet connection for initial setup, library/platform installations, and updates.<br>Runs a local web server, which consumes system resources.<br>Default port 8008 might conflict with other applications; can be changed with <i>--port</i>.<br>While web-based, it still requires PlatformIO Core to be installed locally to function.


title: <B>WEB-BASED INTERFACE</B>
content:
PlatformIO Home operates as a local web server, accessible via a browser, providing a rich graphical interface for managing projects, libraries, and development environments. This approach makes it cross-platform and easily accessible.


title: <B>INTEGRATION WITH VS CODE</B>
content:
While <i>pio home</i> can be run standalone, it's often launched automatically when using the <b>PlatformIO IDE extension for Visual Studio Code</b>, seamlessly integrating the UI into the development environment.


title: HISTORY
content:
<b>PlatformIO Home</b> was introduced as a major feature to complement the command-line interface, aiming to provide a more user-friendly graphical experience for embedded development. Its development is ongoing as part of the broader PlatformIO ecosystem, with regular updates introducing new features and improvements. It evolved from a pure CLI tool into a hybrid system offering both powerful command-line control and an intuitive web UI.


title: PARAMETERS
content:
<b>-b, --board <I>ID</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the target board ID (e.g., `esp32dev`, `uno`).<br><br><b>-f, --framework <I>ID</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the development framework (e.g., `arduino`, `espidf`).<br><br><b>-p, --project-dir <I>PATH</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Define the project's root directory. Defaults to the current directory.<br><br><b>--ide <I>ID</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate configuration files for a specific IDE (e.g., `vscode`, `clion`).<br><br><b>-e, --env <I>ID</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Initialize project with a specific environment ID defined in `platformio.ini`.<br><br><b>--ecc</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exclude generation of `.vscode/c_cpp_properties.json` for VSCode.<br><br><b>--skip-versioning-generation</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevent generation of version control files like `.gitignore`.<br><br><b>--rebuild-project-ide</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force regeneration of IDE project files, useful for updates.<br><br>


title: DESCRIPTION
content:
The `pio init` command is a core component of the PlatformIO ecosystem, used to initialize a new embedded development project. It establishes the foundational project structure in a specified or current directory, making it ready for coding, building, and uploading. The command creates essential folders like `src` for source code, `lib` for private libraries, and `test` for unit tests. Crucially, it generates the `platformio.ini` configuration file, which defines the project's board, framework, dependencies, and build settings. This allows developers to quickly set up a consistent and organized environment for various microcontrollers and development boards, streamlining the embedded software development workflow from inception.


title: CAVEATS
content:
The `pio init` command is part of the PlatformIO Core CLI and requires PlatformIO to be installed on your system; it is not a standalone Linux utility. Running it in a non-empty directory will initialize the project within that directory, potentially overwriting an existing `platformio.ini` file if parameters conflict or if rebuilding is forced.


title: PROJECT STRUCTURE
content:
Upon successful execution, `pio init` establishes a standard directory layout for your project:<br> &nbsp;&nbsp;`platformio.ini` - Main project configuration file.<br> &nbsp;&nbsp;`src/` - Directory for your primary source code files.<br> &nbsp;&nbsp;`lib/` - Location for project-specific or private libraries.<br> &nbsp;&nbsp;`test/` - Folder designated for unit testing code.<br> &nbsp;&nbsp;`.vscode/` (if `--ide vscode` used) - VS Code specific configuration.<br> &nbsp;&nbsp;`.gitignore` (unless `--skip-versioning-generation` used) - Git ignore rules.


title: CONFIGURATION FILE (`PLATFORMIO.INI`)
content:
The `platformio.ini` file is the central configuration hub for any PlatformIO project. It defines critical settings such as target boards, development frameworks, build flags, upload protocols, and library dependencies. `pio init` automatically generates a basic `platformio.ini` file, pre-configured based on the board and framework options provided during initialization, providing a solid starting point for further project customization.


title: HISTORY
content:
PlatformIO emerged in 2014-2015 as an open-source solution to standardize embedded development across diverse hardware. The `pio init` command has been a foundational element since its inception, providing the essential capability to rapidly set up new projects with a consistent structure. Its design principles reflect modern software development practices, bringing structured project management and dependency handling to the embedded world, continually evolving to support new boards, frameworks, and IDE integrations.


title: PARAMETERS
content:
<b><b>install</b> <i>[library_id|name|path|url]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Installs a specified library or all project dependencies. Can take a library ID, name, path to a local library, or a remote URL (e.g., Git repository).<br><br><b><b>update</b> <i>[library_id|name]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Updates installed libraries. If no argument is provided, all installed libraries (global or project) are checked for updates.<br><br><b><b>search</b> <i>[query]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Searches the PlatformIO Library Registry for libraries matching the provided query.<br><br><b><b>list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists currently installed libraries, either globally or within the current project.<br><br><b><b>show</b> <i>[library_id|name]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays detailed information about a specific library from the PlatformIO Library Registry or an installed version.<br><br><b><b>builtin</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manages framework built-in libraries, typically used for listing or updating them.<br><br><b><b>register</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Registers a new library in the PlatformIO Library Registry, making it discoverable and installable by others.<br><br><b><b>unpublish</b> <i>[library_id|name]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Unpublishes a library from the PlatformIO Library Registry (requires ownership).<br><br><b><b>contribute</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides guidance and best practices for contributing libraries to the PlatformIO ecosystem.<br><br><b><b>-g</b>, <b>--global</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Operate on global libraries instead of project-specific ones. Applicable to various subcommands like <i>install</i>, <i>update</i>, and <i>list</i>.<br><br><b><b>--project-dir</b> <i><path></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the path to the PlatformIO project directory (default is current working directory).<br><br><b><b>--json-output</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output results in JSON format, useful for scripting and integration with other tools.<br><br>


title: DESCRIPTION
content:
<i>pio lib</i> is a fundamental command-line interface tool within the PlatformIO ecosystem, designed for comprehensive management of external libraries in embedded development projects.<br><br>It provides a robust solution for discovering, installing, updating, and removing libraries, streamlining the often complex process of dependency management. Developers can leverage <i>pio lib</i> to search the official PlatformIO Library Registry, install libraries by ID, name, or directly from local paths and remote repositories (like Git URLs).<br><br>The command supports both global installations (making libraries available across all projects) and project-specific dependencies, which are typically defined in the <b>platformio.ini</b> configuration file. By automating library dependency resolution, <i>pio lib</i> significantly enhances project reproducibility, maintainability, and collaboration by ensuring that all necessary components are correctly linked during the build process.


title: CAVEATS
content:
The <i>pio lib</i> command requires the PlatformIO Core CLI to be installed, which in turn depends on Python. Network connectivity is generally necessary for searching, installing, and updating libraries from the PlatformIO Registry or remote sources. Project-specific library dependencies are primarily managed through the <b>platformio.ini</b> configuration file within a PlatformIO project.


title: LIBRARY DEPENDENCY FINDER (LDF)
content:
<i>pio lib</i> works in conjunction with PlatformIO's intelligent Library Dependency Finder (LDF). The LDF automatically resolves and links library dependencies defined in <b>platformio.ini</b> or detected within source code, ensuring that all required libraries are correctly included during the build process, even when dealing with nested dependencies.


title: PLATFORMIO LIBRARY REGISTRY
content:
A core feature of <i>pio lib</i> is its seamless integration with the PlatformIO Library Registry. This centralized online repository hosts thousands of community-contributed and official libraries, making it easy for developers to discover, share, and install libraries for their embedded projects with simple command-line calls.


title: HISTORY
content:
PlatformIO, conceived by Ivan Kravets, began as an open-source project to simplify embedded development across various platforms and frameworks. From its early stages, efficient library management was identified as a critical need, addressing the fragmented and often manual processes prevalent in embedded ecosystems (e.g., Arduino IDE's manual library folder placement). The <i>pio lib</i> command evolved to provide a robust, automated solution for dependency resolution, integrating with the PlatformIO Library Registry and supporting diverse sources like local paths and Git repositories. This significantly enhanced the reusability, maintainability, and version control capabilities for embedded software projects, becoming a cornerstone of the PlatformIO CLI.


title: SYNOPSIS
content:
As <i><b>pio-org</b></i> is not a standardized command, its synopsis depends entirely on the specific custom script or utility being used. An illustrative, generic syntax might be:<br><b>pio-org</b> [<i>command</i>] [<i>options</i>] [<i>arguments</i>]


title: PARAMETERS
content:
<b>No standard parameters.</b><br>&nbsp;&nbsp;&nbsp;&nbsp;As a non-official script, specific parameters for <i><b>pio-org</b></i> depend entirely on the custom implementation. Common functionalities one might expect such a script to provide include options for:<br><b>Project path specification</b> (e.g., <i>-p &lt;path&gt;</i>, <i>--project=&lt;path&gt;</i>)<br><b>Action specification</b> (e.g., <i>build</i>, <i>upload</i>, <i>monitor</i>, <i>clean</i>, <i>export-org</i>)<br><b>Configuration overrides</b> (e.g., <i>--env=&lt;env_name&gt;</i>)<br><b>Verbose output</b> (e.g., <i>-v</i>, <i>--verbose</i>)<br><br>However, these are conceptual examples, and actual parameters will be defined by the script's author.<br><br>


title: DESCRIPTION
content:
<i><b>pio-org</b></i> is not an official command in the PlatformIO CLI. Instead, it typically refers to a custom script or community-contributed utility designed to facilitate the integration and management of PlatformIO projects within Emacs' Org-mode environment.<br><br>Users create or adapt <i>pio-org</i> scripts to leverage Org-mode's powerful plain-text outlining, task management, and literate programming capabilities for embedded development. This could involve generating PlatformIO build commands from Org-mode source blocks, parsing <i>platformio.ini</i> files, or displaying project status within Org documents. The exact functionality varies widely depending on the script's implementation, as it is not standardized. Its primary goal is to streamline workflows for developers who prefer to manage their development tasks and project documentation using Org-mode.


title: CAVEATS
content:
<i><b>pio-org</b></i> is <b>not an official</b> PlatformIO CLI command nor an official Emacs package.<br>Its existence, behavior, and syntax are entirely dependent on individual custom scripts or community-contributed utilities.<br>There is no centralized documentation or support for <i><b>pio-org</b></i> beyond what individual script authors provide.<br>Users interested in this functionality typically need to write or adapt a script themselves, or find and use a community-maintained version.<br>Compatibility and features may vary significantly across different implementations.


title: USAGE CONTEXT
content:
Users often embed <i><b>pio-org</b></i> functionalities within Emacs Lisp functions or Org-mode source blocks (e.g., <i>#+BEGIN_SRC sh :dir /path/to/project</i>). This allows for dynamic execution of PlatformIO commands, compilation of projects, or retrieval of project information directly from their Org-mode documents, blurring the lines between documentation, task management, and code execution. This approach facilitates a highly integrated development and documentation workflow.


title: HISTORY
content:
Not having an official history, <i><b>pio-org</b></i> refers to a concept of integrating PlatformIO with Org-mode. It emerged from the developer community seeking to leverage Org-mode's literate programming and project management features for embedded systems development with PlatformIO. Various users and developers have independently created their own scripts and configurations to achieve this synergy, leading to diverse implementations rather than a singular, standardized tool.


title: SYNOPSIS
content:
<b>pio package</b> <I>command</I> [OPTIONS]<br><b>pio package install</b> <I>&lt;pkg_name_or_id&gt;</I> [OPTIONS]<br><b>pio package update</b> [OPTIONS]<br><b>pio package uninstall</b> <I>&lt;pkg_name_or_id&gt;</I> [OPTIONS]<br><b>pio package list</b> [OPTIONS]<br><b>pio package search</b> <I>&lt;query&gt;</I> [OPTIONS]


title: PARAMETERS
content:
<b><b>--global</b>, <b>-g</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manages packages in the global PlatformIO storage, making them available across all projects without being tied to a specific project's <i>platformio.ini</i>.<br><br><b><b>--platform</b> <I>&lt;platform_id&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the development platform (e.g., <i>espressif32</i>, <i>atmelsam</i>) for the package operation. Useful when managing platform-specific tools or frameworks.<br><br><b><b>--framework</b> <I>&lt;framework_id&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the framework (e.g., <i>arduino</i>, <i>esp-idf</i>) for the package operation. Typically used in conjunction with <b>install</b> or <b>update</b>.<br><br><b><b>--tool</b> <I>&lt;tool_id&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the tool package for the operation (e.g., a specific compiler or debugger). Applies to various subcommands.<br><br><b><b>--json</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the results in JSON format. Primarily used with the <b>list</b> and <b>search</b> subcommands for machine-readable output.<br><br><b><b>--skip-dependencies</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Applicable to <b>install</b>) Installs the specified package without automatically installing its listed dependencies.<br><br><b><b>--spec</b> <I>&lt;version_spec&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Applicable to <b>install</b>) Specifies a particular version or version range for the package to be installed (e.g., <i>^1.2.3</i>, <i>>1.0.0,<2.0.0</i>).<br><br>


title: DESCRIPTION
content:
The <b>pio-package</b> command, a core component of the PlatformIO ecosystem, is designed for efficient management of development platforms, frameworks, and tools. These essential components are crucial for building embedded software projects. PlatformIO abstracts the complexity of setting up diverse development environments by allowing users to easily install, update, uninstall, and list these packages. <br><br>It supports a wide range of microcontrollers and development boards by providing curated toolchains, SDKs, and frameworks. This command is particularly useful for ensuring project reproducibility across different development machines and for maintaining consistent versions of dependencies. It can operate on packages globally or within the scope of a specific PlatformIO project, depending on the options used.


title: CAVEATS
content:
The <b>pio-package</b> command requires PlatformIO Core to be installed and properly configured in your system's PATH.<br><br>It exclusively manages packages within the PlatformIO ecosystem (development platforms, frameworks, tools) and should not be confused with general Linux package managers (like <i>apt</i> or <i>yum</i>) or Python package managers (like <i>pip</i>).<br><br>While manual management is possible, PlatformIO projects often handle platform and framework dependencies automatically via their <i>platformio.ini</i> configuration when commands like <b>pio run</b> or <b>pio build</b> are executed.


title: USAGE CONTEXT: GLOBAL VS. PROJECT-SPECIFIC PACKAGES
content:
By default, when you use <b>pio package install</b> within a PlatformIO project directory, the package is added as a dependency to your project's <i>platformio.ini</i> file and installed for that specific project. This ensures project portability and reproducibility. <br><br>However, using the <b>--global</b> (or <b>-g</b>) flag with commands like <b>install</b>, <b>update</b>, or <b>uninstall</b> directs the operation to PlatformIO's global package storage. Global packages are available to any PlatformIO project on your system without explicit declaration in <i>platformio.ini</i>. This is beneficial for common tools, frameworks, or platforms that you use across multiple projects, reducing redundant installations and storage.


title: HISTORY
content:
PlatformIO was launched in 2014 with the aim of simplifying embedded software development. The `pio-package` functionality, or its conceptual equivalent, was integral to PlatformIO Core from its early stages, providing a unified mechanism for managing the disparate toolchains and SDKs inherent in embedded systems. Its continuous evolution has mirrored the rapid growth of the embedded ecosystem, adapting to new architectures, boards, and development methodologies, consistently aiming to abstract away the environmental complexities for developers.


title: SYNOPSIS
content:
<b>pio pkg</b> <i><command></i> [<i>options</i>]<br><b>pio pkg install</b> [<i>options</i>] [<i><package></i>]<br><b>pio pkg update</b> [<i>options</i>] [<i><package></i>]<br><b>pio pkg uninstall</b> [<i>options</i>] [<i><package></i>]<br><b>pio pkg list</b> [<i>options</i>]<br><b>pio pkg search</b> [<i>options</i>] <i><query></i><br><b>pio pkg pack</b> [<i>options</i>]<br><b>pio pkg publish</b> [<i>options</i>]


title: PARAMETERS
content:
<b><b>install</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Installs specified packages (libraries, platforms, toolchains, frameworks). Can be used without arguments within a project to install all dependencies from <i>platformio.ini</i>.<br><br><b><b>update</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Updates installed packages to their latest compatible versions. If no package is specified, all project or global packages are updated.<br><br><b><b>uninstall</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes specified packages from the system or project environment.<br><br><b><b>list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all currently installed packages, categorized by type (libraries, platforms, etc.).<br><br><b><b>search</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Searches the PlatformIO Registry for packages matching a given query.<br><br><b><b>pack</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Packs a local library into a distributable archive (<i>.tar.gz</i>) for publishing or local installation.<br><br><b><b>publish</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Publishes a packed library to the PlatformIO Registry, making it available for other developers.<br><br><b><b>-g</b>, <b>--global</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies the command to global packages rather than project-specific ones. Applicable to <i>install</i>, <i>update</i>, <i>uninstall</i>.<br><br><b><b>--library</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies that the operation applies to a library package type.<br><br><b><b>--platform</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies that the operation applies to a development platform package type.<br><br><b><b>--framework</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies that the operation applies to a framework package type.<br><br><b><b>--toolchain</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies that the operation applies to a toolchain package type.<br><br><b><b>--storage-dir</b> <i><path></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a custom directory for package storage instead of the default location.<br><br><b><b>--save</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When installing a library, adds it to the <i>lib_deps</i> section of the project's <i>platformio.ini</i> file. Applicable to <i>install</i>.<br><br><b><b>--skip-dependencies</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skips the installation of package dependencies. Applicable to <i>install</i>.<br><br><b><b>--json-output</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs command results in JSON format, useful for scripting and programmatic access.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, displaying more detailed information during command execution.<br><br>


title: DESCRIPTION
content:
The <i><b>pio-pkg</b></i> command is an essential component of the PlatformIO Core, serving as its powerful package manager. It provides a robust and streamlined way to manage all dependencies required for embedded development projects, including <b>libraries</b>, <b>development platforms</b> (e.g., Espressif 32, STM32), <b>toolchains</b> (compilers, debuggers), and <b>frameworks</b> (e.g., Arduino, ESP-IDF).<br><br><i><b>pio-pkg</b></i> automates the process of finding, downloading, installing, updating, and uninstalling these crucial components, ensuring that your development environment is consistent and up-to-date. This eliminates the complexities of manual dependency management, allowing developers to focus on writing code for their embedded systems. It supports various package sources, including PlatformIO Registry, local paths, and VCS repositories, making it incredibly flexible for diverse project requirements. Its integration with the PlatformIO project structure and configuration files (like <i>platformio.ini</i>) ensures reproducible builds and simplifies collaboration among developers.


title: CAVEATS
content:
Requires <i><b>PlatformIO Core</b></i> to be installed on the system.<br>Many operations, especially <i><b>install</b></i> and <i><b>update</b></i>, require an active internet connection to download packages from the PlatformIO Registry or other remote sources.<br>Package versioning and compatibility can sometimes lead to conflicts, requiring manual resolution or specific version pinning in <i>platformio.ini</i>.


title: PACKAGE TYPES
content:
<i><b>pio-pkg</b></i> manages several distinct types of packages crucial for embedded development:<br><b>Libraries</b>: Reusable code components (e.g., sensor drivers, communication protocols).<br><b>Development Platforms</b>: Integrated environments for specific hardware architectures (e.g., Espressif 32, Atmel AVR), including SDKs, toolchains, and frameworks.<br><b>Toolchains</b>: Collections of programming tools, primarily compilers, assemblers, and linkers, specific to a target architecture.<br><b>Frameworks</b>: Software abstraction layers that simplify interaction with hardware, such as Arduino, ESP-IDF, Mbed OS.


title: PROJECT CONFIGURATION INTEGRATION
content:
Packages can be specified and managed within a PlatformIO project's <i><b>platformio.ini</b></i> configuration file. This allows for dependency declaration (e.g., <i>lib_deps</i>, <i>platform</i>, <i>board</i>) which <i><b>pio-pkg install</b></i> automatically resolves and installs when a project is initialized or built, ensuring reproducible builds across different development environments.


title: HISTORY
content:
PlatformIO, including its package management capabilities, was created by <i><b>Ivan Grytsenko</b></i> and first released around 2014. It emerged as a comprehensive, open-source ecosystem designed to simplify cross-platform embedded development, addressing the fragmentation and complexity often found in this domain. The <i><b>pio-pkg</b></i> command became a central piece of PlatformIO's architecture, enabling developers to easily manage the vast and growing collection of hardware-specific libraries, development platforms, toolchains, and frameworks. Its continuous development has kept pace with new microcontrollers and development boards, establishing PlatformIO as a popular choice for professional and hobbyist embedded engineers.


title: PARAMETERS
content:
<b>list / ls</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all installed development platforms.<br><br><b>search / s <query></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Searches for available development platforms in the PlatformIO Registry based on a provided query.<br><br><b>install / i <platform_name_or_url></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Installs a new development platform. Accepts a platform name from the registry, a Git repository URL, or a path to a local platform folder.<br><br><b>update / up [<platform_name>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Updates installed development platforms. If no <I>platform_name</I> is specified, all installed platforms are checked and updated to their latest versions.<br><br><b>uninstall / un <platform_name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uninstalls a previously installed development platform from your system.<br><br><b>show / sh <platform_name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays detailed information about a specific installed or available development platform, including its supported boards, packages, and frameworks.<br><br><b>outdate</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists installed development platforms that have updates available in the PlatformIO Registry.<br><br><b>--json-output</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Global option for some subcommands) Outputs command results in JSON format, ideal for scripting and programmatic parsing.<br><br><b>--installed</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(For <I>search</I> subcommand) Filters search results to display only platforms that are already installed on the system.<br><br><b>--skip-default-package</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(For <I>install</I> subcommand) Prevents the installation of default packages (toolchains, frameworks) associated with a platform during installation. Useful for custom configurations.<br><br><b>--with-package <package_name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(For <I>install</I> subcommand) Specifies an additional package to be installed along with the platform. Can be used multiple times.<br><br><b>--without-package <package_name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(For <I>install</I> subcommand) Excludes a specific package from being installed with the platform. Can be used multiple times.<br><br><b>--storage-dir <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(For <I>install</I> subcommand) Specifies a custom directory where the platform and its packages should be installed, overriding the default PlatformIO storage location.<br><br>


title: DESCRIPTION
content:
The <I>pio platform</I> command is a core component of the PlatformIO ecosystem, enabling seamless management of diverse hardware development platforms. These platforms encapsulate specific microcontrollers, their associated toolchains, SDKs, and development frameworks (like Arduino, ESP-IDF, Mbed, etc.). <br><br>This command allows developers to <I>list</I> all installed platforms, <I>search</I> for new ones in the PlatformIO Registry, <I>install</I> them from various sources (registry, Git repositories, local paths), <I>update</I> existing installations, <I>uninstall</I> platforms no longer needed, and <I>show</I> detailed information about any specific platform. It significantly simplifies the setup and maintenance of multi-architecture embedded projects, abstracting away the complexities of managing toolchain versions and framework dependencies.


title: CAVEATS
content:
An active internet connection is typically required for searching, installing, and updating platforms, as they download necessary toolchains and frameworks from remote repositories. <br><br>PlatformIO platforms, toolchains, and frameworks can consume significant disk space, especially if many different platforms are installed. Regular cleanup of unused platforms via <I>uninstall</I> is recommended.


title: PLATFORM MANIFESTS
content:
Each PlatformIO development platform is defined by a manifest file (e.g., <I>platform.json</I>) which specifies its packages, toolchains, frameworks, and supported boards. These manifests are crucial for the <I>pio platform</I> command to correctly resolve dependencies and configure development environments.


title: OFFLINE CAPABILITIES
content:
Once a platform and its associated packages are installed, many <I>pio platform</I> operations (like <I>show</I>) and subsequent project builds can often proceed offline, as long as all necessary components are locally cached. New installations or updates, however, will always require network access to fetch remote resources.


title: HISTORY
content:
The <I>pio platform</I> command is a foundational element of PlatformIO Core, which emerged around 2014-2015 as a cross-platform, professional-grade development ecosystem for embedded systems. Its design evolved to address the fragmentation in embedded development, where managing different vendor-specific IDEs, toolchains, and SDKs was a significant challenge. The command provides a unified, command-line interface for handling these complexities, making PlatformIO a popular choice for developers working with a variety of microcontrollers and boards, emphasizing automation and consistency across projects.


title: PARAMETERS
content:
<b><b><I>init</I></b> [options]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Initializes a new PlatformIO project in the current or specified directory. Allows selection of board, framework, and IDE for the project setup.<br><br><b><b><I>build</I></b> [options]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Compiles the project source code for the specified environment(s) and target(s). This command generates firmware binaries and other build artifacts.<br><br><b><b><I>upload</I></b> [options]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uploads the compiled firmware binary to the target development board connected to the system. This often uses parameters to specify port or protocol.<br><br><b><b><I>clean</I></b> [options]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes compiled object files, firmware binaries, and other temporary build artifacts from the project, ensuring a fresh build on subsequent compilations.<br><br><b><b><I>run</I></b> [options]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;A versatile command that can perform various actions on the project, such as building, uploading, monitoring serial output, or debugging. It serves as a unified entry point for project workflow.<br><br><b><b><I>config</I></b> [options]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manages project configuration, allowing users to inspect or modify settings defined within the <i><I>platformio.ini</I></i> file programmatically.<br><br><b><b><I>data</I></b> [options]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manages the project's data folder, typically used for storing assets like SPIFFS images or web interfaces for embedded devices.<br><br><b><b><I>deps</I></b> [options]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manages project dependencies (libraries). This command can install, update, or uninstall libraries specified in the <i><I>platformio.ini</I></i> file.<br><br>


title: DESCRIPTION
content:
The <b><I>pio project</I></b> command group is a fundamental component of the PlatformIO Core Command Line Interface (CLI). It provides comprehensive tools for managing the entire lifecycle of Internet of Things (IoT) and embedded development projects.<br><br>This command abstracts away the complexities of cross-platform development, allowing users to initialize new projects, configure build environments, manage dependencies (libraries), compile source code, upload firmware to target boards, and clean project artifacts. It supports a vast ecosystem of development boards, frameworks (like Arduino, ESP-IDF, Mbed), and debugging tools, making it an indispensable utility for developers working with embedded systems.<br><br>The commands within <b><I>pio project</I></b> interact heavily with the <i><I>platformio.ini</I></i> configuration file, which defines project-specific settings, environments, and build instructions. While primarily a CLI tool, its functionality is deeply integrated into popular IDEs, most notably the PlatformIO IDE extension for VSCode, providing a seamless graphical interface for these powerful project management capabilities.


title: CAVEATS
content:
The <b><I>pio project</I></b> commands require PlatformIO Core to be properly installed and configured on the system. Initial project setup and dependency resolution can involve significant downloads of toolchains, platforms, and libraries, which require an active internet connection. Project configuration heavily relies on the <i><I>platformio.ini</I></i> file, which must be correctly structured for the commands to function as expected and to define the project's specific requirements.


title: PROJECT CONFIGURATION FILE
content:
PlatformIO projects are primarily configured using the <i><I>platformio.ini</I></i> file, located in the project's root directory. This INI-style file defines build environments, target boards, frameworks, library dependencies, custom build flags, and upload/monitor settings. It is the central hub for customizing a project's behavior for different environments and hardware, offering granular control over the build process.


title: IDE INTEGRATION
content:
While <b><I>pio project</I></b> commands are executed from the command line, PlatformIO offers deep integration with various Integrated Development Environments (IDEs). The most popular integration is the PlatformIO IDE extension for Visual Studio Code, which provides a rich graphical interface for initializing, building, uploading, and debugging projects, all powered by the underlying <b><I>pio project</I></b> CLI commands. This integration streamlines the development process for users preferring a visual workflow.


title: HISTORY
content:
PlatformIO was founded by Ivan Kravets with the vision of simplifying cross-platform embedded development. The <b><I>pio project</I></b> command group has been central to PlatformIO Core since its inception, evolving significantly to support a rapidly expanding ecosystem of microcontrollers, development boards, and frameworks. Its design emphasizes ease of use, automation, and cross-platform compatibility, making it a popular choice for both hobbyists and professional IoT developers. The continuous development focuses on integrating new hardware and software standards, further streamlining the embedded development workflow and enhancing developer productivity.


title: PARAMETERS
content:
<b>agent</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts the PlatformIO Remote Agent on the host machine. This agent listens for commands from a local PlatformIO CLI, allowing remote compilation, uploading, and debugging tasks to be performed. It typically runs in the background and provides necessary drivers for connected devices.<br><br><b>run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes a remote PlatformIO project build, upload, or both. This command functions similarly to <i>pio run</i> but targets a remote environment managed by an active agent. It supports all standard PlatformIO build environments and targets.<br><br><b>test</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs unit tests remotely on a connected device or host. This is useful for automated testing of embedded code in its intended environment without direct physical intervention.<br><br><b>monitor</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Establishes a remote serial port monitor session. It allows developers to view serial output from a remotely connected device, crucial for debugging and observing device behavior, akin to <i>pio device monitor</i> locally.<br><br><b>debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Initiates a remote debugging session. This command enables stepping through code, inspecting variables, and setting breakpoints on an embedded target connected to the remote agent, significantly aiding in complex problem diagnosis.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the PlatformIO Core version.<br><br><b>--help, -h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows a help message for the <i>pio remote</i> command or its subcommands.<br><br>


title: DESCRIPTION
content:
<code>pio-remote</code> is a powerful extension of the PlatformIO ecosystem, enabling seamless remote development for embedded systems. It allows developers to compile, upload, monitor, and debug their PlatformIO projects on a remote machine or target device, often connected via a network. This is particularly useful for scenarios where the development environment cannot be directly on the target device (e.g., resource-constrained devices, or when the device is in a hard-to-reach location). The command operates by leveraging a <i>pio remote agent</i> running on the remote machine, which acts as an intermediary, executing commands received from the local PlatformIO CLI. This facilitates continuous integration, remote debugging, and collaborative development for IoT and embedded projects without needing direct physical access to the hardware for every operation. It significantly streamlines the workflow for distributed teams and complex deployment scenarios.


title: CAVEATS
content:
<code>pio-remote</code> requires an active <code>pio remote agent</code> running on the remote machine. Network connectivity between the local machine and the remote agent is essential. Security considerations are paramount, as the agent can execute commands on the remote system; ensure secure network configurations (e.g., SSH tunnels, firewalls). The performance of remote operations can be affected by network latency and bandwidth.


title: TYPICAL WORKFLOW
content:
The typical workflow involves first starting the remote agent on the target machine using <b>pio remote agent start</b>. Once the agent is running and accessible from your local network, you can then use <b>pio remote run</b>, <b>pio remote test</b>, <b>pio remote monitor</b>, or <b>pio remote debug</b> from your local machine, passing in the relevant project configuration and options. The agent acts as a proxy, executing these commands on the remote machine where the target hardware is connected.


title: AGENT MANAGEMENT
content:
The <b>pio remote agent</b> subcommand also provides actions like <b>stop</b> to terminate the agent, <b>restart</b> to restart it, and <b>status</b> to check its current state. These are crucial for managing the remote environment.


title: HISTORY
content:
<code>pio-remote</code> was developed as a key feature within the PlatformIO ecosystem to address the growing need for efficient remote development in IoT and embedded systems. As projects became more complex and distributed, managing hardware that wasn't physically co-located with the developer became a bottleneck. Introduced to streamline workflows for CI/CD, remote debugging, and collaborative development, it quickly became an integral part of PlatformIO for professional and hobbyist developers alike, evolving with the PlatformIO Core.


title: SYNOPSIS
content:
<i><I>pio settings <b>[COMMAND]</b> <b>[OPTIONS]</b></I></i><br><i><I>pio settings list <b>[OPTIONS]</b></I></i><br><i><I>pio settings get <b><KEY></b> <b>[OPTIONS]</b></I></i><br><i><I>pio settings set <b><KEY></b> <b><VALUE></b> <b>[OPTIONS]</b></I></i><br><i><I>pio settings unset <b><KEY></b> <b>[OPTIONS]</b></I></i>


title: PARAMETERS
content:
<b><i><I>list</I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays all current global PlatformIO settings and their values.<br><br><b><i><I>get <KEY></I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Retrieves the value of a specific setting identified by <i><I><KEY></I></i>.<br><br><b><i><I>set <KEY> <VALUE></I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the value of a specific setting <i><I><KEY></I></i> to <i><I><VALUE></I></i>. If the key does not exist, it will be created.<br><br><b><i><I>unset <KEY></I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes a specific setting identified by <i><I><KEY></I></i> from the global configuration.<br><br><b><i><I>--json-output</I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An optional global flag that outputs the command's result in JSON format, useful for scripting.<br><br><b><i><I>--caller</I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An internal flag used by PlatformIO to identify the caller process, typically not used by end-users.<br><br>


title: DESCRIPTION
content:
The <i><I>pio-settings</I></i> command is a command-line utility part of the PlatformIO Core ecosystem, designed for managing global configuration settings. PlatformIO is an open-source ecosystem for IoT development, providing a cross-platform build system, library manager, and integrated debugging. The <i><I>pio-settings</I></i> command allows users to view, retrieve, modify, and remove global configuration options that dictate PlatformIO's behavior across all projects.<br><br>These settings are typically stored in a global configuration file, often located at <i><I>~/.platformio/config.ini</I></i>. Common uses include configuring proxy settings, custom package installation directories, development server options, or other system-wide preferences. By providing a programmatic interface to manage these settings, <i><I>pio-settings</I></i> facilitates automation and scripting of PlatformIO environment setups, ensuring consistent behavior across different development machines or CI/CD pipelines. It's a fundamental tool for customizing the PlatformIO experience beyond project-specific configurations.


title: CAVEATS
content:
Using <i><I>pio-settings</I></i> requires a working installation of PlatformIO Core. Modifications made with this command are global to your PlatformIO environment and can significantly alter its behavior, potentially affecting all your PlatformIO projects. Incorrectly set values might lead to unexpected errors or functionality issues. Some changes may require restarting any active PlatformIO IDE instances or the shell to take full effect.


title: CONFIGURATION FILE LOCATION
content:
Global PlatformIO settings managed by <i><I>pio-settings</I></i> are persistently stored in the <i><I>config.ini</I></i> file, typically located within the PlatformIO home directory, such as <i><I>~/.platformio/config.ini</I></i> on Linux/macOS or <i><I>%USERPROFILE%\.platformio\config.ini</I></i> on Windows. Understanding this location can be useful for manual inspection or backup.


title: SCOPE OF SETTINGS
content:
It's crucial to differentiate between global settings handled by <i><I>pio-settings</I></i> and project-specific settings. Project-specific configurations, such as build flags, environment variables, or library dependencies for an individual project, are defined in the <i><I>platformio.ini</I></i> file located in the root of each PlatformIO project.


title: HISTORY
content:
The <i><I>pio-settings</I></i> command has been an integral part of PlatformIO Core since its early development. PlatformIO was launched in 2014, and as a comprehensive IoT development environment, it quickly required robust configuration management. The command evolved with PlatformIO's feature set, adapting to new configuration needs and providing a consistent CLI interface for managing the global <i><I>config.ini</I></i> file. Its consistent presence underlines the importance of programmatic configuration for automation and flexible development workflows within the PlatformIO ecosystem.


title: PARAMETERS
content:
<b>info</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays detailed system-wide information about PlatformIO Core, Python environment, OS, and installed packages.<br><br><b>completion</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manages shell tab-completion for the PlatformIO CLI. Can install or uninstall completion scripts.<br><br><b>prune</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes unused or orphaned PlatformIO packages, tools, and frameworks from the global storage, optimizing disk space.<br><br><b>install</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ensures that all required system components for PlatformIO are installed and configured correctly.<br><br><b>update</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Updates PlatformIO Core, installed development platforms, and tools to their latest versions.<br><br><b>uninstall</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uninstalls PlatformIO Core from the system. Use with caution as this permanently removes PIO Core.<br><br><b>repair</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempts to repair common issues with the PlatformIO Core installation or its components.<br><br>


title: DESCRIPTION
content:
<i>pio system</i> is a vital subcommand within the <b>PlatformIO (PIO) command-line interface</b>, designed for comprehensive management of the PlatformIO ecosystem across your system. It serves as a central hub for maintaining the health, efficiency, and integrity of your PIO development environment. Through various sub-commands, <i>pio system</i> enables users to perform essential tasks such as inspecting detailed system information, installing or updating crucial dependencies, pruning unused development tools and packages to free up disk space, and configuring shell tab-completion for an improved user experience. It plays a critical role in diagnosing and resolving common PlatformIO-related issues, ensuring that all necessary components are correctly installed and up-to-date. This command empowers developers to efficiently manage their IoT development toolchain, from initial setup to ongoing maintenance, by providing centralized control over PlatformIO's foundational elements.


title: CAVEATS
content:
The <i>pio system</i> command requires the PlatformIO CLI to be installed on your system.<br>Many of its subcommands necessitate active internet connectivity for downloading updates or installing new components.<br>Be extremely cautious when using the <b>uninstall</b> subcommand, as it permanently removes PlatformIO Core from your system.<br>Depending on your system's configuration and how PlatformIO was installed, some commands might require administrator or root privileges.<br>The exact set of available subcommands and their specific options may vary slightly with different versions of PlatformIO Core.


title: SUBCOMMAND SPECIFIC OPTIONS
content:
Each subcommand within <i>pio system</i> offers its own specific options and arguments to fine-tune its behavior. To view these, you can append <i>--help</i> after the subcommand. For example, to see options for configuring shell completion, run <b>pio system completion --help</b>.


title: PLATFORMIO ECOSYSTEM MANAGEMENT
content:
<i>pio system</i> is indispensable for managing the intricate web of dependencies, including compilers, upload tools, debuggers, and development frameworks, that PlatformIO seamlessly abstracts for a vast array of microcontrollers and development boards. It ensures a consistent and functional development environment across different projects.


title: HISTORY
content:
PlatformIO began as an open-source project aimed at simplifying cross-platform embedded development. The <i>pio system</i> subcommand was introduced as part of the evolving PlatformIO CLI to provide users with direct control over the underlying components and infrastructure that PlatformIO relies upon. Its development paralleled the growth of the PlatformIO ecosystem, as the need for robust system management tools became apparent to handle diverse development platforms, frameworks, and toolchains. This command set helps maintain the portability and stability of PlatformIO across different operating systems, reflecting the project's commitment to a seamless developer experience for IoT and embedded systems.


title: PARAMETERS
content:
<b>-n, --name <team_name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the unique name of the target team for the operation.<br><br><b>-e, --email <user_email></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides the email address of the team member to invite, update, or remove.<br><br><b>-r, --role <role></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets or updates the role for a team member. Common roles include <br><i>member</i><br> and <br><i>admin</i><br> (administrator).<br><br><b>--json</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the command's result in JSON format, useful for programmatic consumption (primarily with <br><i>list</i><br> subcommand).<br><br>


title: DESCRIPTION
content:
The <br><i>pio team</i><br> command is a crucial subcommand within the PlatformIO Core Command Line Interface (CLI), designed for the comprehensive management of PlatformIO Cloud teams. It empowers users to create, list, and modify their organizational structures within the PlatformIO ecosystem, facilitating collaborative embedded development.<br><br>This command provides functionalities for administering team members, including sending invitations to new users, updating their roles (such as <br><i>administrator</i><br> or <br><i>member</i><br>), and removing them from a team. It is indispensable for organizations leveraging PlatformIO Cloud services to streamline workflows, securely share projects, and manage access permissions across development teams, ensuring efficient and collaborative work on embedded systems projects.


title: CAVEATS
content:
<b>Requirements:</b> An active PlatformIO Cloud subscription and a successful authentication via <br><i>pio account login</i><br>.<br><b>Connectivity:</b> Internet connectivity is mandatory for all operations as it interacts with PlatformIO Cloud services.<br><b>Permissions:</b> Users must possess the necessary team permissions (e.g., an <br><i>admin</i><br> role) to perform team and member management actions.


title: SUBCOMMANDS
content:
The <br><i>pio team</i><br> command acts as a parent, offering several specialized subcommands for specific actions:<br><b>list</b>: Displays a list of all teams the authenticated user is currently a part of.<br><b>invite</b>: Sends an invitation to a new user to join a specified team.<br><b>update</b>: Modifies the role of an existing member within a team.<br><b>remove</b>: Removes a specific member from a team.<br><b>init</b>: Initializes and creates a new PlatformIO Cloud team.


title: HISTORY
content:
PlatformIO, an open-source ecosystem for IoT development, was initially released in 2014. The <br><i>pio team</i><br> functionality emerged as an integral part of the PlatformIO Cloud services, which expanded the PlatformIO CLI's capabilities to encompass collaborative features. This development was a response to the growing demand for team-based embedded software development and project sharing, marking PlatformIO's evolution from a local development environment into a more integrated, cloud-enabled platform.


title: SYNOPSIS
content:
<b>pio-test</b> [<I>options</I>] [<I>file_or_directory</I>]<br><br><i>Typical usage with MPI:</i><br><b>mpirun -np 4 pio-test -s 10G -b 1M -t write -p seq /mnt/lustre/test_dir/testfile</b>


title: PARAMETERS
content:
<b>-s <I>SIZE</I>, --size=<I>SIZE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the total I/O size for the test (e.g., 10G, 512M). This is the aggregated size across all participating processes.<br><br><b>-b <I>SIZE</I>, --block-size=<I>SIZE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the size of each individual I/O operation (e.g., 4K, 1M). This sets the granularity of data transfer.<br><br><b>-t <I>TYPE</I>, --type=<I>TYPE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the type of I/O operation: <I>write</I> (create and write data), <I>read</I> (read existing data), or <I>rmw</I> (read-modify-write).<br><br><b>-p <I>PATTERN</I>, --pattern=<I>PATTERN</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Determines the access pattern for I/O operations: <I>seq</I> (sequential access) or <I>rand</I> (random access).<br><br><b>-D, --direct</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables direct I/O (O_DIRECT) to bypass the operating system's page cache, providing a more raw measurement of disk performance.<br><br><b>-l, --local</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs <i>pio-test</i> to perform tests on a local file system rather than assuming a parallel file system environment.<br><br><b>-i <I>ITERATIONS</I>, --iterations=<I>ITERATIONS</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the number of times to repeat the entire I/O test workload.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases the verbosity of the output, providing more detailed information about the test progress and results.<br><br><b>-c, --collect-stats</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables the collection of detailed statistics, often used in conjunction with the <i>piostats</i> daemon for comprehensive performance monitoring.<br><br><b>-d, --dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a dry run, parsing arguments and setting up the test without actually executing I/O operations.<br><br><b>-P <I>NUM</I>, --processes=<I>NUM</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;This flag is often informational or for non-MPI local tests; for parallel tests, the number of processes is typically controlled by the MPI runner (e.g., <b>mpirun -np</b>).<br><br>


title: DESCRIPTION
content:
The <i>pio-test</i> command is a utility designed for benchmarking and analyzing I/O performance, particularly on parallel file systems like Lustre, GPFS (now IBM Spectrum Scale), or BeeGFS, but it can also test local file systems. It allows users to simulate various I/O workloads by specifying parameters such as total I/O size, block size, I/O pattern (sequential or random), and the type of operation (read, write, read-modify-write).<br><br>The tool is invaluable in understanding the I/O characteristics and identifying bottlenecks of a storage system by performing synthetic read and write operations. It's commonly used by system administrators and performance engineers in HPC environments to optimize storage configurations, troubleshoot performance issues, and validate new hardware or file system deployments. The output typically includes aggregated throughput and sometimes latency metrics.


title: CAVEATS
content:
<i>pio-test</i> frequently relies on an MPI (Message Passing Interface) environment (e.g., OpenMPI, MPICH) for its parallel testing capabilities. Without MPI, it can only perform local, single-process I/O tests. The validity of benchmark results can be significantly affected by system-level caching; using the <I>--direct</I> flag can help mitigate this. As a synthetic benchmark, <i>pio-test</i> may not perfectly mimic the complex I/O patterns of real-world applications, so its results should be interpreted as an indicator of maximum potential throughput rather than actual application performance. Running large-scale tests can consume substantial disk space and I/O bandwidth, potentially impacting other users or applications on a shared system.


title: INTEGRATION WITH MPI
content:
For parallel I/O operations, <i>pio-test</i> is typically launched through an MPI job launcher like <b>mpirun</b> or <b>srun</b>. The number of parallel I/O streams or processes (MPI ranks) is determined by the <I>-np</I> argument passed to the MPI launcher, not usually directly by <i>pio-test</i> itself. Each MPI process contributes to the total I/O workload, allowing the tool to assess the aggregate performance of the parallel file system.


title: INTERPRETING OUTPUT
content:
The primary output of <i>pio-test</i> focuses on aggregated I/O bandwidth, typically reported in MB/s or GB/s. For write tests, this signifies the rate at which data is written to the file system, and for read tests, the rate at which data is retrieved. While <i>pio-test</i> primarily provides throughput metrics, more detailed statistical breakdowns, including minimum, maximum, and average performance, can be obtained when used in conjunction with the full <i>piostats</i> collection framework, offering deeper insights into performance variability.


title: HISTORY
content:
<i>pio-test</i> is a core component of the <i>piostats</i> suite, a collection of tools developed to address the specific challenges of monitoring and benchmarking parallel I/O in high-performance computing (HPC) environments. Its development is closely tied to the evolution and widespread adoption of parallel and distributed file systems such as Lustre, GPFS (now IBM Spectrum Scale), and others. The tool emerged from the critical need for system administrators, storage architects, and researchers to accurately measure, characterize, and optimize the throughput and latency of these complex, large-scale storage infrastructures to meet the demanding I/O requirements of scientific applications.


title: PARAMETERS
content:
<b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Display a help message for the command.</I><br><br><b>--json-output</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Output the results in JSON format, useful for scripting.</I><br><br><b>--dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Perform a simulated update, showing what would be updated without making actual changes.</I><br><br><b>--core-packages-update</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Update only the PlatformIO Core internal packages.</I><br><br><b>--platform-packages-update</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Update only the installed development platforms.</I><br><br><b>--framework-packages-update</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Update only the installed frameworks (e.g., Arduino, ESP-IDF).</I><br><br><b>--tool-packages-update</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Update only the installed development tools (e.g., compilers, uploaders).</I><br><br><b>--library-packages-update</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Update only the installed project libraries.</I><br><br>


title: DESCRIPTION
content:
<I>pio-update</I> is a crucial command within the <I>PlatformIO Core</I> ecosystem. It is used to keep your <I>PlatformIO</I> development environment up-to-date by downloading and installing the latest versions of core packages, development platforms, frameworks, tools, and libraries. Regular use of this command ensures you have access to the newest features, bug fixes, performance improvements, and security patches for your embedded and IoT development projects. It streamlines the process of maintaining a robust and current development setup, preventing compatibility issues and leveraging the most recent advancements in supported hardware and software.


title: CAVEATS
content:
<I>Requires an active internet connection to download updates.</I><br><I>Updates can be time-consuming, especially if many components need to be refreshed.</I><br><I>While generally stable, major version updates of components might occasionally introduce breaking changes for existing projects, though this is rare with PlatformIO's dependency management.</I>


title: DEFAULT BEHAVIOR
content:
<I>When executed without any options, <B>pio update</B> will attempt to update all installed PlatformIO Core packages, development platforms, frameworks, tools, and project libraries. This provides a comprehensive update for your entire PlatformIO ecosystem.</I>


title: REGULAR MAINTENANCE
content:
<I>It is highly recommended to run <B>pio update</B> regularly to ensure you are working with the latest stable versions of PlatformIO components, which can resolve potential bugs, improve performance, and provide access to new features and hardware support.</I>


title: HISTORY
content:
<I>PlatformIO Core, including the <B>pio update</B> command, was created by Ivan Kravets.</I><br><I>Since its inception, <B>pio update</B> has been a fundamental command, designed to simplify the complex task of managing toolchains, frameworks, and libraries for cross-platform embedded development.</I><br><I>It has evolved to support an ever-growing list of microcontrollers and development boards, continuously adapting to the needs of the IoT and embedded systems community by providing a unified and easy-to-maintain development environment.</I>


title: PARAMETERS
content:
<b><b>--dev</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Upgrades the <i>PlatformIO Core</i> to the latest development (bleeding-edge) version. This option provides access to new features and fixes before they are officially released, but it may also introduce unstable behavior or bugs. Not recommended for production environments.<br><br><b><b>--dry-run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a simulated upgrade process without actually installing or modifying any files. This is useful for previewing what changes would occur during an upgrade, allowing users to identify potential issues or dependencies before committing to the full installation.<br><br><b><b>--skip-python-check</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Bypasses the integrity check for the Python executable used by <i>PlatformIO</i>. This option can be useful in specific environments where the check might incorrectly flag issues, but it should be used with caution as it skips a fundamental verification step.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message for the <b>pio upgrade</b> command, listing available options and their brief descriptions, and then exits.<br><br>


title: DESCRIPTION
content:
The <b>pio upgrade</b> command is an essential utility within the <i>PlatformIO</i> ecosystem, designed to update the <i>PlatformIO Core</i> to its most recent stable release. The <i>Core</i> serves as the foundational command-line interface for <i>PlatformIO</i>, enabling interaction with development platforms, frameworks, libraries, and project management tasks.<br><br>Executing this command ensures that users benefit from the newest features, critical bug fixes, performance enhancements, and support for the latest hardware and software components in the embedded development landscape. It typically fetches packages from official <i>PlatformIO</i> repositories, providing a streamlined update process that maintains compatibility and system integrity. Unlike <b>pio update</b>, which updates project dependencies, <b>pio upgrade</b> specifically targets the underlying <i>PlatformIO</i> CLI tool itself.


title: CAVEATS
content:
<i><b>Important Considerations:</b></i><br>An active internet connection is required to download the necessary update packages.<br>Depending on your <i>PlatformIO</i> installation method (system-wide vs. user-specific), administrative privileges (e.g., using <b>sudo</b> on Linux/macOS) may be necessary to successfully perform the upgrade.<br>Using the <b>--dev</b> flag can lead to unstable software and is not recommended for critical projects.<br>Significant changes in <i>PlatformIO Core</i> versions might occasionally introduce minor incompatibilities with older project setups, though such instances are rare and usually documented.


title: INTERNET CONNECTION
content:
Successful execution of <b>pio upgrade</b> relies on an active internet connection to retrieve the latest <i>PlatformIO Core</i> packages from their official distribution servers.


title: PERMISSIONS
content:
For system-wide installations of <i>PlatformIO Core</i>, it is often necessary to run the <b>pio upgrade</b> command with elevated privileges (e.g., using <b>sudo pio upgrade</b> on Linux or macOS) to allow modifications to system directories.


title: DEVELOPMENT VERSION CAUTION
content:
While the <b>--dev</b> flag offers early access to cutting-edge features, it is crucial to understand that development versions are inherently less stable and might contain bugs. It should only be used by advanced users for testing purposes, not for production work.


title: HISTORY
content:
The <b>pio upgrade</b> command has been a core component of the <i>PlatformIO</i> CLI since its early days. Initially, users might have manually updated <i>PlatformIO</i> via <b>pip</b> commands, but the integrated <b>pio upgrade</b> command was introduced to provide a more consistent, user-friendly, and robust method for keeping the <i>PlatformIO Core</i> updated. Its evolution reflects <i>PlatformIO</i>'s commitment to simplifying embedded development workflows and ensuring users can easily access the latest tools and features without complex manual intervention. This command helps to bridge the gap between rapidly evolving hardware and software ecosystems.


title: SYNOPSIS
content:
While primarily invoked by <B>pio debug</B>, <I>piodebuggdb</I> is a Python script that can be directly executed (though not recommended for general users) with various configuration options:<br><br><B>python -m platformio.debug.piodebuggdb [OPTIONS]</B><br>or<br><B>piodebuggdb [OPTIONS]</B> <I>(if an alias or wrapper is set up)</I>


title: PARAMETERS
content:
<b><B>--project-dir &lt;path&gt;</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the PlatformIO project directory.<br><br><b><B>--environment &lt;env&gt;</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects the build environment (e.g., board configuration) defined in <I>platformio.ini</I>.<br><br><b><B>--port &lt;port&gt;</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the debug probe's communication port or device path (e.g., JTAG/SWD device).<br><br><b><B>--interface &lt;interface&gt;</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the debugging interface (e.g., <I>swd</I>, <I>jtag</I>).<br><br><b><B>--build-dir &lt;path&gt;</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Indicates the directory where build artifacts (like the firmware executable) are located.<br><br><b><B>--toolchain-path &lt;path&gt;</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides the absolute path to the GDB toolchain executable (e.g., <I>arm-none-eabi-gdb</I>).<br><br><b><B>--exec-path &lt;path&gt;</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the absolute path to the compiled firmware executable file to be debugged.<br><br><b><B>--extra-args &lt;args&gt;</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows passing additional, raw arguments directly to the invoked GDB client.<br><br><b><B>--ignore-debug-init</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents <I>piodebuggdb</I> from loading the default PlatformIO debug initialization script for GDB.<br><br><b><B>--interpreter &lt;interpreter&gt;</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the GDB interpreter mode (e.g., <I>mi</I> for machine interface, <I>console</I> for standard TUI).<br><br>


title: DESCRIPTION
content:
The <I>piodebuggdb</I> command is an <I>internal</I> Python script within the PlatformIO ecosystem, designed to orchestrate and configure GNU Debugger (GDB) sessions for embedded system development. It acts as a crucial bridge, taking PlatformIO project configuration settings (such as target board, debug probe, build environment, and firmware paths) and translating them into the necessary arguments and commands for a GDB client. While users typically initiate debugging through the higher-level <B>pio debug</B> command, <I>piodebuggdb</I> is the underlying utility responsible for launching GDB with the correct parameters, connecting it to the debug probe's GDB server (e.g., OpenOCD, J-Link GDB Server), and loading the target firmware for debugging on the microcontroller. It streamlines the complex setup process often associated with embedded debugging, providing a consistent interface across diverse hardware.


title: CAVEATS
content:
This command is an <I>internal implementation detail</I> of PlatformIO. It is not typically run directly by end-users but rather invoked and managed by the <B>pio debug</B> command. Direct invocation requires a deep understanding of PlatformIO's internal structure and GDB configuration. It relies on a correctly configured PlatformIO project, a compatible debug probe, and a running GDB server (which PlatformIO often manages itself).


title: GDB ORCHESTRATION
content:
<I>piodebuggdb</I>'s primary role is to act as an orchestrator for the GDB debugging session. It reads the detailed <I>platformio.ini</I> configuration, determines the correct GDB client executable, the GDB server address, and the target firmware. It then constructs the precise command-line arguments and initialization scripts that GDB needs to connect to the hardware and start debugging.


title: INTEGRATION WITH IDES
content:
This script is also leveraged by PlatformIO's IDE integrations (e.g., VS Code extension). When a user initiates a debug session from their IDE, the IDE calls <B>pio debug</B>, which in turn utilizes <I>piodebuggdb</I> to set up and launch the GDB process, allowing the IDE to interact with the GDB session seamlessly.


title: HISTORY
content:
<I>piodebuggdb</I> emerged as part of PlatformIO's continuous efforts to provide a seamless and integrated development experience for embedded systems. Its development has focused on abstracting the complexities of GDB setup, making it easier for developers to get started with debugging microcontrollers across various platforms and debug probes, without manually configuring GDB and its server components. It's a key component in PlatformIO's robust debugging framework, constantly updated to support new hardware and debug features.


title: PARAMETERS
content:
<b>--local</b><br>&nbsp;&nbsp;&nbsp;&nbsp;If a virtual environment is active, only display packages installed into that virtual environment. Otherwise, display packages installed in the global <i>site-packages</i>.<br><br><b>--user</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only display packages installed in the user's <i>site-packages</i> directory. This is useful when <i>pip</i> is configured to install packages only for the current user.<br><br><b>--path <dir></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Restrict to packages installed in the specified directory. This allows inspecting specific installation locations outside of the standard <i>site-packages</i> or virtual environments.<br><br><b>--all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show all installed packages, including those that are considered "editable" (e.g., installed with <i>pip install -e</i>). By default, editable packages are shown differently.<br><br><b>--exclude <package></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exclude specified package(s) from the output. This option can be used multiple times to exclude several packages (e.g., <i>--exclude pip --exclude setuptools</i>).<br><br><b>--exclude-editable</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exclude editable packages from the output. This is the opposite of <i>--all</i>, useful when you only want non-editable, 'production' dependencies.<br><br><b>--require-virtualenv</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exit with an error code if not run inside a virtual environment. This enforces best practices by ensuring dependency pinning only occurs within isolated environments.<br><br>


title: DESCRIPTION
content:
<i>pip freeze</i> is a fundamental command in the Python ecosystem for managing project dependencies. It serves to output a list of currently installed Python packages along with their exact version numbers. This list is formatted in a way that is directly compatible with <i>pip install -r</i>, making it an indispensable tool for creating <i>requirements.txt</i> files. These files ensure that all developers working on a project, or deployment environments, can install the identical set of dependencies, thus promoting consistency and reproducibility. The command inspects the active Python environment (whether it's a global installation or a virtual environment) and enumerates the packages found there. It's especially crucial for maintaining virtual environments, allowing users to capture the state of their isolated dependencies before sharing or deploying code.


title: CAVEATS
content:
<ul><li><b>Environment Specificity</b>:<br><i>pip freeze</i> lists packages from the <i>current</i> active Python environment. If you're not in a virtual environment, it will list global packages, which might not be desirable for project-specific dependency management.</li><li><b>Editable Installs</b>:<br> By default, editable installs (e.g., <i>pip install -e .</i> or <i>pip install -e git+...</i>) are outputted with a special format (e.g., <i>-e git+...#egg=package-name</i>). This differs from standard <i>package==version</i> pinning and requires careful handling if you intend to reproduce the exact setup. Use <i>--all</i> or <i>--exclude-editable</i> to modify this behavior.</li><li><b>No Transitive Dependencies</b>:<br><i>pip freeze</i> only lists the directly installed top-level packages. It does <i>not</i> show their dependencies. While <i>pip install -r</i> will automatically resolve and install transitive dependencies, <i>pip freeze</i> won't explicitly list them.</li><li><b>Exact Version Pinning</b>:<br> The command outputs exact versions (<i>package==X.Y.Z</i>). While this ensures reproducibility, it can sometimes be too restrictive for development, where dependency ranges (<i>package~=X.Y</i>) might be preferred. However, for <i>requirements.txt</i> used in deployment, exact pinning is generally recommended.</li></ul>


title: COMMON USAGE: REQUIREMENTS.TXT
content:
The most common and recommended use of <i>pip freeze</i> is to generate a <i>requirements.txt</i> file.<br><i><pre>pip freeze > requirements.txt</pre></i><br>This file can then be used to install the exact same set of packages on another machine or environment: <br><i><pre>pip install -r requirements.txt</pre></i>. This practice is crucial for reproducible builds and collaborative development.


title: INTERPRETING OUTPUT
content:
The standard output format is <i>PackageName==VersionNumber</i>, e.g., <i>requests==2.28.1</i>. For editable installs, it typically shows <i>-e git+https://...#egg=PackageName</i>. This format is specifically designed for <i>pip install -r</i>.


title: BEST PRACTICES FOR REQUIREMENTS.TXT
content:
It's generally recommended to use <i>pip freeze</i> <b>within a virtual environment</b> to capture only project-specific dependencies. Avoid running it globally unless you explicitly want to list all system-wide installed packages. Regularly update your <i>requirements.txt</i> file as dependencies change during development.


title: HISTORY
content:
The <i>pip</i> (Python Package Installer) tool itself emerged as a replacement for <i>easy_install</i> around 2008-2010, aiming for a more robust and user-friendly experience in managing Python packages. The <i>freeze</i> command has been a core and indispensable feature from <i>pip</i>'s early days, central to its mission of simplifying dependency management and promoting reproducible builds. Its design allows for straightforward capturing of an environment's state, directly addressing the common challenge of ensuring consistent dependency sets across different development and deployment environments. The command's output format has remained largely consistent over time, solidifying its role as the de-facto standard for <i>requirements.txt</i> files.


title: SYNOPSIS
content:
<b>pip install</b> <i>[options]</i> <i><package></i> ...<br><b>pip install</b> <i>[options]</i> <b>-r</b> <i><requirements file></i><br><b>pip install</b> <i>[options]</i> <b>-e</b> <i><path/url></i><br><b>pip install</b> <i>[options]</i> <i><archive.whl or .tar.gz></i>


title: PARAMETERS
content:
<b><b>package</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the name of the package to install. Can include version specifiers like <i>package==1.0</i> or <i>package>=1.0</i>.<br><br><b><b>-r <file></b>, <b>--requirements <file></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Install packages listed in the given requirements file. Each line in the file specifies a package.<br><br><b><b>-e <path/url></b>, <b>--editable <path/url></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Install a project in editable mode (for development). This creates a link to the source code.<br><br><b><b>--upgrade</b>, <b>-U</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Upgrade all specified packages to the newest available version.<br><br><b><b>--force-reinstall</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reinstall all packages even if they are already installed and up-to-date.<br><br><b><b>--user</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Install packages into the user's site-packages directory instead of the system-wide one.<br><br><b><b>--target <dir></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Install packages into the specified directory.<br><br><b><b>--no-deps</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not install package dependencies.<br><br><b><b>--no-cache-dir</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable the pip cache.<br><br><b><b>--index-url <url></b>, <b>-i <url></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Base URL of the Python Package Index (default is PyPI).<br><br><b><b>--extra-index-url <url></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Additional URLs to search for packages.<br><br>


title: DESCRIPTION
content:
The <b>pip install</b> command is the primary method for installing Python packages from the Python Package Index (PyPI) or other package indexes. It automates the process of downloading, building (if necessary), and installing Python libraries and their dependencies, making it simple for developers to manage project requirements. <b>pip</b> resolves dependencies recursively, ensuring all necessary components are installed. It supports various installation sources, including PyPI, version control systems, local directories, and distribution archives. When used with a <i>requirements.txt</i> file, <b>pip install</b> can install multiple packages at once, making project setup consistent and reproducible. It's an essential tool in the Python ecosystem for setting up development environments and deploying applications.


title: CAVEATS
content:
<b>pip install</b> can lead to issues if not used carefully. Installing packages globally (without a virtual environment) can cause conflicts between different projects requiring different versions of the same package. It's highly recommended to use <i>virtual environments</i> (e.g., <b>venv</b> or <b>conda</b>) to isolate project dependencies. Installing directly from untrusted sources can pose security risks. Dependency resolution can sometimes be complex, leading to version conflicts, especially when multiple packages depend on different versions of a common library.


title: <B>VIRTUAL ENVIRONMENTS BEST PRACTICE</B>
content:
Always use virtual environments (e.g., <b>python -m venv .venv</b>) for new Python projects. This isolates project dependencies, preventing conflicts with other projects or system-wide Python installations. Activate the environment (<i>source .venv/bin/activate</i> on Linux/macOS, <i>.venv\Scripts\activate</i> on Windows) before using <b>pip install</b>.


title: <B>REQUIREMENTS FILES</B>
content:
Use <b>pip freeze > requirements.txt</b> to save a list of your project's exact dependencies. This allows others to install the same versions with <b>pip install -r requirements.txt</b>, ensuring consistent environments.


title: HISTORY
content:
<b>pip</b> (short for "Pip Installs Packages" or "Preferred Installer Program") emerged as a replacement for <b>easy_install</b> in 2008. It was developed by Ian Bicking, who also created <b>virtualenv</b> and <b>setuptools</b>. <b>pip</b> quickly gained popularity due to its improved dependency resolution, easier uninstallation of packages, and support for <i>requirements.txt</i> files, which <b>easy_install</b> lacked. It became the recommended package installer for Python and has been included with Python distributions since Python 3.4. Its development has continued to evolve, adding features like wheel support and a more robust resolver.


title: SYNOPSIS
content:
<b>pip uninstall</b> [<i>options</i>] <<i>package</i>>... <br><b>pip uninstall</b> [<i>options</i>] <b>-r</b> <<i>requirements_file</i>>


title: PARAMETERS
content:
<b>-y, --yes</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Don't ask for confirmation</b> of uninstall deletions. Removes packages without prompting.<br><br><b>-r, --requirements <<i>file</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uninstall all the packages listed in the specified <i>requirements file</i>.<br><br><b>-e, --editable <<i>path/url</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uninstall an <b>editable project</b> (e.g., one installed with <i>pip install -e .</i>) by specifying its path or URL.<br><br><b>-t, --target <<i>dir</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Target directory from which to uninstall packages, instead of the default installation location.<br><br><b>--dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform a <b>dry run</b>: show what would be uninstalled without actually performing any deletions.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the command's <b>help message</b> and exit.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increase output verbosity. Can be used multiple times for more detail.<br><br><b>-q, --quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress output. Can be used multiple times for less detail.<br><br><b>--no-input</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not prompt for any input, including confirmation prompts.<br><br><b>--break-system-packages</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b><i>(DANGEROUS)</i></b> Allow pip to modify system-wide packages. Use with extreme caution as it can destabilize your system's Python environment.<br><br>


title: DESCRIPTION
content:
<i>pip uninstall</i> is a command-line utility provided by pip, the Python package installer, used to remove installed Python packages from your system or a specific Python environment.<br><br>When executed, it identifies the files associated with the specified package(s) and prompts the user for confirmation before deleting them. This includes package code, metadata, and scripts installed by the package. It helps maintain a clean and organized Python environment, allowing developers to remove unused dependencies or resolve conflicts caused by different package versions.<br><br>Unlike some system package managers, <i>pip uninstall</i> does <b>not</b> automatically uninstall packages that were installed as dependencies of the package being removed, nor does it resolve reverse dependencies (i.e., it won't tell you if other installed packages depend on the one you're removing). Users must manually manage these relationships, which can sometimes lead to broken environments if not handled carefully.<br><br>It is highly recommended to use <i>pip uninstall</i> within isolated Python environments (like virtual environments) to prevent unintended removal of packages that might be crucial for system-wide applications or other projects.


title: CAVEATS
content:
<b>Dependency Management:</b> <i>pip uninstall</i> does <b>not</b> automatically uninstall unused dependencies or check for reverse dependencies. Manually track dependencies to avoid breaking other installed packages.<br><br><b>System-Wide Installations:</b> Avoid uninstalling packages from your system's global Python environment directly. Always prefer using <I>virtual environments</I> to isolate project dependencies and prevent conflicts.<br><br><b>Permissions:</b> You need appropriate write permissions to the installation directories (e.g., site-packages) to uninstall packages. Using <i>sudo</i> with pip is generally discouraged unless strictly necessary and understood.<br><br><b>Incomplete Uninstalls:</b> In rare cases, especially with manually installed packages or unusual package structures, <i>pip uninstall</i> might not remove all associated files. Manual cleanup may be required.


title: BEST PRACTICES FOR UNINSTALLING
content:
Always use <i>pip uninstall</i> within a <b>virtual environment</b> to ensure that only project-specific dependencies are affected. Before uninstalling a critical package, consider using the <b>--dry-run</b> option to see exactly what files will be removed. Regularly review your project's <i>requirements.txt</i> to manage dependencies effectively.


title: RESOLVING DEPENDENCY ISSUES
content:
Since <i>pip uninstall</i> doesn't manage reverse dependencies, if you encounter 'ModuleNotFoundError' after uninstalling a package, it's likely another package relied on it. Use <b>pip show <<i>package_name</i>></b> to see its dependencies, and consider reinstalling the necessary package or finding an alternative.


title: HISTORY
content:
The <I>pip</I> package manager emerged as an improvement over <I>easy_install</I> and was officially adopted as the recommended tool for installing Python packages. The <I>uninstall</I> functionality has been a core component of <I>pip</I> from its early development, providing essential package management capabilities. Its design reflects a philosophy of explicit control over installed packages rather than automatic dependency resolution for removal, contrasting with some system package managers.


title: SEE ALSO
content:
<b>pip install</b>(1), <b>pip list</b>(1), <b>pip show</b>(1), <b>pip freeze</b>(1), <b>python -m venv</b>(1)


title: SYNOPSIS
content:
<b>pip3</b> [<<i>general options</i>>] <<i>command</i>> [<<i>command options</i>>] [<<i>arguments</i>>]


title: PARAMETERS
content:
<b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show help message for <b>pip3</b> or a specific command.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show <b>pip</b> version and exit.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Give more output. Option is additive, and can be used up to 3 times.<br><br><b><b>-q</b>, <b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Give less output.<br><br><b><b>--log</b> <<i>path</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to a verbose log file.<br><br><b><b>--proxy</b> <<i>url</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an HTTP proxy in the form <I>user:passwd@proxy.server:port</I>.<br><br><b><b>--timeout</b> <<i>seconds</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the socket timeout for network operations (default 15 seconds).<br><br><b><b>--retries</b> <<i>times</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the number of retries for network errors (default 5).<br><br><b><b>--no-input</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not prompt for input of any kind.<br><br>


title: DESCRIPTION
content:
<b>pip3</b> is the standard package management system used to install and manage software packages written in <B>Python 3</B>.<br><br>It connects to the <B>Python Package Index</B> (<I>PyPI</I>), a large repository of Python software, and allows users to easily download, install, upgrade, and uninstall Python packages and their dependencies.<br><br>While <B>pip3</B> is a command-line utility, it is often recommended to invoke it via <B>python3 -m pip</B> to ensure that you are using the <B>pip</B> instance associated with your specific <B>Python 3</B> interpreter, especially when multiple Python versions are present on a system. This helps prevent conflicts and ensures that packages are installed into the correct environment.<br><br><B>pip3</B> plays a crucial role in the Python ecosystem, enabling developers to easily share and reuse code by managing project dependencies efficiently.


title: CAVEATS
content:
Using <B>pip3 install</B> with <B>sudo</B> (i.e., installing packages globally) is generally discouraged as it can interfere with system-managed Python packages and lead to conflicts. It's highly recommended to use <B>virtual environments</B> (created with <B>python3 -m venv</B>) for project-specific dependencies, or install packages to the user site directory with <B>pip3 install --user</B> for personal use. Recent versions of <B>pip</B> also introduced a <B>--break-system-packages</B> flag to explicitly acknowledge modifications to system Python, making it harder to accidentally corrupt the system Python installation.


title: RECOMMENDED INVOCATION
content:
While <B>pip3</B> is a common command, the most robust way to invoke <B>pip</B> for <B>Python 3</B> is <B>python3 -m pip</B>. This ensures that the <B>pip</B> module from the specific <B>python3</B> interpreter being used is executed, preventing potential issues when multiple Python versions or virtual environments are active.


title: KEY SUBCOMMANDS
content:
Some of the most frequently used <B>pip3</B> subcommands include:<br><ul><li><B>install</B>: Installs packages from <I>PyPI</I> or other sources.</li><li><B>uninstall</B>: Removes installed packages.</li><li><B>list</B>: Lists installed packages.</li><li><B>freeze</B>: Outputs installed packages in requirements format.</li><li><B>show</B>: Shows information about installed packages.</li><li><B>check</B>: Verify installed packages have compatible dependencies.</li></ul>


title: VIRTUAL ENVIRONMENTS
content:
For development, it's highly recommended to use <B>virtual environments</B> (e.g., with <B>python3 -m venv</B> or <B>virtualenv</B>). A virtual environment creates an isolated Python installation, allowing you to install packages for a specific project without affecting the global Python installation or other projects. This prevents dependency conflicts and ensures project portability.


title: HISTORY
content:
<B>pip</B>, originally called <I>pyinstall</I>, was created by Ian Bicking in 2008 as a replacement for <I>easy_install</I>. Its name is a recursive acronym, "Pip Installs Packages." The <B>pip3</B> variant emerged with the widespread adoption of <B>Python 3</B> to specifically target Python 3 environments, distinct from Python 2 installations that often used just <B>pip</B>.<br><br>Since <B>Python 3.4</B>, <B>pip</B> (and by extension <B>pip3</B>) has been included by default with <B>Python</B> distributions, establishing it as the official and de-facto standard package installer for the language. It is actively maintained and developed by the <I>Python Packaging Authority</I> (<I>PyPA</I>).


title: SYNOPSIS
content:
<b>pipenv</b> <i>[options]</i> &lt;<i>command</i>&gt; <i>[command_options_and_args]</i><br><br><b>Common Commands:</b><br>  &nbsp;&nbsp;<b>install</b> <i>[packages] [options]</i> - Installs packages and manages the Pipfile/Pipfile.lock.<br>  &nbsp;&nbsp;<b>shell</b> - Spawns a shell within the virtual environment.<br>  &nbsp;&nbsp;<b>run</b> &lt;<i>command</i>&gt; <i>[args]</i> - Runs a command within the virtual environment.<br>  &nbsp;&nbsp;<b>sync</b> - Installs all packages specified in Pipfile.lock.<br>  &nbsp;&nbsp;<b>uninstall</b> <i>[packages] [options]</i> - Uninstalls packages.<br>  &nbsp;&nbsp;<b>update</b> <i>[packages] [options]</i> - Updates packages to their latest versions.<br>  &nbsp;&nbsp;<b>graph</b> - Displays a graph of installed dependencies.<br>  &nbsp;&nbsp;<b>check</b> - Checks for security vulnerabilities and PEP 508 markers.


title: PARAMETERS
content:
<b><b>--python</b> &lt;<i>path_to_python</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a Python interpreter to use for the virtual environment (e.g., <i>--python 3.9</i> or <i>--python /usr/bin/python3.10</i>).<br><br><b><b>--dev</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Installs development packages defined in the <i>[dev-packages]</i> section of the <i>Pipfile</i>.<br><br><b><b>--pre</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows the installation of pre-release versions of packages.<br><br><b><b>--skip-lock</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skips the generation or update of <i>Pipfile.lock</i>, which can speed up operations but sacrifices determinism.<br><br><b><b>--system</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces <i>pipenv</i> to use the system's <i>pip</i> and global Python environment instead of creating a virtual environment.<br><br><b><b>--pypi-mirror</b> &lt;<i>url</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a PyPI mirror URL to use for package lookups instead of the default PyPI.<br><br><b><b>--require-virtualenv</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ensures that <i>pipenv</i> operates within an active virtual environment; aborts if not.<br><br><b><b>--where</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the path to the project directory where <i>pipenv</i> is operating.<br><br><b><b>--venv</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the path to the virtual environment associated with the current project.<br><br><b><b>--rm</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes the virtual environment associated with the current project.<br><br><b><b>--bare</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Produces minimal output, useful for scripting or CI/CD pipelines.<br><br>


title: DESCRIPTION
content:
<i>pipenv</i> is a Python dependency management tool that combines the best of <i>pip</i> and <i>virtualenv</i> into a single utility. It aims to simplify the Python development workflow by managing virtual environments and project dependencies in a consistent and reproducible manner.<br><br>Instead of <i>requirements.txt</i>, <i>pipenv</i> uses a <i>Pipfile</i> to explicitly declare project dependencies. It automatically creates and manages a project-specific virtual environment, ensuring that your project's dependencies are isolated from other Python projects and the system's global Python installation.<br><br>Key features include cryptographic hashing of dependencies for deterministic builds via <i>Pipfile.lock</i>, a unified workflow for installing, uninstalling, and updating packages, and convenient commands like <b>pipenv shell</b> to activate the environment or <b>pipenv run</b> to execute commands within it. It streamlines setting up development environments and deploying applications, making dependency management less error-prone and more efficient.


title: CAVEATS
content:
<i>pipenv</i>, while powerful, has been subject to debate regarding its complexity and sometimes slower performance compared to using <i>pip</i> and <i>virtualenv</i> separately. Its strict dependency resolution and reliance on <i>Pipfile.lock</i> can sometimes lead to issues when dealing with complex dependency graphs or private package indexes that are not well-behaved. Community adoption has varied, with some developers preferring newer alternatives like <i>Poetry</i> for their opinionated workflows, or sticking to the simpler <i>pip</i> + <i>venv</i> approach.


title: PIPFILE AND PIPFILE.LOCK
content:
<i>Pipfile</i> is a high-level declaration of project dependencies, replacing <i>requirements.txt</i>. It's more declarative, supporting different environments (e.g., development dependencies). <i>Pipfile.lock</i> is a generated file that cryptographically hashes all package dependencies and sub-dependencies, ensuring deterministic builds across different machines and deployments. It guarantees that running <b>pipenv sync</b> will install the exact same versions of packages every time.


title: VIRTUAL ENVIRONMENT MANAGEMENT
content:
<i>pipenv</i> automatically creates and manages a virtual environment for each project. By default, it places these environments in a central location (e.g., <i>~/.local/share/virtualenvs</i>), but it can also be configured to create them within the project directory (by setting the <i>PIPENV_VENV_IN_PROJECT</i> environment variable to <i>1</i>).


title: HISTORY
content:
<i>pipenv</i> was created by Kenneth Reitz in 2017 with the goal of bringing the best features from various package managers (like npm, yarn, bundler) to the Python ecosystem. It gained significant initial traction and was, for a period, considered the Python Packaging Authority's (PyPA) recommended tool for application dependency management. However, PyPA later shifted its official recommendation back to the more fundamental tools, <i>pip</i> and <i>venv</i>, citing <i>pipenv</i>'s complexity and specific design choices. Despite this, <i>pipenv</i> continues to be actively maintained and widely used by many Python developers for its comprehensive features and streamlined workflow, especially for project-based development.


title: PARAMETERS
content:
<b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Displays the version information of the <b>piper</b> application.</i><br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Shows a brief help message with available command-line options.</i><br><br><b><b>--display=</b><i>DISPLAY</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies the X display to use for the graphical interface. This is a standard GTK option.</i><br><br><b><b>--device=</b><i>PATH</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Allows specifying a particular device path (e.g., <b>/dev/hidrawX</b>) to open directly within <b>piper</b>, bypassing automatic device discovery.</i><br><br>


title: DESCRIPTION
content:
<i><b>piper</b> is a graphical user interface (GUI) application designed for configuring various settings on compatible gaming mice in Linux. It provides a user-friendly frontend to the underlying <b>libratbag</b> library and the <b>ratbagd</b> D-Bus daemon, which handle the actual communication with the hardware.<br><br>With <b>piper</b>, users can easily customize a wide array of mouse parameters, including but not limited to:<br><ul><li><b>DPI/CPI sensitivity levels:</b> Adjusting the precision of mouse movement.</li><li><b>Button assignments:</b> Remapping buttons, including extra side buttons, to perform specific actions, keyboard shortcuts, or macros.</li><li><b>LED lighting:</b> Controlling RGB lighting effects, colors, and patterns.</li><li><b>Profiles:</b> Creating and managing multiple configuration profiles that can be switched on the fly, often tied to specific applications or games.</li></ul><b>piper</b> aims to bring a level of configuration convenience to Linux users that is common on other operating systems for gaming peripherals, making it an essential tool for gamers and power users alike who wish to fine-tune their mouse hardware.</i>


title: CAVEATS
content:
<i><br><b>piper</b> relies heavily on the <b>libratbag</b> library and the <b>ratbagd</b> daemon. For <b>piper</b> to function correctly, <b>ratbagd</b> must be installed and running as a system service. Without it, <b>piper</b> will not be able to detect or configure mice.<br><br>Device compatibility is dictated by <b>libratbag</b>. Not all gaming mice are supported; only those for which <b>libratbag</b> has implemented drivers will work. Users should verify their mouse is supported by the <b>libratbag</b> project.<br><br>Proper user permissions (via udev rules) are often required to access the HID devices without needing to run <b>piper</b> as root. If devices are not detected, checking udev rules and group memberships (e.g., 'plugdev' or 'input') is a common troubleshooting step.<br><br>As a graphical application, <b>piper</b>'s command-line options are limited, primarily serving for launching or basic debugging rather than extensive scripting or batch operations.</i>


title: <I>DEPENDENCIES</I>
content:
<i><b>piper</b> relies heavily on the <b>libratbag</b> library and the <b>ratbagd</b> D-Bus daemon. <b>libratbag</b> handles the communication protocols with various gaming mice, while <b>ratbagd</b> provides a persistent service for managing device configurations. Users must ensure these components are installed and running for <b>piper</b> to function correctly.</i>


title: <I>DEVICE SUPPORT</I>
content:
<i>The range of mice supported by <b>piper</b> is directly tied to the devices supported by the underlying <b>libratbag</b> project. Not all gaming mice are compatible. Users should consult the <b>libratbag</b> project documentation (often on its GitHub page) for an up-to-date list of supported peripherals.</i>


title: HISTORY
content:
<i><b>piper</b> was developed as a user-friendly graphical frontend for the <b>libratbag</b> project. The motivation behind <b>libratbag</b> (and consequently <b>piper</b>) was to provide a standardized, open-source solution for configuring gaming mice on Linux, a functionality often restricted to proprietary software on other operating systems. Before <b>piper</b>, configuring advanced gaming mouse features on Linux was either impossible or required cumbersome manual configuration and reverse-engineering efforts.<br><br>The development of <b>piper</b> in conjunction with <b>libratbag</b> filled a significant gap in the Linux gaming ecosystem, offering a much-needed accessible interface for managing gaming peripheral settings, thereby enhancing the overall Linux gaming experience. It continues to evolve with support for new devices and features as they are added to the underlying <b>libratbag</b> library.</i>


title: SYNOPSIS
content:
pipes.sh [<b>-c</b>|<b>--colors</b>] [<b>-p</b> <i>num</i>|<b>--pipes</b>=<i>num</i>] [<b>-t</b> <i>delay</i>|<b>--timeout</b>=<i>delay</i>] [<b>-f</b> <i>char</i>|<b>--frame</b>=<i>char</i>] [<b>-u</b>|<b>--unicode</b>] [<b>-h</b>|<b>--help</b>]


title: PARAMETERS
content:
<b><b>-c</b> or <b>--colors</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables or disables color output for the pipes. By default, colors are often enabled.<br><br><b><b>-p</b> <i>num</i> or <b>--pipes</b>=<i>num</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum number of concurrent pipes that can be drawn on the screen. <i>num</i> is an integer; increasing this value creates a denser visualization.<br><br><b><b>-t</b> <i>delay</i> or <b>--timeout</b>=<i>delay</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the delay in microseconds between each frame update. <i>delay</i> is an integer; a smaller <i>delay</i> value results in faster animation.<br><br><b><b>-f</b> <i>char</i> or <b>--frame</b>=<i>char</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the character used to draw the pipes. <i>char</i> is a single character; this allows customization of the visual style.<br><br><b><b>-u</b> or <b>--unicode</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the use of Unicode block characters for drawing the pipes, which can result in a more solid and visually distinct appearance if supported by the terminal.<br><br><b><b>-h</b> or <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief help message summarizing the available options and usage.<br><br>


title: DESCRIPTION
content:
pipes.sh is a charming and purely aesthetic shell script designed to render a captivating animated visualization directly within your terminal window. Unlike traditional Linux commands focused on system operations or data manipulation, pipes.sh offers a unique visual experience, depicting a network of interconnected 'pipes' that continuously grow and move across the screen. It achieves this by leveraging ANSI escape codes, which allow for control over cursor movement and character output, effectively creating a dynamic, real-time graphical display using only text characters. Primarily used for recreational purposes, as a simple terminal screensaver, or to add a touch of whimsy to a workspace, the script is a testament to the versatility of shell scripting and terminal capabilities. Its appeal lies in its simplicity and the hypnotic, ever-changing patterns it generates, making it a popular choice for those looking to personalize their command-line interface with a dynamic background effect.


title: CAVEATS
content:
pipes.sh is not a standard Unix/Linux utility; it's a community-contributed shell script. Its exact behavior, options, and availability can vary significantly depending on the specific version downloaded or installed. It requires a terminal emulator that supports ANSI escape codes for cursor manipulation and color output. Running it continuously may consume CPU resources, especially with a high number of pipes or a very low timeout, potentially impacting system performance.


title: INSTALLATION AND AVAILABILITY
content:
pipes.sh is typically not pre-installed on most Linux distributions. Users usually obtain it by downloading the script from a public repository (e.g., GitHub) or by copying it from a shared collection of useful scripts. Some niche package managers or community repositories might offer it. Once downloaded, it generally needs executable permissions (<code>chmod +x pipes.sh</code>) to run.


title: PERFORMANCE CONSIDERATIONS
content:
While visually appealing, continuous execution of pipes.sh can lead to measurable CPU usage, especially with high frame rates or a large number of pipes. This is due to the constant redrawing of the screen and the shell's processing overhead. Users on resource-constrained systems might notice a slight slowdown. It's best used as a temporary visual effect rather than a permanent background process unless resources are abundant.


title: HISTORY
content:
pipes.sh doesn't have a single, official development history like core GNU utilities. Instead, it emerged as a popular open-source project and personal scripting endeavor within the Unix/Linux community. Numerous variations and forks of the script exist across platforms like GitHub and personal dotfile repositories, each with slightly different features or implementations. Its evolution is primarily driven by individual contributions aimed at refining the animation, adding customization options, or improving compatibility with various terminal emulators, reflecting a shared enthusiasm for terminal aesthetics and the creative potential of shell scripting.


title: PARAMETERS
content:
<b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Displays the version information of the PipeWire daemon.</i><br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Shows a help message detailing command-line options.</i><br><br><b><b>--verbose</b>, <b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Increases the verbosity of logging output, providing more detailed information.</i><br><br><b><b>--debug</b>, <b>-d</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Enables debug logging, outputting extensive debugging information which can be useful for troubleshooting.</i><br><br><b><b>--config</b> <I>FILE</I>, <b>-c</b> <I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies an alternative configuration file to load instead of the default.</i><br><br><b><b>--nofork</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Prevents the daemon from forking into the background; it runs in the foreground. Useful for debugging or when managed by an external process supervisor.</i><br><br><b><b>--daemonize</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Forces the daemon to run in the background (default behavior).</i><br><br><b><b>--system</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Runs PipeWire as a system-wide instance, rather than the more common per-user instance. This is typically used for specific server setups.</i><br><br>


title: DESCRIPTION
content:
The <b>pipewire</b> command launches the PipeWire multimedia server, a low-latency, graph-based framework designed to handle audio and video streams on Linux. Its primary goal is to unify and improve upon existing Linux multimedia systems like PulseAudio, JACK, and ALSA for audio, and V4L2 for video. PipeWire offers key features such as low-latency processing for professional audio applications, robust security for sandboxed environments (e.g., Flatpak, Snap), and efficient handling of video streams, including screen sharing capabilities. It aims to provide a modern, flexible, and secure foundation for all multimedia workloads, from desktop audio to complex professional studio setups, and to facilitate seamless integration with Wayland and containerized applications. It typically runs as a daemon, managed by systemd or similar init systems.


title: CAVEATS
content:
<i>PipeWire is a daemon and not typically interacted with directly by end-users via command-line options for daily use. Most configuration and interaction are handled through configuration files or client applications and utilities like <I>pw-cli</I> or <I>pw-top</I>. While stable and widely adopted, its complex graph architecture can make advanced troubleshooting challenging, especially for newcomers.</i>


title: CONFIGURATION FILES
content:
<i>PipeWire's behavior is extensively controlled via configuration files. The main configuration files are typically located in <I>/etc/pipewire/</I> (system-wide defaults) and <I>~/.config/pipewire/</I> (user-specific overrides). These files define modules, properties, and graph configurations for various audio and video sinks/sources, as well as rules for device handling.</i>


title: DAEMON OPERATION
content:
<i>The <B>pipewire</B> command primarily launches the PipeWire daemon process. This daemon manages all multimedia streams, devices, and connections on the system. Users and applications interact with this daemon through PipeWire client libraries (e.g., <I>libpipewire</I>) or through specialized tools like <I>pw-cli</I> for command-line control, rather than directly invoking the <B>pipewire</B> command itself for routine tasks. It is often started automatically at login or boot via systemd.</i>


title: HISTORY
content:
<i>PipeWire was initiated by Wim Taymans (Red Hat) in 2017 with the goal of addressing the limitations of existing Linux multimedia solutions. It aimed to provide a modern, low-latency framework capable of handling both professional audio (like JACK) and desktop audio (like PulseAudio) simultaneously, while also supporting video processing and offering better security for sandboxed applications. Its design focused on flexibility, modularity, and integration with modern Linux desktop technologies like Wayland. Since its inception, PipeWire has seen rapid adoption and is now the default audio and video server in many major Linux distributions, including Fedora, Ubuntu, and Arch Linux.</i>


title: PARAMETERS
content:
<b>NEW_ROOT</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The directory that will become the new root filesystem. This directory must be a mount point (i.e., the root of another mounted filesystem).<br><br><b>PUT_OLD</b><br>&nbsp;&nbsp;&nbsp;&nbsp;A directory inside <I>NEW_ROOT</I> where the original root filesystem will be moved. This directory must be empty and must be a subdirectory of <I>NEW_ROOT</I>. After the pivot, the old root filesystem will be accessible at this path.<br><br>


title: DESCRIPTION
content:
The <I>pivot_root</I> command (which wraps the <I>pivot_root(2)</I> system call) is used to change the root filesystem of the current process. It allows a process to move its current root filesystem to a new location and make a different mount point the new root.<br><br>Unlike <I>chroot</I>, which merely changes the apparent root directory for future operations within a process, <I>pivot_root</I> fundamentally alters the root of the entire mount namespace. This means that all processes in the current mount namespace will see the new filesystem as their root, and the old root filesystem becomes available at a specified mount point within the new root.<br><br>This functionality is crucial for several Linux operations, most notably during the system boot process (e.g., when transitioning from an <I>initramfs</I> to the real root filesystem) and in containerization technologies. It provides a robust mechanism for isolating processes and managing filesystem hierarchies.


title: CAVEATS
content:
The command requires <B>CAP_SYS_ADMIN</B> capability to execute.<br><br><I>NEW_ROOT</I> must be a mount point itself, not just a directory.<br><br><I>PUT_OLD</I> must be an empty directory residing within <I>NEW_ROOT</I>.<br><br>The old root filesystem must not be identical to <I>NEW_ROOT</I>.<br><br>It's often necessary to ensure that mounts are made private (<B>mount --make-rprivate /</B>) before using <I>pivot_root</I> to prevent unintended propagation of mount events.<br><br>Any files open on the old root filesystem will continue to refer to their original inodes, even after the root has changed.<br><br>The old root filesystem (now at <I>PUT_OLD</I>) typically needs to be explicitly unmounted later to free up resources.


title: DIFFERENCES FROM CHROOT
content:
While both <I>pivot_root</I> and <I>chroot</I> modify the root directory, they operate differently.<br><br><B>chroot</B>: Changes the root directory for the current process and its children. The old root remains accessible to the parent process and any other processes not affected by the <I>chroot</I>. It's primarily a security and isolation tool, but less robust for full system transitions.<br><br><B>pivot_root</B>: Changes the root of the entire mount namespace. The old root is moved to a specified location within the new root and becomes part of the new hierarchy. This makes it more suitable for situations like booting from an <I>initramfs</I> to the actual root filesystem, or setting up a full container environment where the old root needs to be effectively "hidden" or unmounted from the new environment.


title: TYPICAL USAGE PATTERN
content:
A common sequence for using <I>pivot_root</I> involves the following steps:<br>1. Prepare the new root filesystem (e.g., mount it):<br><I>mount /dev/sda1 /mnt/new_root</I><br>2. Create a directory within the new root for the old root to be moved to:<br><I>mkdir /mnt/new_root/old_root_dir</I><br>3. Execute <I>pivot_root</I>:<br><I>pivot_root /mnt/new_root /mnt/new_root/old_root_dir</I><br>After this, <I>/mnt/new_root</I> becomes <I>/</I>, and the original root filesystem (e.g., the <I>initramfs</I> root) is now accessible at <I>/old_root_dir</I>.<br>4. Clean up the old root (optional, but usually desired):<br><I>umount /old_root_dir</I>


title: HISTORY
content:
The <I>pivot_root(2)</I> system call was introduced in Linux kernel version 2.2, released in early 1999. It was developed to address limitations of the older <I>chroot(2)</I> system call, particularly in scenarios where the old root filesystem needed to be unmounted or remained accessible from within the new root.<br><br>Its primary initial use cases revolved around the boot process, allowing systems to transition smoothly from a minimal initial ramdisk (<I>initramfs</I>) environment to the full root filesystem without complex unmounting procedures. Over time, with the rise of containerization technologies like Docker and LXC, <I>pivot_root</I> became a fundamental building block for creating isolated execution environments.


title: PARAMETERS
content:
<b>install</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Initiates the interactive PiVPN setup wizard to configure your OpenVPN or WireGuard server.<br><br><b>add [nopass]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a new VPN client configuration file. The <i>nopass</i> option creates a client without a password (OpenVPN) or passphrase (WireGuard).<br><br><b>list / clients</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a comprehensive list of all configured VPN clients, including their current connection status.<br><br><b>revoke</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Revokes an existing client's certificate or key, immediately disabling their access to the VPN server.<br><br><b>debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs a diagnostic script to check the PiVPN setup and server status, providing useful information for troubleshooting.<br><br><b>uninstall</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes all PiVPN configurations, installed packages, and associated files from the system.<br><br><b>update</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Updates the PiVPN script itself to the latest version, ensuring you have the newest features and bug fixes.<br><br><b>upgrade</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Upgrades the underlying system packages using the system's package manager (e.g., <i>apt update && apt upgrade</i>).<br><br><b>qr</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the QR code for a specified WireGuard client configuration, facilitating easy setup on mobile devices.<br><br><b>disconnect</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disconnects a currently connected OpenVPN client.<br><br><b>enable <I>client_name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables a previously disabled WireGuard client, allowing it to connect to the VPN.<br><br><b>disable <I>client_name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables an active WireGuard client, preventing it from connecting until re-enabled.<br><br><b>help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows a list of available PiVPN commands and their basic usage.<br><br>


title: DESCRIPTION
content:
PiVPN is a script designed to simplify the process of setting up and managing a personal VPN server using either OpenVPN or WireGuard protocols. It automates the complex configuration steps on a Raspberry Pi or other Debian-based systems, including certificate generation, client profile creation, and firewall rules. The tool aims to make VPN server deployment accessible to users who want to secure their internet traffic, bypass geo-restrictions, or access their home network remotely. PiVPN provides a user-friendly command-line interface with interactive prompts for initial installation and various commands for ongoing management tasks such as adding, revoking, or listing VPN clients. It handles the generation of client configuration files (.ovpn for OpenVPN, plain text/QR for WireGuard) for easy distribution to client devices, ensuring a seamless setup experience. Regular updates help maintain security and compatibility.


title: CAVEATS
content:
<ul><li>Requires a clean installation of a Debian-based OS (e.g., Raspberry Pi OS, Ubuntu Server) for optimal results.</li><li>Should ideally be run on a dedicated machine or a virtual private server (VPS) to avoid conflicts with other services.</li><li>Requires root privileges to install and manage the VPN server.</li><li>Port forwarding might be necessary on your router if the server is behind a Network Address Translation (NAT) device.</li></ul>


title: CLIENT CONFIGURATION EXPORT
content:
PiVPN automates the generation of client configuration files. For OpenVPN, it creates <i>.ovpn</i> files that can be imported directly into OpenVPN client applications. For WireGuard, it provides plain text configurations or QR codes, which simplify setup on various devices, especially mobile phones.


title: PROTOCOL CHOICE
content:
During the initial installation, PiVPN prompts the user to choose between deploying an OpenVPN or WireGuard server. This flexibility allows users to select the protocol that best fits their needs regarding speed, security, and client compatibility.


title: HISTORY
content:
PiVPN was initially developed to streamline the installation and management of OpenVPN servers specifically for Raspberry Pi devices, making personal VPN deployment accessible to hobbyists and home users. Over time, its functionality expanded to include support for the WireGuard protocol, offering a more modern and performant VPN option. The project has consistently focused on user-friendliness, automation, and broad compatibility with various Debian-based distributions, solidifying its reputation as a go-to solution for setting up personal VPNs.


title: PARAMETERS
content:
<b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases verbosity of the output. Can be specified multiple times for more detail.<br><br><b>--quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses normal output, showing only errors.<br><br><b>--color <I>WHEN</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls when to use colored output. <I>WHEN</I> can be `auto`, `always`, or `never`.<br><br><b>--frozen</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ensures that the lockfile (`pixi.lock`) is not modified. An error occurs if a modification is needed.<br><br><b>--locked</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ensures that the lockfile (`pixi.lock`) is up-to-date with the `pixi.toml`. An error occurs if it's out of sync.<br><br><b>--manifest-path <I>PATH</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the `pixi.toml` manifest file. Defaults to the current directory.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the command or subcommand.<br><br>


title: DESCRIPTION
content:
<b>Pixi</b> is a modern, cross-platform package manager developed by prefix.dev, designed to create fast and reproducible development environments. It aims to unify dependency management across different language ecosystems, primarily focusing on Rust and Python, but capable of managing other tools and dependencies. Unlike traditional package managers that often focus on a single language, <b>pixi</b> leverages concepts similar to `conda` to manage environments and dependencies for multiple languages within a single project. It prioritizes speed, caching, and deterministic builds, making it an excellent choice for collaborative and continuous integration workflows. <b>Pixi</b> uses a `pixi.toml` file to declare project dependencies, scripts, and environment configurations.


title: CAVEATS
content:
<b>Pixi</b> is a relatively new tool compared to established package managers like `pip` or `conda`, and its ecosystem and feature set are still evolving. While powerful for polyglot projects, adoption requires integrating a new workflow. It's not typically pre-installed on Linux systems, requiring manual installation. Its dependency resolution relies on a `conda`-like solver, which might behave differently than pure `pip` or `cargo` resolvers.


title: KEY SUBCOMMANDS
content:
<b>pixi</b> operates primarily through subcommands:<br><br><b>install</b>: Installs project dependencies defined in `pixi.toml` and creates the environment.<br><b>run</b>: Executes scripts or commands defined in `pixi.toml` within the project's environment.<br><b>add</b>: Adds new dependencies to the project, updating `pixi.toml` and `pixi.lock`.<br><b>shell</b>: Enters a shell with the project's environment activated.<br><b>update</b>: Updates project dependencies to their latest compatible versions.<br><b>remove</b>: Removes dependencies from the project.


title: INSTALLATION
content:
<b>Pixi</b> can be installed on Linux (and other OSes) typically via a one-liner script provided by prefix.dev or by downloading pre-built binaries. For example, using `curl | bash` or through a package manager like `brew` on macOS. It's often installed into a user's local binary path, requiring it to be added to the `PATH` environment variable for direct execution.


title: HISTORY
content:
Developed by prefix.dev, <b>pixi</b> emerged from the need for a more robust and unified package management solution for polyglot development environments, particularly in scientific computing and data science where Python and Rust often coexist. Its development began in the early 2020s, drawing inspiration from existing tools while aiming to improve reproducibility, speed, and cross-platform consistency. It has gained traction among developers seeking deterministic builds and simplified environment setup.


title: SYNOPSIS
content:
<i>pixi config</i><br><i>pixi config get</i> &lt;<i>key</i>&gt;<br><i>pixi config set</i> &lt;<i>key</i>&gt; &lt;<i>value</i>&gt;<br><i>pixi config unset</i> &lt;<i>key</i>&gt;<br><i>pixi config list</i><br><i>pixi config edit</i>


title: PARAMETERS
content:
<b>get &lt;key&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Retrieves the value associated with a specified configuration <i>key</i>. Can be combined with <i>--global</i> or <i>--local</i> to specify the scope.<br><br><b>set &lt;key&gt; &lt;value&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assigns a new <i>value</i> to a given configuration <i>key</i>. If the key doesn't exist, it's created. Can be combined with <i>--global</i> or <i>--local</i>.<br><br><b>unset &lt;key&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes a specified configuration <i>key</i> and its value. Can be combined with <i>--global</i> or <i>--local</i>.<br><br><b>list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays all current active configuration key-value pairs, showing values from both global and local settings and their precedence.<br><br><b>edit</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens the relevant configuration file (either the global <i>~/.pixi/config.toml</i> or the local project's <i>.pixi/config.toml</i>) in the default text editor for manual modification.<br><br><b>--global</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Applicable to <i>get</i>, <i>set</i>, <i>unset</i>) Directs the command to operate specifically on the <b>global</b> configuration file, typically located at <i>~/.pixi/config.toml</i>.<br><br><b>--local</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Applicable to <i>get</i>, <i>set</i>, <i>unset</i>) Directs the command to operate specifically on the <b>local</b> project's configuration file, typically found at <i>.pixi/config.toml</i> within the project root.<br><br>


title: DESCRIPTION
content:
The <i>pixi config</i> command is a powerful subcommand of the <i>pixi</i> dependency manager, designed to manage various configuration settings for <i>pixi</i> projects and the global environment. It allows users to inspect, modify, and list key-value pairs that influence <i>pixi</i>'s behavior, such as proxy settings, preferred package sources, and other environmental variables. Configuration can be applied <b>globally</b>, affecting all <i>pixi</i> operations on the system, or <b>locally</b> within a specific project directory, overriding global settings for that particular project. This granularity ensures flexibility and reproducibility across different development workflows. It acts as a central hub for tailoring <i>pixi</i> to specific needs without modifying project files directly.


title: CAVEATS
content:
The command <i>pixi-config</i> is not a standalone executable. It is a subcommand of the <i>pixi</i> tool, correctly invoked as <b>pixi config</b>. Users should be aware of this distinction when using the command. Additionally, local project configurations always take precedence over global settings, and caution should be exercised when modifying sensitive information stored in plain text configuration files.


title: CONFIGURATION FILES
content:
<i>Pixi</i> stores its configuration in TOML format. The <b>global</b> configuration is typically located at <i>~/.pixi/config.toml</i> (or a path specified by the <i>PIXI_HOME</i> environment variable). <b>Project-specific</b> configurations are found at <i>.pixi/config.toml</i> within the root directory of a <i>pixi</i> project (or specified by <i>PIXI_PROJECT_ROOT</i>). These files contain key-value pairs that define <i>pixi</i>'s behavior, including package channels, proxy settings, and solver preferences.


title: CONFIGURATION PRECEDENCE
content:
When <i>pixi</i> resolves configuration settings for a given operation, values defined in the <b>local</b> project's <i>.pixi/config.toml</i> file always take precedence over identical keys defined in the <b>global</b> <i>~/.pixi/config.toml</i> file. This allows project-specific overrides without affecting other <i>pixi</i> environments or projects on the system, ensuring tailored behavior for individual development contexts.


title: HISTORY
content:
<i>Pixi</i> is a relatively modern and actively developed project, gaining significant attention since 2023 as a robust dependency and environment manager. The <i>config</i> subcommand has been an integral part of <i>Pixi</i>'s core functionality from its early stages, providing essential capabilities for users to customize their environment, manage package channels, and handle proxy settings without manual file editing. Its design reflects best practices from similar configuration management patterns seen in established tools like Git and npm, emphasizing user control and flexibility.


title: PARAMETERS
content:
<b><b>install</b> <I>package(s)</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Installs one or more packages globally, making their executables available in your PATH.<br><br><b><b>list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all currently installed global packages.<br><br><b><b>remove</b> <I>package(s)</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes one or more globally installed packages.<br><br><b><b>upgrade</b> [<i>package(s)</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Upgrades one or more specified global packages, or all global packages if none are specified, to their latest compatible versions.<br><br><b><b>run</b> <I>command</I> [<i>args</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes a command within the context of the global environment, allowing access to global packages.<br><br><b><b>bin</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the path to the directory where global executables are linked. This directory should typically be added to your system's PATH environment variable.<br><br>


title: DESCRIPTION
content:
<b>pixi-global</b> is a subcommand of <b>pixi</b>, a modern, cross-platform package manager and project environment tool developed by prefix.dev. While <b>pixi</b> primarily focuses on creating isolated, reproducible project environments defined by a <i>pixi.toml</i> file, the <b>pixi-global</b> command allows users to install and manage tools that should be available system-wide or across multiple projects. This is particularly useful for developer utilities, linters, formatters, and other command-line tools (e.g., <i>uv</i>, <i>ruff</i>, <i>rye</i>, <i>pre-commit</i>, <i>biome</i>, <i>jq</i>, <i>delta</i>) that you want to access from any directory without associating them with a specific project's dependencies.<br><br>It simplifies the process of setting up common development tools, ensuring they are consistently available and easily managed, leveraging <b>pixi</b>'s efficient dependency resolution and environment management capabilities from ecosystems like <i>conda-forge</i> and <i>PyPI</i>.


title: CAVEATS
content:
<b>pixi-global</b> manages tools in a dedicated global environment. For these tools to be directly executable from your shell, the directory where <b>pixi</b> links global executables (output of <i>pixi global bin</i>) must be added to your system's PATH environment variable. While convenient, global installations can sometimes conflict with other system-wide or manually installed versions of the same tools if PATH is not ordered carefully. It is primarily designed for user-level global installations rather than system-wide provisioning.


title: PATH CONFIGURATION
content:
To make globally installed <b>pixi</b> packages directly executable from any shell session, ensure that the output of <b><I>pixi global bin</I></b> is added to your system's <b>PATH</b> environment variable. This is usually done by adding a line like <i>export PATH="/path/to/pixi/global/bin:$PATH"</i> to your shell's configuration file (e.g., <i>.bashrc</i>, <i>.zshrc</i>, <i>.profile</i>).


title: ISOLATION
content:
Despite being "global," packages installed via <b>pixi-global</b> are managed within <b>pixi</b>'s internal structure, providing a degree of isolation from system-level package managers and potential conflicts. This allows for specific tool versions to be installed without affecting system libraries.


title: HISTORY
content:
<b>pixi</b> is a relatively new and rapidly evolving project, first released in late 2022 by prefix.dev. It was developed to address limitations of existing package managers by offering fast, reliable, and reproducible environments across various programming languages, leveraging the <i>conda-forge</i> ecosystem as well as <i>PyPI</i> for Python packages. The <b>global</b> subcommand was introduced as a core feature from early on, recognizing the need for developers to manage common CLI tools outside of specific project contexts, streamlining developer workstation setup and tool access.


title: SYNOPSIS
content:
<b>pixi project</b> <I>SUBCOMMAND</I> [OPTIONS]<br><br>Common Subcommands:<br><b>pixi project add</b> <I>DEPENDENCY</I>...<br><b>pixi project run</b> <I>SCRIPT_NAME</I> [ARGS]...<br><b>pixi project install</b><br><b>pixi project shell</b>


title: PARAMETERS
content:
<b>--manifest-path <PATH></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the <I>pixi.toml</I> manifest file, if not in the current directory.<br><br><b>--frozen</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents <I>pixi.lock</I> from being updated. Fails if the lock file is out of sync with <I>pixi.toml</I>.<br><br><b>--locked</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ensures <I>pixi.lock</I> is up-to-date with <I>pixi.toml</I>. Fails if it's out of sync without updating it.<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases the verbosity of the output, showing more detailed information.<br><br><b>--quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Decreases the verbosity of the output, showing less information.<br><br><b>add</b><br>&nbsp;&nbsp;&nbsp;&nbsp;A subcommand to add one or more dependencies to the project, updating <I>pixi.toml</I> and <I>pixi.lock</I>.<br><br><b>run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;A subcommand to execute a custom script or command defined within the <I>pixi.toml</I> file, within the project's environment.<br><br><b>install</b><br>&nbsp;&nbsp;&nbsp;&nbsp;A subcommand to install all dependencies specified in <I>pixi.lock</I> into the project's isolated environment.<br><br><b>shell</b><br>&nbsp;&nbsp;&nbsp;&nbsp;A subcommand to open a new shell with the project's environment activated, making project-specific tools and dependencies available.<br><br><b>update</b><br>&nbsp;&nbsp;&nbsp;&nbsp;A subcommand to update all project dependencies to their latest compatible versions and regenerate <I>pixi.lock</I>.<br><br><b>remove</b><br>&nbsp;&nbsp;&nbsp;&nbsp;A subcommand to remove specified dependencies from the project, updating <I>pixi.toml</I> and <I>pixi.lock</I>.<br><br><b>info</b><br>&nbsp;&nbsp;&nbsp;&nbsp;A subcommand to display comprehensive information about the current project and its environment.<br><br>


title: DESCRIPTION
content:
The <I>pixi project</I> command group is a central component of the <I>pixi</I> package manager, not a standalone executable. It provides a comprehensive suite of subcommands for managing all aspects of a software project's lifecycle, from initialization and dependency management to script execution and environment setup.<br><br>It orchestrates a project's dependencies, ensuring a reproducible and isolated environment across different machines and collaborators. <I>pixi project</I> leverages the <I>pixi.toml</I> manifest file to define project metadata, dependencies (for various languages like Python, Rust, etc.), and custom scripts, while the <I>pixi.lock</I> file guarantees exact dependency versions for consistent builds. This command group streamlines common development workflows, making it easier to manage complex, polyglot projects and integrate with underlying package managers like Conda.


title: CAVEATS
content:
The <I>pixi project</I> command group requires the <I>pixi</I> package manager to be installed. It operates on a project defined by a <I>pixi.toml</I> file, typically located in the current working directory or specified via <I>--manifest-path</I>. While powerful, <I>pixi</I> is a relatively new tool compared to established package managers, and its ecosystem and feature set are still evolving. Its underlying dependency resolution often relies on <I>conda</I> infrastructure, which might introduce specific behaviors or dependencies.


title: THE <I>PIXI.TOML</I> MANIFEST FILE
content:
This TOML file is the central configuration for a <I>pixi</I> project. It defines project metadata, specifies direct dependencies, lists development dependencies, and can include custom scripts or tasks. It's the primary way to declare your project's requirements and behavior.


title: THE <I>PIXI.LOCK</I> LOCK FILE
content:
Generated automatically by <I>pixi</I> based on <I>pixi.toml</I>, this file precisely pins the versions of all direct and transitive dependencies. It ensures that everyone working on the project, or deploying it, gets the exact same environment, guaranteeing reproducibility and preventing 'works on my machine' issues.


title: HISTORY
content:
<I>Pixi</I> emerged from the <I>prefix.dev</I> initiative, driven by the need for a modern, unified package manager that can handle polyglot projects across multiple operating systems. It was conceived to address the fragmentation in dependency management for environments combining languages like Python, Rust, JavaScript, and more, building upon lessons learned from tools like <I>conda</I> and <I>rye</I>.<br><br>The <I>project</I> subcommand group has been fundamental to <I>pixi</I>'s design from its early stages, providing the core interface for users to interact with their project's dependencies and environments. Its development reflects a focus on reproducibility, ease of use, and integration with existing package ecosystems.


title: SYNOPSIS
content:
<b><I>pixi</I></b> task [<b><I>OPTIONS</I></b>] <<b><I>TASK_NAME</I></b>> [<b><I>TASK_ARGUMENTS</I></b>...]<br><b><I>pixi</I></b> task [<b><I>OPTIONS</I></b>] --list<br><b><I>pixi</I></b> task [<b><I>OPTIONS</I></b>] --info <<b><I>TASK_NAME</I></b>>


title: PARAMETERS
content:
<b><<b><I>TASK_NAME</I></b>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the name of the task to be executed, as defined in the <b><I>pixi.toml</I></b> file.<br><br><b>[<b><I>TASK_ARGUMENTS</I></b>...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Any additional arguments provided after the task name are passed directly to the command or script executed by the task.<br><br><b>--list, -l</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all available tasks defined in the current <b><I>pixi</I></b> project's <b><I>pixi.toml</I></b> file.<br><br><b>--info <<b><I>TASK_NAME</I></b>>, -i <<b><I>TASK_NAME</I></b>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays detailed information about a specific task, including its command, dependencies, and type.<br><br><b>--frozen</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents any modifications to the <b><I>pixi.lock</I></b> file during task execution, ensuring a fully reproducible environment state.<br><br><b>--cwd <<b><I>PATH</I></b>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the current working directory from which the task should be executed. This overrides the default project root.<br><br><b>--target <<b><I>PLATFORM</I></b>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target platform for which the task should be executed (e.g., 'linux-64', 'win-64').<br><br>


title: DESCRIPTION
content:
The <b><I>pixi-task</I></b> command is a subcommand of the <b><I>pixi</I></b> package manager, designed to execute project-specific tasks defined within a <b><I>pixi.toml</I></b> configuration file. It provides a convenient way to encapsulate and run common development, testing, or build commands in a reproducible and isolated environment managed by <b><I>pixi</I></b>.<br><br>When invoked, <b><I>pixi-task</I></b> locates the <b><I>pixi.toml</I></b> file in the current directory or its parent directories, parses the defined tasks, and executes the specified one. Tasks can range from simple shell commands to complex scripts, and they automatically inherit the dependencies and environment setup by <b><I>pixi</I></b> for the project. This ensures that tasks run consistently regardless of the system's global environment.<br><br>Beyond simple execution, <b><I>pixi-task</I></b> supports listing available tasks, displaying detailed information about specific tasks, and passing additional arguments directly to the underlying command. It's a fundamental tool for streamlining project workflows, automating repetitive actions, and maintaining consistent development practices across teams.


title: CAVEATS
content:
The <b><I>pixi-task</I></b> command requires a <b><I>pixi.toml</I></b> file to be present in the current or a parent directory, as tasks are defined within this configuration. Task execution is contingent on the correct environment setup by <b><I>pixi</I></b>; issues with dependencies or environment resolution can prevent a task from running successfully. Arguments passed to a task (<b><I>TASK_ARGUMENTS</I></b>) are interpreted by the underlying command executed by the task, not by <b><I>pixi-task</I></b> itself.


title: TASK DEFINITION IN <B><I>PIXI.TOML</I></B>
content:
Tasks are defined under the <b><I>[tasks]</I></b> section of the <b><I>pixi.toml</I></b> file. Each task can be a simple string (shell command), a table with more options (e.g., <b><I>cmd</I></b>, <b><I>depends_on</I></b>, <b><I>install_from_channels</I></b>), or even a combination. For example:<br><i>[tasks]<br>  start = "python app.py"<br>  test = { cmd = "pytest", depends_on = ["lint"] }<br>  lint = "black ."</i><br>This structure allows for complex workflows where tasks can depend on each other, ensuring a specific execution order.


title: ENVIRONMENT INTEGRATION
content:
One of the key strengths of <b><I>pixi-task</I></b> is its deep integration with <b><I>pixi</I></b>'s managed environment. When a task is executed, <b><I>pixi</I></b> automatically ensures that all necessary dependencies specified in the <b><I>pixi.toml</I></b> are available and that the task runs within this isolated environment. This means commands like <b><I>python</I></b> or <b><I>pytest</I></b> inside a task will refer to the versions installed by <b><I>pixi</I></b> for that specific project, rather than any globally installed versions. This guarantees reproducibility and avoids conflicts between different projects or system-wide installations.


title: HISTORY
content:
<b><I>pixi-task</I></b> is an integral part of the <b><I>pixi</I></b> project, which emerged from the <b><I>prefix-dev</I></b> ecosystem as a next-generation package manager aiming to provide reproducible, cross-platform environments. From its inception, the ability to define and execute project-specific tasks has been a core design principle of <b><I>pixi</I></b>, addressing the need for streamlined development workflows in modern software projects. Its development closely mirrors the evolution of the broader <b><I>pixi</I></b> tool, continuously enhancing its capabilities for task management and environment integration.


title: PARAMETERS
content:
<b><b>-dhcp-addr</b> <I>address</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the network address and port for the DHCP server to listen on. Typically <i>:67</i> for all interfaces, or a specific IP like <i>192.168.1.1:67</i>.<br><br><b><b>-http-addr</b> <I>address</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the network address and port for the integrated HTTP server. Common values are <i>:80</i> or <i>:8080</i>.<br><br><b><b>-firmware</b> <I>path</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Designates a directory containing essential firmware files (e.g., <i>pxelinux.0</i>, <i>ipxe.efi</i>) that <i>pixiecore</i> will serve to clients based on their architecture and boot type.<br><br><b><b>-kernel</b> <I>path</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The absolute or relative path to the Linux kernel image (e.g., <i>vmlinuz</i>) that clients will download and boot.<br><br><b><b>-initrd</b> <I>path</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The absolute or relative path to the initial ramdisk image (e.g., <i>initrd.img</i>) required by the specified kernel.<br><br><b><b>-cmdline</b> <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Appends additional arguments to the kernel command line during the boot process (e.g., <i>console=ttyS0</i>, <i>ip=dhcp</i>, <i>root=/dev/sda1</i>).<br><br><b><b>-ipxe-script</b> <I>path</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides a path to a custom iPXE script to be served instead of the default boot sequence, offering advanced boot customization.<br><br><b><b>-extra-file</b> <I>path</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds an additional file to be served over HTTP. This option can be specified multiple times to serve various supporting files.<br><br><b><b>-debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose debugging output, which is useful for diagnosing issues during setup and operation.<br><br>


title: DESCRIPTION
content:
<i>pixiecore</i> is a streamlined network boot server designed to simplify bare-metal provisioning. Unlike traditional PXE setups that often require multiple services like DHCP, TFTP, and HTTP to be configured separately, <i>pixiecore</i> integrates these functionalities into a single, cohesive application. Written in Go, it aims for ease of deployment and management. It supports a wide range of boot firmware, including traditional BIOS PXE, UEFI, and iPXE, making it highly versatile for modern data centers and home labs.<br><br>It can serve various boot artifacts such as Linux kernels, initial ramdisks (initrds), and custom iPXE scripts, facilitating automated operating system installations or ephemeral boot environments. By providing a unified solution, <i>pixiecore</i> reduces the complexity and potential for misconfiguration often associated with network booting, making it an excellent tool for continuous integration/deployment pipelines for hardware.


title: CAVEATS
content:
Running <i>pixiecore</i> requires sufficient privileges (typically root or capabilities to bind privileged ports) to operate its DHCP and TFTP services (ports 67 and 69, respectively). If configured to serve HTTP on port 80, it also requires privileges for that port.<br><br>As it includes a DHCP server, <i>pixiecore</i> should be the <b>only</b> DHCP server active on its broadcast domain, or carefully configured to avoid conflicts, as multiple DHCP servers can lead to network instability. Appropriate firewall rules must be in place to allow inbound UDP traffic on ports 67 (DHCP) and 69 (TFTP), and TCP/UDP traffic on port 80 (HTTP) if used.


title: ARCHITECTURE AND OPERATION
content:
<i>pixiecore</i> functions as an all-in-one network boot solution. When a client initiates a PXE boot, <i>pixiecore</i>'s integrated DHCP server responds with the necessary boot information. It then serves the initial bootloader (e.g., <i>pxelinux.0</i>, <i>ipxe.efi</i>) via TFTP, and subsequent, larger files like kernels and initrds via HTTP for improved performance. This streamlined architecture avoids the complexities of configuring and troubleshooting separate DHCP, TFTP, and HTTP daemons, providing a more robust and manageable PXE environment. It intelligently handles different client architectures (BIOS/UEFI) and boot types to ensure compatibility.


title: COMMON USAGE PATTERNS
content:
<i>pixiecore</i> is frequently employed in automated server provisioning workflows, allowing organizations to rapidly deploy and configure bare-metal hardware. It's ideal for scenarios involving continuous integration/deployment (CI/CD) pipelines for physical servers, where machines need to be booted into an installer, a testing environment, or a minimal OS for initial setup. Its ability to serve custom iPXE scripts enables dynamic and highly flexible boot configurations, supporting diverse hardware and software requirements within a single PXE server instance.


title: HISTORY
content:
<i>pixiecore</i> was developed by Dan Anderson with the primary goal of simplifying the notoriously complex PXE booting process. It emerged from a need for a modern, single-binary solution that could integrate multiple network services (DHCP, TFTP, HTTP) typically required for network booting. Written in Go, it leverages the language's strengths in concurrency and cross-platform compilation, making it well-suited for automated bare-metal provisioning in cloud-native and datacenter environments. Its development focused on providing an opinionated, easy-to-use tool for efficient infrastructure management, contrasting with the often fragmented and cumbersome traditional PXE setups.


title: SEE ALSO
content:
<b>dnsmasq(8)</b>: A lightweight DHCP, DNS, and TFTP server often used for network booting., <b>tftpd-hpa(8)</b>: A common standalone TFTP server for serving boot files., <b>dhcpd(8)</b>: The ISC DHCP server, a robust and full-featured DHCP solution., <b>ipxe</b>: An open-source network boot firmware that expands on traditional PXE capabilities., <b>pxelinux</b>: A component of the SYSLINUX project, widely used for PXE booting Linux systems.


title: PARAMETERS
content:
<b>-c, --columns <i>&amp;lt;int&amp;gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target width of the image in character columns.<br><br><b>-r, --rows <i>&amp;lt;int&amp;gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target height of the image in character rows.<br><br><b>-s, --scale <i>&amp;lt;float&amp;gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a scaling factor to the image. A value of 1.0 means no scaling. Can be used instead of or in conjunction with <i>--columns</i> and <i>--rows</i>.<br><br><b>-t, --type <i>&amp;lt;string&amp;gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the output rendering type. Common values include <i>ascii</i>, <i>block</i>, <i>braille</i>, <i>iterm</i>, <i>kitty</i>, and <i>sixel</i>. The default usually attempts auto-detection or falls back to a suitable method.<br><br><b>-j, --jpeg-quality <i>&amp;lt;int&amp;gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the JPEG compression quality (0-100) when rendering images using methods that involve JPEG encoding (e.g., some inline protocols). Higher values mean better quality but larger data.<br><br><b>-w, --watch</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Monitors the input image file for changes and automatically re-renders the image in the terminal when modifications are detected. Useful for dynamic content or development.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message with usage information and available options.<br><br><b>-v, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the version information of the <i>pixterm</i> utility.<br><br>


title: DESCRIPTION
content:
<i>pixterm</i> is a versatile command-line tool written in Go that empowers users to render images directly within their terminal emulator. Unlike traditional image viewers that open a separate window, <i>pixterm</i> integrates graphical content seamlessly into the command-line environment. It achieves this by leveraging advanced terminal capabilities, including the iTerm2 inline image protocol, Kitty graphics protocol, and Sixel graphics, to display various image formats like PNG, JPEG, GIF, and BMP. This functionality is invaluable for developers, system administrators, and anyone working in a terminal, allowing for quick previews of images, embedding graphics in script outputs, or visualizing data without breaking the workflow. For terminals lacking these modern features, <i>pixterm</i> intelligently falls back to rendering images as less detailed but broadly compatible ASCII art, block characters, or braille patterns, ensuring a visual representation is always available.


title: CAVEATS
content:
<b>Terminal Compatibility:</b> <i>pixterm</i>'s advanced rendering capabilities (e.g., iTerm2, Kitty, Sixel) require a compatible terminal emulator. If your terminal does not support a specific protocol, the image may not display correctly or may fall back to less detailed ASCII/block rendering. <br><b>Performance:</b> Displaying very large images or continuously watching files with the <i>--watch</i> option can consume significant terminal resources or cause visual flickering, depending on your system and terminal emulator. <br><b>Installation:</b> <i>pixterm</i> is not a standard system utility and typically needs to be installed by compiling from source or using Go's package manager (<code>go install</code>).


title: SUPPORTED IMAGE FORMATS
content:
<i>pixterm</i> supports a wide range of common image formats, including PNG, JPEG, GIF, BMP, and WebP. The underlying Go image processing libraries ensure broad compatibility.


title: DEFAULT IMAGE SIZING
content:
When no specific dimensions (<i>--columns</i>, <i>--rows</i>) or scaling factor (<i>--scale</i>) are provided, <i>pixterm</i> attempts to automatically scale the image to fit within the current terminal window dimensions, preserving the aspect ratio.


title: HISTORY
content:
<i>pixterm</i> was created by Dalton Pereira as a modern command-line utility written in Go. Its development aimed to provide a user-friendly and efficient way to display graphical images directly within the terminal, leveraging the capabilities of modern terminal emulators while also offering broader compatibility through ASCII and block character rendering. It addresses the growing need for richer media display within command-line environments.


title: DESCRIPTION
content:
<i>pjtoppm</i> is a specialized utility from the Netpbm project, a comprehensive toolkit for image format conversion and manipulation. Its core function is to convert a PJPEG (Progressive JPEG) image file into a PPM (Portable Pixmap) format image file. Unlike traditional baseline JPEGs, Progressive JPEGs store image data in multiple scans, displaying a rough image quickly and then progressively refining its quality.<br><br>The PPM format is a simple, uncompressed representation of pixel data, making it an ideal intermediate format for subsequent processing by other Netpbm tools or custom scripts. <i>pjtoppm</i> typically reads the PJPEG data from standard input (or an optionally specified file) and writes the resulting PPM data to standard output. This design makes it highly suitable for use in Unix-style pipelines.<br><br>While more general converters like <i>jpegtopnm</i> exist, <i>pjtoppm</i> offers a focused conversion for progressive JPEGs, fitting seamlessly into the Netpbm philosophy of small, single-purpose tools that can be combined to achieve complex operations.


title: CAVEATS
content:
<i>pjtoppm</i> is designed specifically for Progressive JPEG files. Attempting to convert a baseline JPEG or a malformed file may result in errors or unexpected output. As a Netpbm tool, it assumes a pipeline-oriented workflow, meaning error messages are usually written to standard error and output to standard output.


title: STANDARD I/O USAGE
content:
<i>pjtoppm</i> heavily relies on standard input and output, making it highly suitable for chaining with other commands in a Unix shell. For example, to convert a progressive JPEG and then resize it, you might use: <br><code>cat image.pjp | pjtoppm | pnmscale 0.5 | pnmtopng &gt; output.png</code>


title: NETPBM INTEGRATION
content:
As part of the Netpbm suite, <i>pjtoppm</i> produces a PPM (Portable Pixmap) output, which is a common intermediate format for many Netpbm utilities. This allows for seamless transitions between various image processing steps within the Netpbm framework.


title: HISTORY
content:
<i>pjtoppm</i> is a component of the venerable Netpbm toolkit, which traces its origins back to the <i>pbmplus</i> package from the late 1980s. Netpbm's development has always emphasized modularity and the Unix philosophy of small, single-purpose tools that do one thing well. <i>pjtoppm</i> likely emerged to specifically address the conversion of Progressive JPEG formats, which became more common over time, into Netpbm's native intermediate formats. Its creation reflects the toolkit's ongoing evolution to support various image standards and facilitate interoperation within the Netpbm ecosystem.


title: SYNOPSIS
content:
<b>pkaction</b> [<i>OPTIONS</i>...] [<i>ACTION_ID</i>]<br>Example: <b>pkaction</b> --list-actions<br>Example: <b>pkaction</b> --action-id org.freedesktop.policykit.exec --verbose


title: PARAMETERS
content:
<b><b>--help</b>, <b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief help message and exits.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the version of the <b>pkaction</b> command and exits.<br><br><b><b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides more detailed output for the specified action ID, including properties like implicit authorization requirements.<br><br><b><b>--list-actions</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all registered Polkit action IDs. This is the default behavior if no <i>ACTION_ID</i> is specified.<br><br><b><b>--action-id</b> <I>ID</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the unique ID of the Polkit action to query. When provided, <b>pkaction</b> displays detailed information about this specific action.<br><br><b><b>--dump-system-locale</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Dumps the system's current locale settings, which can be relevant for localized action descriptions.<br><br>


title: DESCRIPTION
content:
<i>pkaction</i> is a command-line tool used to query and inspect <I>Polkit</I> (PolicyKit) actions. <I>Polkit</I> is an essential authorization framework that defines and handles privileges for system-wide services on modern Linux distributions. This command allows administrators and developers to gain insight into which authorization actions are registered on the system, what properties they possess (such as <b>id</b>, <b>description</b>, <b>vendor</b>, <b>icon</b>, and <b>implicit authorization</b> settings), and any associated annotations.<br><br>It's an invaluable tool for understanding the authorization policies enforced by <I>Polkit</I>. Whether you need to list all available actions or retrieve detailed information for a specific action ID, <i>pkaction</i> provides the necessary introspection. This capability is crucial for debugging authorization issues, developing applications that integrate with <I>Polkit</I>, or simply understanding the privilege management landscape of a Linux system. It offers a transparent view into the authorization logic configured by various installed software components.


title: CAVEATS
content:
The <b>pkaction</b> command requires the <I>Polkit</I> daemon (<b>polkitd</b>) to be running in order to query action information. It only provides introspection capabilities; it cannot be used to modify or configure <I>Polkit</I> policies. The output can be extensive, especially when listing all actions, requiring familiarity with <I>Polkit</I> concepts to fully interpret.


title: UNDERSTANDING ACTION IDS
content:
Polkit actions are uniquely identified by string IDs, typically following a reverse-DNS naming convention (e.g., <b>org.freedesktop.udisks2.filesystem-mount</b>). These IDs are defined by applications and services that integrate with <I>Polkit</I> for authorization purposes. They represent specific operations that might require elevated privileges or user consent.


title: IMPLICIT AUTHORIZATION DETAILS
content:
When using the <b>--verbose</b> option with a specific action ID, <b>pkaction</b> displays detailed information about the action's 'implicit authorization' requirements. These include values like <b>auth_self</b> (user needs to authenticate themselves), <b>auth_admin</b> (an administrator needs to authenticate), <b>auth_self_keep</b>, or <b>auth_admin_keep</b> (authentication persists for a session), and <b>no</b> (no authentication required). These settings dictate how <I>Polkit</I> handles authorization requests for that particular action.


title: HISTORY
content:
<I>Polkit</I> (originally PolicyKit) was developed by David Zeuthen at Red Hat as a fundamental framework for defining and handling authorizations for system-wide services on Unix-like operating systems. It became an integral part of modern Linux distributions, offering a more granular and flexible approach to privilege management compared to older mechanisms.<br><br>The <b>pkaction</b> utility has been a standard component of the <I>Polkit</I> suite since its early versions, providing essential introspection capabilities into the registered authorization actions. Its primary function—to query and display details about <I>Polkit</I> actions—has remained consistent, making it a key tool for system administrators and developers working with <I>Polkit</I>-enabled applications.


title: PARAMETERS
content:
<b>--allow-user-interaction</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allow polkit to query the user for authentication if necessary. This might lead to a graphical or text-based prompt.<br><br><b>--enable-session</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable session-specific authorization mechanisms, which are rarely used directly with <i>pkcheck</i>.<br><br><b>--system-bus-name NAME</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the D-Bus system bus name of the process whose authorization is being checked.<br><br><b>--system-bus-pid PID</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the PID of the process connected to the D-Bus system bus, whose authorization is being checked.<br><br><b>--process PROCESS_PID</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the PID of the process whose authorization is being checked.<br><br><b>--process-id PROCESS_ID</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Alias for <b>--process</b>, specifying the PID of the process to check.<br><br><b>--caller-pid CALLER_PID</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the PID of the calling process. By default, this is the parent process of <i>pkcheck</i>.<br><br><b>--action-id ACTION_ID</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>(Required)</b> The unique identifier of the action for which authorization is to be checked (e.g., <i>org.freedesktop.systemd1.restart-unit</i>).<br><br><b>DETAIL KEY VALUE...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more key-value pairs providing additional context for the authorization check. These details are specific to the action being checked.<br><br>


title: DESCRIPTION
content:
<i>pkcheck</i> is a command-line tool used to determine if a specific process is authorized to perform a particular PolicyKit (polkit) action. Polkit provides a framework for system-wide authorization, enabling unprivileged applications to interact securely with privileged system services. <i>pkcheck</i> queries the <i>polkitd</i> daemon, providing details about the requesting process (e.g., PID, D-Bus identity) and the requested action's identifier (<b>ACTION_ID</b>), along with any relevant context. It is frequently employed by applications or scripts to programmatically verify permissions before attempting operations that require elevated privileges. The command returns an exit code indicating whether authorization was granted, denied, or if an error occurred during the check. It can optionally allow user interaction (e.g., a password prompt) if configured by polkit rules.


title: CAVEATS
content:
<ul><li><i>pkcheck</i> relies on the <i>polkitd</i> daemon running. If the daemon is inactive, the command will fail with an error exit code (2).</li><li>Authorization decisions are entirely determined by polkit's configured policy rules, which can be complex and depend on various factors like user groups, process context, and the specific action details.</li><li>Using the <b>--allow-user-interaction</b> flag in scripts requires careful handling, as it may result in blocking prompts requiring manual input.</li></ul>


title: RETURN CODES
content:
<i>pkcheck</i> returns specific exit codes indicating the result of the authorization check:<br><ul><li><b>0</b>: The process is <i>authorized</i> to perform the action.</li><li><b>1</b>: The process is <i>not authorized</i> to perform the action.</li><li><b>2</b>: An error occurred and the authorization check could not be completed (e.g., the <i>polkitd</i> daemon is not running).</li></ul>


title: EXAMPLE USAGE
content:
<ul><li>To check if the current process can shut down the system without requiring user interaction:<br><i>pkcheck --action-id org.freedesktop.login1.power-off</i></li><li>To check if a specific PID (e.g., 1234) can install software, allowing for user interaction if needed:<br><i>pkcheck --process 1234 --allow-user-interaction --action-id org.freedesktop.packagekit.install-comps</i></li><li>To check if the current user can change the system hostname, providing a detail:<br><i>pkcheck --action-id org.freedesktop.hostname1.set-hostname --details hostname 'my_new_host'</i></li></ul>


title: HISTORY
content:
<i>pkcheck</i> is an integral component of the PolicyKit (later renamed to polkit) framework, initially developed by David Zeuthen at Red Hat. PolicyKit was introduced to provide a more granular and flexible authorization system compared to traditional Unix permissions and <i>sudo</i>.<br>It became a standard component in many Linux distributions, especially those utilizing <i>systemd</i>, serving to replace or complement older authorization mechanisms. <i>pkcheck</i> acts as the primary command-line interface for applications and administrators to query authorization status within this modern framework, ensuring consistent privilege management across the system.


title: PARAMETERS
content:
<b><b>install</b> <i>&lt;package&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Installs one or more specified packages.<br><br><b><b>remove</b> <i>&lt;package&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes one or more specified packages.<br><br><b><b>update</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Checks for and applies available system updates. Typically requires root privileges.<br><br><b><b>refresh</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Refreshes the local package metadata cache from configured repositories (similar to <b>apt update</b> or <b>dnf makecache</b>).<br><br><b><b>search</b> <i>&lt;keyword&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Searches for packages matching the given keyword in their names or descriptions.<br><br><b><b>get-details</b> <i>&lt;package&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays detailed information about a specific package, including description, version, and dependencies.<br><br><b><b>get-updates</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all available updates without installing them.<br><br><b><b>repo-list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all currently configured software repositories and their status.<br><br><b><b>--noninteractive</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs the command without prompting for user input, useful for scripting.<br><br><b><b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the operation to proceed, overriding some checks or warnings.<br><br><b><b>--only-download</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;For update operations, downloads packages but does not install them.<br><br>


title: DESCRIPTION
content:
<b>pkcon</b> is the command-line utility for interacting with <i>PackageKit</i>, a cross-distribution package management system. <i>PackageKit</i> provides a consistent, high-level API for managing software, abstracting away the complexities and differences of native package managers such as <b>APT</b> (Debian/Ubuntu), <b>DNF/YUM</b> (Red Hat/Fedora), and <b>Zypper</b> (openSUSE).<br><br>Through <b>pkcon</b>, users and scripts can perform common software management tasks like searching for, installing, updating, and removing packages, as well as managing software repositories, using a single, unified interface. This makes it invaluable in diverse Linux environments or for automated scripting where the underlying package manager may vary. It communicates with the <b>packagekitd</b> daemon and leverages <i>PolicyKit</i> for secure privilege escalation.


title: CAVEATS
content:
<b>pkcon</b> relies on the <b>PackageKit</b> daemon being active; if the daemon is not running, commands will fail. While convenient, it might not expose all fine-grained options or provide the same performance as native package managers for specific operations. Error messages can sometimes be generic, requiring investigation with the underlying system's package manager.


title: POLICYKIT INTEGRATION
content:
<b>pkcon</b> extensively uses <i>PolicyKit</i> (now often referred to as <i>polkit</i>) for privilege management. This allows non-root users to perform administrative package operations after authentication, typically through a graphical password prompt or via <b>sudo</b> if configured, ensuring secure access to system-level package management functions.


title: UNDERLYING DAEMON
content:
All <b>pkcon</b> operations are processed by the <b>packagekitd</b> system daemon. <b>pkcon</b> acts as a client, sending requests to this daemon, which then translates them into actions using the specific package manager (e.g., <b>apt-get</b>, <b>dnf</b>) configured for the distribution.


title: HISTORY
content:
<i>PackageKit</i>, and consequently <b>pkcon</b>, was created by Richard Hughes, with its initial release in 2007. The primary goal was to provide a standardized, cross-distribution software management framework, abstracting the complexities of diverse package systems. It gained adoption through integration into major desktop environments like GNOME and KDE, with <b>pkcon</b> serving as its direct command-line interface for system administrators and power users.


title: SYNOPSIS
content:
<B>openssl pkcs12</B> [<I>-export</I> | <I>-import</I> | <I>-info</I>] [<I>-in filename</I>] [<I>-out filename</I>] [<I>-passin arg</I>] [<I>-passout arg</I>] [<I>options</I>]


title: PARAMETERS
content:
<b><I>-export</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies export mode. This creates a PKCS#12 file from a private key and certificate(s).<br><br><b><I>-import</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies import mode. This extracts a private key and certificate(s) from a PKCS#12 file.<br><br><b><I>-info</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints human-readable information about the contents of the PKCS#12 file.<br><br><b><I>-in filename</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The input file. For <I>-export</I>, this is typically the certificate file. For <I>-import</I> or <I>-info</I>, it's the PKCS#12 file itself.<br><br><b><I>-out filename</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The output file. For <I>-export</I>, this is the new PKCS#12 file. For <I>-import</I>, it's the PEM formatted output.<br><br><b><I>-passin arg</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The source for the input file's password. Can be <I>pass:password</I>, <I>env:VAR_NAME</I>, <I>file:path</I>, or <I>fd:number</I>.<br><br><b><I>-passout arg</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The source for the output file's password. Uses the same format as <I>-passin</I>.<br><br><b><I>-inkey filename</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Input private key file (required for <I>-export</I>).<br><br><b><I>-name "friendly name"</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a 'friendly name' for the key and certificate in the exported PKCS#12 file.<br><br><b><I>-chain</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes the full certificate chain in the exported PKCS#12 file.<br><br><b><I>-nodes</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;For <I>-import</I>, this option prevents encryption of the private key in the output PEM file.<br><br><b><I>-nokeys</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents importing or exporting private keys.<br><br><b><I>-nocerts</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents importing or exporting certificates.<br><br><b><I>-macalg algorithm</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the MAC algorithm to use (e.g., <I>sha256</I>).<br><br>


title: DESCRIPTION
content:
The <I>pkcs12</I> command, part of the <B>openssl</B> utility suite, is designed for handling PKCS#12 (Personal Information Exchange Syntax) files. These files are a common, standardized format for securely storing private keys and their associated X.509 certificates in a single, password-protected archive (often with <I>.p12</I> or <I>.pfx</I> extensions).<br><br>The <B>pkcs12</B> utility provides robust functionality to:<br>- <I>Export</I> a private key and its corresponding certificate(s) into a PKCS#12 file.<br>- <I>Import</I> (extract) a private key and certificate(s) from an existing PKCS#12 file into PEM format.<br>- <I>View</I> human-readable information about the contents of a PKCS#12 file.<br>- <I>Change</I> passwords associated with the PKCS#12 file or its private key.<br><br>It is an essential tool for certificate and key management in various secure contexts, including web servers, client authentication, and secure email systems, facilitating the secure transport and backup of cryptographic identities.


title: CAVEATS
content:
Handling PKCS#12 files involves sensitive cryptographic material, primarily private keys. <I>Weak passwords</I> or <I>insecure storage</I> of these files can severely compromise security. Ensure strong, unique passwords are used and the files are stored securely.<br><br>While <B>pkcs12</B> aims for broad compatibility, <I>interoperability issues</I> can occasionally arise when transferring PKCS#12 files between different cryptographic libraries or systems, especially when using non-standard options or very old/new encryption algorithms. The <I>-legacy</I> option may be required for compatibility with older systems, but it often entails using less secure cryptographic primitives.


title: COMMON USE CASES
content:
The primary applications of <B>pkcs12</B> include:<br>- <B>Exporting for Backup/Transfer:</B> Creating a single <I>.p12</I> file containing a private key and its certificate chain, making it easy to back up cryptographic identities or transfer them securely between systems.<br>- <B>Importing for Server/Client:</B> Extracting keys and certificates from a <I>.p12</I> file for use by web servers (e.g., Apache, Nginx) or client applications that require key/certificate pairs.<br>- <B>Viewing Contents:</B> Quickly inspecting the certificates, keys, and other attributes stored within a PKCS#12 file without needing to extract its components.


title: PASSWORD PROMPTING
content:
If password options like <I>-passin</I> or <I>-passout</I> are not explicitly provided, <B>openssl pkcs12</B> will interactively prompt the user for the necessary passwords on the command line. This provides a secure way to input credentials without exposing them in shell history.


title: HISTORY
content:
The PKCS#12 standard itself was published by RSA Laboratories to define a portable format for storing and transferring personal identity information (private keys, certificates). The <B>pkcs12</B> utility was developed as an integral part of the OpenSSL project, providing a robust command-line interface for managing these files. Its evolution has closely tracked the development of cryptographic standards and the OpenSSL library, incorporating support for new algorithms, improved security features, and enhanced usability over time to meet the demands of modern cryptographic applications.


title: SYNOPSIS
content:
<b>openssl pkcs7</b> [<b>-in <i>filename</i></b>] [<b>-out <i>filename</i></b>] [<b>-inform <i>DER|PEM</i></b>] [<b>-outform <i>DER|PEM</i></b>] [<b>-noout</b>] [<b>-print</b>] [<b>-text</b>] [<b>-nocerts</b>] [<b>-noattr</b>] [<b>-binary</b>] [<b>-certfile <i>file</i></b>]


title: PARAMETERS
content:
<b><b>-in <i>filename</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the input file from which to read the PKCS#7 structure. If omitted, standard input is used.<br><br><b><b>-out <i>filename</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output file to which to write the processed PKCS#7 structure. If omitted, standard output is used.<br><br><b><b>-inform <i>DER|PEM</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the input format for the PKCS#7 structure. Can be <i>DER</i> (binary) or <i>PEM</i> (Base64 encoded with headers).<br><br><b><b>-outform <i>DER|PEM</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output format for the PKCS#7 structure. Can be <i>DER</i> or <i>PEM</i>.<br><br><b><b>-noout</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents the output of the encoded (binary or PEM) version of the PKCS#7 structure. Typically used with <b>-print</b> or <b>-text</b> to display only human-readable content.<br><br><b><b>-print</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints a human-readable representation of the PKCS#7 structure's contents.<br><br><b><b>-text</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints a verbose, human-readable text version of the PKCS#7 structure, including detailed information about contained certificates and CRLs.<br><br><b><b>-nocerts</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When used with <b>-print</b> or <b>-text</b>, this option suppresses the printing of any certificates included within the PKCS#7 structure.<br><br><b><b>-noattr</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When used with <b>-print</b> or <b>-text</b>, this option suppresses the printing of any attributes included within the PKCS#7 structure.<br><br><b><b>-binary</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When used, it ensures output of the PKCS#7 structure in raw binary DER format, often implied by <b>-outform DER</b>.<br><br><b><b>-certfile <i>file</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a file containing additional certificates to be considered when processing the PKCS#7 structure, useful for providing a trust chain.<br><br>


title: DESCRIPTION
content:
The <b>openssl pkcs7</b> command is a specialized utility within the OpenSSL toolkit, designed for processing and inspecting data formatted according to the PKCS#7 (Cryptographic Message Syntax Standard) specification. This standard is widely used for digital signatures, enveloping of digital data, and certificate management. <br><br>The command allows users to read, print, and convert PKCS#7 structures, which are commonly found in files with extensions like <i>.p7b</i> or <i>.p7c</i> (PKCS#7 Certificate Bundle). It's instrumental for tasks such as extracting certificates from a PKCS#7 bundle, examining signed data, or inspecting the contents of an enveloped message. Its options focus on input/output formats, detailed printing, and handling of contained certificates and attributes, making it a valuable tool for cryptographic data analysis.


title: CAVEATS
content:
The <b>openssl pkcs7</b> command is primarily a <i>parser</i> and <i>viewer</i> for PKCS#7 structures. It does not perform cryptographic operations like signing, encryption, or direct signature verification. For these tasks, other OpenSSL commands such as <b>openssl smime</b> are typically used. Its options are focused on extracting information or converting formats rather than cryptographic operations themselves.


title: PKCS#7 FORMAT
content:
PKCS#7 (Cryptographic Message Syntax Standard, superseded by CMS, RFC 5652) defines structures for cryptographically protected data. It's used for digital signatures, digital envelopes, and crucially, for bundling and distributing certificates (e.g., <i>.p7b</i> files often contain certificate chains from CAs). The <b>pkcs7</b> command is specifically designed to interact with and extract information from these standardized data formats.


title: COMMON USE CASES
content:
This command is commonly used to extract certificates from <i>.p7b</i> files (certificate bundles received from Certificate Authorities), or to inspect the contents of a signed or enveloped message before being processed by other cryptographic tools. It helps in debugging or understanding the structure of PKCS#7 compliant data.


title: HISTORY
content:
The <b>pkcs7</b> command has been a fundamental part of the OpenSSL command-line utility for a significant portion of its development history, evolving from the SSLeay project. Its inclusion has consistently provided core functionality for handling PKCS#7 cryptographic message syntax. Its role has remained consistent as a tool primarily for inspection, format conversion, and extraction of information from these standardized cryptographic structures.


title: PARAMETERS
content:
<b><b>-inform</b> <I>arg</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the input key format. Common values include <b>DER</b> (DER encoded ASN.1), <b>PEM</b> (PEM encoded), <b>P12</b> (PKCS#12 bundle), or <b>ENGINE</b> (private key from an engine). Default is <b>PEM</b>.<br><br><b><b>-outform</b> <I>arg</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output key format. Values are <b>DER</b> or <b>PEM</b>. Default is <b>PEM</b>.<br><br><b><b>-in</b> <I>filename</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the input file containing the private key. If not specified, standard input is used.<br><br><b><b>-out</b> <I>filename</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output file for the private key. If not specified, standard output is used.<br><br><b><b>-topk8</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Indicates that the input key should be converted to PKCS#8 format. If omitted, the default is to assume input is PKCS#8 and convert to traditional format.<br><br><b><b>-nocrypt</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When used with <b>-topk8</b>, outputs an unencrypted PKCS#8 private key. Otherwise, a passphrase will be prompted.<br><br><b><b>-passin</b> <I>arg</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the source for the input file's passphrase. Can be 'pass:<i>password</i>', 'env:<i>varname</i>', 'file:<i>path</i>', 'fd:<i>number</i>', or 'stdin'.<br><br><b><b>-passout</b> <I>arg</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the source for the output file's passphrase. Similar options to <b>-passin</b>.<br><br><b><b>-iter</b> <I>count</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the iteration count for the key derivation function (KDF) used in PKCS#5 v2.0 encryption. A higher count increases resistance to brute-force attacks.<br><br><b><b>-noiter</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables iteration count, often meaning a single iteration. This is generally less secure and should be avoided for new keys.<br><br><b><b>-v2</b> <I>alg</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the PKCS#5 v2.0 algorithm for encryption. Common values include 'aes128', 'aes192', 'aes256', 'des', 'des3', 'rc2'. This implies using PBKDF2.<br><br><b><b>-v1</b> <I>alg</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the PKCS#5 v1.5 algorithm. Less secure than v2.0 and deprecated for new applications.<br><br><b><b>-engine</b> <I>id</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a cryptographic engine to use for operations, for example, for hardware security modules (HSMs).<br><br><b><b>-traditional</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the key in traditional OpenSSL format (PKCS#1 for RSA/DSA) instead of PKCS#8. This is the default if <b>-topk8</b> is not used.<br><br><b><b>-scrypt</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses the scrypt KDF for PKCS#8 encryption, an alternative to PBKDF2 (which is default with <b>-v2</b>). Offers better resistance to hardware-assisted brute-force attacks.<br><br><b><b>-v2prf</b> <I>digest</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the Pseudorandom Function (PRF) digest for PKCS#5 v2.0 KDF when using PBKDF2. Examples: 'sha1', 'sha256', 'sha512'. Default is often SHA1 or SHA256 depending on the cipher.<br><br><b><b>-v2des</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shorthand for <b>-v2 des</b> (DES-CBC).<br><br><b><b>-v2rc2</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shorthand for <b>-v2 rc2</b> (RC2-CBC).<br><br><b><b>-v2aes128</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shorthand for <b>-v2 aes128</b> (AES-128-CBC).<br><br><b><b>-v2aes192</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shorthand for <b>-v2 aes192</b> (AES-192-CBC).<br><br><b><b>-v2aes256</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shorthand for <b>-v2 aes256</b> (AES-256-CBC).<br><br><b><b>-cipher</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When outputting in traditional format (without <b>-topk8</b> or with <b>-traditional</b>), specifies the cipher to encrypt the key. E.g., <b>-aes256</b>, <b>-des3</b>.<br><br>


title: DESCRIPTION
content:
The <b>pkcs8</b> command, a component of the <I>OpenSSL</I> toolkit, is a versatile utility for processing private keys formatted according to the PKCS#8 standard. PKCS#8 is a secure and standardized method for storing private keys, often encrypted. This command facilitates the conversion of private keys between various formats, including traditional <I>OpenSSL</I> format, DER, and PEM, and the PKCS#8 standard. It also provides robust capabilities for encrypting and decrypting PKCS#8 private keys, enabling users to protect their sensitive cryptographic material with passphrases. It supports a range of ciphers (e.g., AES, DES3) and key derivation functions (KDFs) like PBKDF2 and scrypt, ensuring strong key protection. It's an indispensable tool for secure handling and deployment of cryptographic keys in diverse computing environments.


title: CAVEATS
content:
When converting keys, ensure the input format is correctly specified to avoid errors. <br> Using strong, unique passphrases is crucial for the security of encrypted private keys. <br> The choice of cipher and KDF (e.g., scrypt vs. PBKDF2 with sufficient iterations) significantly impacts the key's resistance to brute-force attacks. <br> Be cautious when using <b>-nocrypt</b> as it leaves the private key unencrypted, which is generally not recommended for storage or transmission.


title: USAGE NOTES
content:
If neither <b>-in</b> nor <b>-out</b> is specified, the command reads from standard input and writes to standard output respectively. <br> When encrypting, if no passphrase is provided via <b>-passout</b>, the user will be interactively prompted to enter and verify a passphrase. <br> For PKCS#8 encrypted keys, PKCS#5 v2.0 is the recommended standard due to its use of modern, customizable KDFs (like PBKDF2 or scrypt) and wider range of strong ciphers. PKCS#5 v1.5 is considered legacy and less secure.


title: EXAMPLES OF USE
content:
<b>1. Convert a traditional RSA key to encrypted PKCS#8:</b><br><I>openssl pkcs8 -topk8 -in rsa_key.pem -out pkcs8_key.pem -v2aes256 -passout pass:MySecurePassphrase</I><br><br><b>2. Convert an encrypted PKCS#8 key to traditional format:</b><br><I>openssl pkcs8 -in pkcs8_key.pem -out rsa_key_trad.pem -passin pass:MySecurePassphrase</I><br><br><b>3. Create an unencrypted PKCS#8 key from a traditional key:</b><br><I>openssl pkcs8 -topk8 -nocrypt -in rsa_key.pem -out pkcs8_nocrypt.pem</I>


title: HISTORY
content:
The <b>pkcs8</b> command is an integral part of the <I>OpenSSL</I> project, which has been under continuous development since 1998. Its functionality has evolved with the <I>OpenSSL</I> library, incorporating support for various cryptographic algorithms, key derivation functions (like scrypt in later versions), and security enhancements over time. Early versions primarily focused on basic PKCS#8 conversions, while later releases added more robust encryption options and KDFs to improve security.


title: SYNOPSIS
content:
<i>pkexec</i> [<b>--user</b> <i>USER</i>] [<b>--keep-environment</b>] [<b>--disable-internal-agent</b>] <i>PROGRAM</i> [<i>ARGUMENTS</i>...]<br><i>pkexec</i> [<b>--version</b> | <b>--help</b>]


title: PARAMETERS
content:
<b><b>--user</b> <i>USER</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Execute the specified <i>PROGRAM</i> as the given <i>USER</i>. If omitted, the default target user is <b>root</b>.<br><br><b><b>--keep-environment</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Retain the original environment variables of the calling user. By default, <i>pkexec</i> cleans the environment for security reasons.<br><br><b><b>--disable-internal-agent</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevent <i>pkexec</i> from using its built-in password authentication agent. This can be useful if an external agent is preferred or required.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the version information of <i>pkexec</i> and exit.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show a help message describing command usage and options, then exit.<br><br>


title: DESCRIPTION
content:
<i>pkexec</i> is a command-line utility designed to execute commands as another user, typically the superuser (root), leveraging the PolicyKit (polkit) authorization framework. Unlike traditional tools like <i>sudo</i> which rely on configuration files (e.g., /etc/sudoers) to define privileges, <i>pkexec</i> defers authorization decisions to the polkit daemon. <br><br> This allows for a more fine-grained and centralized control over system privileges. Policies are defined by action IDs (e.g., <i>org.freedesktop.policykit.exec</i> for executing commands) and can specify who is allowed to perform an action, under what conditions, and if authentication (like a password) is required. When <i>pkexec</i> is invoked, it communicates with the polkit daemon, which evaluates the request against configured policies. If authorization is granted, the specified command is executed with the target user's privileges. <br><br> <i>pkexec</i> is commonly used in graphical environments by desktop applications that need to perform privileged operations, often presenting a graphical password prompt provided by a polkit authentication agent. This makes it a crucial component for secure privilege escalation in modern Linux desktop environments.


title: CAVEATS
content:
<i>pkexec</i> relies entirely on the PolicyKit daemon for authorization. If the polkitd service is not running or properly configured, <i>pkexec</i> will fail to execute commands. <br><br> Policy definitions are complex and typically managed via <i>.policy</i> files in <i>/usr/share/polkit-1/actions/</i> and local overrides in <i>/etc/polkit-1/localauthority/</i>. Misconfigured policies can lead to unintended privilege escalations or deny legitimate operations. <br><br> While generally secure, historical vulnerabilities (e.g., CVE-2021-4034, "PwnKit") in polkit and <i>pkexec</i> have demonstrated the importance of keeping the system updated to patch such critical issues.


title: <B>AUTHORIZATION MODEL</B>
content:
<i>pkexec</i>'s authorization is driven by 'actions' defined in polkit policy files. Each action has an ID (e.g., <i>org.freedesktop.policykit.exec</i> for executing commands) and specifies default authorization rules (e.g., <i>auth_admin_keep</i> requiring administrator authentication). These rules can be overridden by local configuration, allowing system administrators to precisely define who can run what and under what conditions.


title: <B>AUTHENTICATION AGENTS</B>
content:
When an action requires authentication, <i>pkexec</i> attempts to locate an active polkit authentication agent. In graphical environments, this typically presents a dialog box for password entry. If no graphical agent is available, <i>pkexec</i> can fall back to its internal agent for a TTY-based password prompt, unless disabled by <b>--disable-internal-agent</b>.


title: HISTORY
content:
<i>pkexec</i> is an integral part of the PolicyKit (now known as polkit) project, which was initiated by Havoc Pennington at Red Hat around 2008. The goal of polkit was to provide a centralized, standardized, and secure way for non-privileged applications to interact with privileged system services, especially in desktop environments. It aimed to address limitations of traditional <i>sudo</i> setups for graphical applications and provide more granular control over permissions. <i>pkexec</i> was developed as the command-line client for this framework, allowing direct execution of commands subject to polkit policies, evolving with the polkit framework itself over the years.


title: SYNOPSIS
content:
<b>pkey</b> [<i>options</i>]<br><i>(Note: On most systems, this functionality is provided by `openssl pkey`.)</i>


title: PARAMETERS
content:
<b><b>-in</b> <i>file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the input file from which to read the public key. If omitted, standard input is used.<br><br><b><b>-out</b> <i>file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output file to which the processed public key will be written. If omitted, standard output is used.<br><br><b><b>-pubin</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Indicates that the input file is a public key. If not specified, the input is assumed to be a private key from which the public key will be extracted.<br><br><b><b>-pubout</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the public key. This is usually the default behavior for `pkey` operations that don't involve private key handling.<br><br><b><b>-text</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the public key in a human-readable, decoded format, which can be useful for debugging and inspection.<br><br><b><b>-noout</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents the output of the encoded public key. Useful when only checking the key or displaying text output.<br><br><b><b>-inform</b> <i>format</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the input format of the key. Common formats include <i>PEM</i> (default) and <i>DER</i>.<br><br><b><b>-outform</b> <i>format</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output format of the key. Common formats include <i>PEM</i> (default) and <i>DER</i>.<br><br><b><b>-passin</b> <i>arg</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides the passphrase for an encrypted input key file.<br><br><b><b>-check</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a consistency check on the public key structure.<br><br>


title: DESCRIPTION
content:
The `pkey` utility, often invoked as a subcommand of the `openssl` toolkit (i.e., `openssl pkey`), is a versatile tool for handling cryptographic public keys. While not a standalone command on most standard Linux distributions, its functionality is integral to public key infrastructure (PKI) operations. It allows users to extract public keys from various sources (like private key files or X.509 certificates), convert them between different formats (e.g., PEM, DER, PKCS#8), and examine their properties. This command is crucial for tasks such as verifying digital signatures, encrypting data for a specific recipient, and exporting public components for secure communication protocols like TLS/SSL and SSH. It supports a wide range of asymmetric algorithms including RSA, DSA, EC (Elliptic Curve), and X25519. The reference `pkey.1s` likely points to a man page or documentation related to public key handling, conceptually aligning with `openssl-pkey(1)`.


title: CAVEATS
content:
The command `pkey` is primarily a subcommand of the `openssl` utility (`openssl pkey`) rather than a standalone executable on most standard Linux distributions. The `.1s` suffix typically indicates a man page section, but `1s` is a non-standard extension; the relevant manual page is usually `openssl-pkey(1)`. Users should be aware that direct invocation as `pkey` may not work without aliases or symlinks. Furthermore, incorrect usage, especially when handling private keys or sensitive cryptographic material, can lead to significant security risks.


title: SUPPORTED KEY FORMATS
content:
The command typically supports key formats like <i>PEM</i> (Privacy-Enhanced Mail, a Base64-encoded ASCII format) and <i>DER</i> (Distinguished Encoding Rules, a binary format). PEM is commonly used for human-readable key files, while DER is often used in binary contexts or for specific protocols.


title: SUPPORTED CRYPTOGRAPHIC ALGORITHMS
content:
The `pkey` command is designed to work with a variety of asymmetric cryptographic algorithms, including but not limited to <i>RSA</i> (Rivest–Shamir–Adleman), <i>DSA</i> (Digital Signature Algorithm), <i>EC</i> (Elliptic Curve Cryptography), and <i>X25519</i>. This broad support makes it a versatile tool for different cryptographic needs.


title: HISTORY
content:
The functionality now encapsulated by `pkey` within the `openssl` toolkit has evolved over decades. OpenSSL itself originated from the SSLeay project in the late 1990s, aiming to provide a robust open-source implementation of SSL/TLS and cryptographic functions. Initially, key-specific operations were handled by individual commands like `rsa` or `dsa`. As cryptographic algorithms diversified and the need for a unified approach to key management grew, `pkey` emerged as a generic interface for handling various types of public keys. This consolidation allowed for a more consistent and flexible way to manage, inspect, and convert public key formats across different asymmetric algorithms, reflecting the continuous development and standardization efforts in cryptography.


title: PARAMETERS
content:
<b><I>input_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the file containing the public key parameters or a public key from which parameters can be extracted. If omitted, input is read from standard input (stdin).<br><br><b>--in <I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the input file from which to read the public key parameters. This option can be used as an alternative to providing the file as a positional argument.<br><br><b>--inform <I>FORMAT</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the input format of the key file. Common formats include <b>PEM</b> (Privacy-Enhanced Mail, default) and <b>DER</b> (Distinguished Encoding Rules). PEM is a base64-encoded ASCII format, while DER is a binary format.<br><br><b>--dump</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the parameters in hexadecimal format, useful for low-level debugging or direct analysis of the encoded data.<br><br><b>--noout</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents the command from printing the encoded key or parameter data itself, focusing solely on the extracted parameters if other display options are used.<br><br><b>--text</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the parameters in a human-readable text format, typically showing the cryptographic values (p, g, q, etc.) in decimal or hexadecimal representation. This is often the default output style.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief usage message and exits.<br><br>


title: DESCRIPTION
content:
The <I>pkeyparam</I> command (often found as <I>pki_pkeyparam</I> in various PKI toolsets) is a utility designed to inspect and display the cryptographic parameters associated with a public key. These parameters are crucial for asymmetric cryptographic algorithms such as Diffie-Hellman (DH) and Digital Signature Algorithm (DSA), where a set of shared parameters (e.g., a prime modulus, a generator, and optionally a subprime) are used to derive individual public and private keys. The command typically reads the key or parameter set from a specified file, which can be in various standard formats like PEM or DER. It then parses the cryptographic structure to extract and present the relevant parameters, such as the prime 'p', generator 'g', and optionally a subprime 'q' for DSA. This tool is invaluable for verifying key parameters, debugging cryptographic operations, or ensuring compatibility between different cryptographic systems that rely on shared parameter sets.


title: CAVEATS
content:
The <I>pkeyparam</I> command, as referred by <I>pkeyparam.1s</I>, is not a standard GNU Core Utilities command. It is most commonly found as <I>pki_pkeyparam</I> within specific PKI (Public Key Infrastructure) toolsets, such as those provided by Dogtag PKI or other specialized security frameworks on Linux distributions like Fedora, CentOS, or RHEL. Its availability depends on the installation of such specialized security packages. Users on other systems might need to look for equivalent functionality in general-purpose cryptographic tools like <I>openssl</I> (e.g., <I>openssl dhparam</I> or <I>openssl dsaparam</I> for generating or examining parameters) or other cryptographic libraries.


title: SUPPORTED KEY PARAMETER TYPES
content:
The <I>pkeyparam</I> command is primarily designed to handle parameters for algorithms like Diffie-Hellman (DH) and Digital Signature Algorithm (DSA). These algorithms require a set of shared public parameters (e.g., prime modulus 'p', generator 'g', and for DSA, an optional subprime 'q') that are used by all parties to derive their individual public/private key pairs. The command helps in verifying that these parameters are correctly configured and shared across cryptographic systems.


title: INPUT FILE FORMATS
content:
The command typically accepts key parameter files in common cryptographic formats such as <b>PEM</b> (Privacy-Enhanced Mail) and <b>DER</b> (Distinguished Encoding Rules). PEM is a base64-encoded ASCII format, often human-readable and enclosed by '-----BEGIN ...-----' and '-----END ...-----' markers. DER is a binary format that represents the same data in a more compact, machine-readable form. The <I>--inform</I> option allows specifying the format if it cannot be automatically detected, though the command often attempts to auto-detect.


title: HISTORY
content:
The functionality to display public key parameters has been a core component of cryptographic toolkits for decades, stemming from the need to manage and verify shared parameters for algorithms like Diffie-Hellman and DSA. The specific <I>pkeyparam</I> (or more commonly, <I>pki_pkeyparam</I>) command emerged as part of dedicated Public Key Infrastructure (PKI) management suites, particularly those developed to support enterprise-level certificate authority and identity management systems. Its development parallels the growth of robust PKI solutions, providing a specialized utility distinct from the broader key management functions offered by general-purpose tools like OpenSSL.


title: SYNOPSIS
content:
<b>openssl pkeyutl</b> <br> [-<i>in</i> <I>file</I>] [-<i>out</i> <I>file</I>] [-<i>inkey</i> <I>file</I>] [-<i>pubin</i>] [-<i>certin</i>] [-<i>encrypt</i>] [-<i>decrypt</i>] [-<i>sign</i>] [-<i>verify</i>] [-<i>verifyrecover</i>] [-<i>hexdump</i>] [-<i>asn1parse</i>] [-<i>pkeyopt</i> <I>opt:value</I>] [-<i>passin</i> <I>arg</I>] [-<i>engine</i> <I>id</I>]


title: PARAMETERS
content:
<b>-in <I>file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the input file for data to be processed. If not specified, standard input is used.<br><br><b>-out <I>file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output file for the result of the operation. If not specified, standard output is used.<br><br><b>-inkey <I>file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the input key file. This can be a private key or a public key, depending on the operation.<br><br><b>-pubin</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Indicates that the input key specified by -inkey is a public key.<br><br><b>-certin</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Indicates that the input key specified by -inkey is an X.509 certificate containing the public key.<br><br><b>-encrypt</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs public key encryption using the provided key.<br><br><b>-decrypt</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs public key decryption using the provided key.<br><br><b>-sign</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Computes a digital signature of the input data using the private key.<br><br><b>-verify</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Verifies a digital signature. Requires the original data (or its hash) and the signature file via -sigfile.<br><br><b>-verifyrecover</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Verifies the signature and attempts to recover the signed data (primarily for RSA). Note: This is an unusual operation for modern crypto.<br><br><b>-hexdump</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Dumps the output data in hexadecimal format to standard output.<br><br><b>-asn1parse</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempts to ASN.1 parse the output data. Useful for debugging structured outputs.<br><br><b>-pkeyopt <I>opt:value</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets public key algorithm-specific options, such as padding mode (e.g., rsa_padding_mode:oaep, rsa_padding_mode:pss) or digest algorithm (e.g., digest:sha256).<br><br><b>-passin <I>arg</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the source of the private key password. Can be 'pass:password', 'env:varname', 'file:path', 'fd:num', or 'stdin'.<br><br><b>-engine <I>id</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an OpenSSL engine to use for cryptographic operations, offloading them to hardware or specific libraries.<br><br>


