# CommandSection

title: RESOURCE PROTECTION
content:
Pulumi allows users to mark resources as 'protected' in their program using resource options. This mechanism prevents accidental deletion of critical infrastructure. If a protected resource is part of a <i>destroy</i> operation, Pulumi will halt unless the <b>--force</b> flag is explicitly used. Conversely, the <b>--exclude-protected</b> flag can be used to ensure protected resources are never touched during a destroy.


title: HISTORY
content:
Pulumi, Inc. was founded in 2017, introducing its open-source Infrastructure as Code (IaC) framework in 2018. From its inception, the <i>pulumi destroy</i> command has been a fundamental component of the Pulumi CLI, reflecting the complete lifecycle management philosophy for cloud infrastructure. It was designed to provide a safe and controlled way to decommission resources, building upon the declarative principles established by other IaC tools but extending them with general-purpose programming languages. Its development has focused on robustness, preview capabilities, and providing clear user prompts to prevent accidental deletions, evolving with features like resource protection and targeted destruction to enhance user control and safety.


title: SEE ALSO
content:
pulumi up, pulumi preview, pulumi refresh, pulumi state, pulumi stack rm, terraform destroy (conceptual)


title: PARAMETERS
content:
<b><b>--stack</b> <i><name></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the stack to operate on. If omitted, the currently selected stack is used.<br><br><b><b>--yes</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skip prompt for confirmation and proceed directly with resource destruction. Use with caution.<br><br><b><b>--target</b> <i><URN></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Target a specific resource (by its URN) for destruction. Can be specified multiple times to target multiple resources. Only these resources and their dependencies will be affected.<br><br><b><b>--target-dependents</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Destroy dependents of targeted resources as well, in addition to the targeted resources themselves.<br><br><b><b>--message</b> <i><message></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An optional message to associate with the destruction operation, recorded in the stack history.<br><br><b><b>--non-interactive</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable interactive prompts, useful for automated scripts or CI/CD pipelines.<br><br><b><b>--skip-preview</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skip the preview step and directly attempt to destroy resources after confirmation (or with <b>--yes</b>).<br><br><b><b>--parallel</b> <i><number></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allow N resource operations (creates, updates, deletes) to run in parallel. Defaults to a reasonable number.<br><br><b><b>--color</b> <i><mode></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Control colored output. Options include <i>always</i>, <i>never</i>, <i>auto</i>.<br><br><b><b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose debug logging output.<br><br>


title: DESCRIPTION
content:
The <b>pulumi down</b> command is used to permanently destroy all resources provisioned by a specific Pulumi stack. It is an essential part of the infrastructure lifecycle management, enabling users to deprovision cloud resources, clean up environments, and reduce cloud costs. Before executing the destruction, <b>pulumi down</b> performs a preview, showing which resources will be deleted and prompting for user confirmation by default. This crucial safety mechanism helps prevent accidental data loss or infrastructure teardown. Pulumi intelligently determines the correct order of resource destruction based on their dependencies, ensuring a clean and complete deprovisioning. Users must have appropriate cloud provider permissions for resource deletion. Once completed, the resources are irrevocably removed from the cloud provider.


title: CAVEATS
content:
<ul><li><i>Irreversible Operation</i>: <b>pulumi down</b> permanently deletes cloud resources. This action cannot be undone. Always review the preview carefully.</li><li><i>State Management</i>: The command relies on the Pulumi state file to know which resources to destroy. If the state is out of sync with the actual cloud resources, unintended results or orphaned resources may occur.</li><li><i>IAM Permissions</i>: The executing user or service principal must possess the necessary Identity and Access Management (IAM) permissions within the cloud provider to delete all targeted resources.</li><li><i>External Modifications</i>: If resources managed by Pulumi have been modified or deleted outside of Pulumi, the <b>down</b> operation might fail or leave resources behind. A <b>pulumi refresh</b> beforehand can help reconcile the state.</li></ul>


title: CONFIRMATION PROMPT
content:
By default, <b>pulumi down</b> requires explicit confirmation (typing 'yes' at a prompt) before proceeding with the destruction. This is a vital safety mechanism designed to prevent accidental deletion of critical infrastructure. The <b>--yes</b> flag can be used to bypass this prompt, but it should be used with extreme caution, especially in production environments.


title: RESOURCE DEPENDENCIES
content:
Pulumi's engine intelligently analyzes the dependencies between resources defined in your program. When executing <b>pulumi down</b>, it determines the correct order to tear down resources, ensuring that dependent resources are removed before their dependencies. This prevents errors that could arise from trying to delete resources that are still in use.


title: HISTORY
content:
<b>Pulumi</b>, as an Infrastructure as Code (IaC) platform, was publicly launched in 2018, aiming to bring familiar programming languages and tools to cloud infrastructure management. The <b>down</b> command, often synonymous with <b>destroy</b>, has been a core and fundamental part of the Pulumi CLI since its earliest versions. It addresses the critical need for a controlled and auditable process to deprovision and clean up cloud resources, complementing the deployment (<b>up</b>) and preview workflows. Its design emphasizes safety, with mandatory confirmation prompts and intelligent dependency resolution, reflecting best practices in cloud resource lifecycle management.


title: PARAMETERS
content:
<b>install <version></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Installs a specified version of the Pulumi CLI. Versions are typically fetched from Pulumi's official release channels.<br><br><b>use <version></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the specified Pulumi CLI version for the current shell session. This allows temporary switching without affecting other shells or projects.<br><br><b>global <version></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the specified Pulumi CLI version as the default for all shells. This version will be used unless overridden by a local or session-specific setting.<br><br><b>local <version></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the specified Pulumi CLI version for the current directory and its subdirectories. This is useful for project-specific versioning, managed by a <i>.pulumi-version</i> file.<br><br><b>versions</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all installed Pulumi CLI versions on the system, indicating the currently active, global, and local versions.<br><br><b>uninstall <version></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes a specified installed version of the Pulumi CLI from the system.<br><br><b>rehash</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Rebuilds the Pulumi shims (executables) to reflect changes in installed versions. This command is often needed after installing or uninstalling versions.<br><br><b>init</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Initializes <i>pulumi-env</i> for the current shell. This typically involves setting up environment variables and shell functions for proper operation.<br><br><b>help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information and a list of available commands.<br><br>


title: DESCRIPTION
content:
<i>pulumi-env</i> is a community-driven command-line tool designed to manage multiple versions of the <B>Pulumi CLI</B> on a single system. Modeled after popular version managers like <I>pyenv</I> for Python or <I>nvm</I> for Node.js, it provides a convenient way to install, switch, and manage different Pulumi CLI versions without conflicts. This is particularly useful for developers working on projects that require specific Pulumi versions, or for testing compatibility across different versions. It helps ensure consistent development environments and simplifies the process of upgrading or downgrading the Pulumi CLI.


title: CAVEATS
content:
<i>pulumi-env</i> is a community-maintained tool and is not officially supported by Pulumi Inc. Its functionality depends on the continued availability and structure of Pulumi's public CLI release channels. Proper installation requires manual setup of shell environment variables (e.g., modifying <B>PATH</B>) to ensure its shims are prioritized over system-wide Pulumi installations.


title: DISTINCTION FROM PULUMI STACKS
content:
It's important to distinguish <i>pulumi-env</i> from Pulumi's concept of <B>stacks</B>. While Pulumi stacks represent isolated environments for your infrastructure deployments (e.g., 'dev', 'staging', 'prod'), <i>pulumi-env</i> focuses solely on managing the <I>version of the Pulumi CLI executable itself</I>. It does not manage your infrastructure deployments or their configurations.


title: INSTALLATION AND SETUP
content:
Installation typically involves cloning the <i>pulumi-env</i> Git repository and adding its <B>bin</B> directory to your shell's <B>PATH</B> environment variable, usually through your shell's configuration file (e.g., <I>.bashrc</I>, <I>.zshrc</I>). The <B>init</B> command helps automate parts of this setup.


title: HISTORY
content:
<i>pulumi-env</i> emerged from the need within the Pulumi community for a robust and standardized way to manage different versions of the Pulumi CLI. Prior to tools like <i>pulumi-env</i>, managing multiple Pulumi versions often involved manual downloads, PATH manipulation, or containerization, which could be cumbersome. It was developed to provide a familiar and convenient <I>'-env'</I> style version management experience, mirroring successful patterns seen in other language ecosystems.


title: PARAMETERS
content:
<b><I>shell_name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target shell for which to generate completion scripts. Valid values typically include <b>bash</b>, <b>zsh</b>, <b>fish</b>, and <b>powershell</b>.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the command, detailing its usage and available options.<br><br>


title: DESCRIPTION
content:
The <b>pulumi-gen-completion</b> command, conceptually referencing the functionality provided by <i>pulumi completion</i> (or <i>pulumi gen completion</i> in older versions) of the Pulumi CLI, is used to generate shell auto-completion scripts. These scripts enable tab-completion for Pulumi commands, options, and arguments within various shell environments.<br><br>When executed, the command outputs the completion script to standard output, which users typically redirect to a file in an appropriate system or user-specific directory (e.g., <i>/etc/bash_completion.d/</i> for Bash, or <i>~/.zsh/completion/</i> for Zsh). This feature significantly enhances productivity by reducing typing and potential errors when interacting with the Pulumi command-line interface.


title: CAVEATS
content:
For the generated shell completion to function correctly, the output file containing the completion script must be <i>sourced</i> by your shell. This commonly involves adding a specific line to your shell's configuration file (e.g., <i>~/.bashrc</i>, <i>~/.zshrc</i>, <i>~/.config/fish/config.fish</i>, or <i>$PROFILE</i> for PowerShell).<br><br>The exact location where completion files should be placed and how they are sourced can vary significantly between different shell versions and operating systems.<br><br>This command inherently requires the Pulumi CLI to be installed and accessible in your system's PATH.


title: COMMON USAGE EXAMPLES
content:
Here are typical ways to generate and enable Pulumi shell completions for various shells:<br><br><b>Bash:</b><br><I># Generate and save the completion script</I><br>pulumi-gen-completion bash > /etc/bash_completion.d/pulumi.sh<br><I># Then, ensure it's sourced in your ~/.bashrc or ~/.profile</I><br>source /etc/bash_completion.d/pulumi.sh<br><br><b>Zsh:</b><br><I># Create a completion directory if it doesn't exist</I><br>mkdir -p ~/.zsh/completion<br><I># Generate and save the completion script</I><br>pulumi-gen-completion zsh > ~/.zsh/completion/_pulumi<br><I># Then, add the following to your ~/.zshrc</I><br>fpath=(~/.zsh/completion $fpath)<br>autoload -Uz compinit && compinit<br><br><b>Fish:</b><br><I># Generate and save the completion script</I><br>pulumi-gen-completion fish > ~/.config/fish/completions/pulumi.fish<br><I>(Fish automatically loads completion files from this directory)</I><br><br><b>PowerShell:</b><br><I># Generate and append the completion script to your PowerShell profile</I><br>pulumi-gen-completion powershell | Out-File -FilePath $PROFILE -Append


title: HISTORY
content:
The ability to generate shell completions has been an integral part of the Pulumi CLI since its early versions, initially often accessible via <i>pulumi gen completion</i> and later streamlined to <i>pulumi completion</i>. This feature was developed to improve the user experience by providing an interactive and efficient way to interact with the Pulumi command-line tools, reflecting a common trend in modern developer tooling for enhanced usability and productivity.


title: SYNOPSIS
content:
<i>curl -fsSL https://get.pulumi.com | sh -s -- [OPTIONS]</i><br><i>wget -qO- https://get.pulumi.com | sh -s -- [OPTIONS]</i>


title: PARAMETERS
content:
<b><b>--version &lt;VERSION&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a particular version of the Pulumi CLI to install (e.g., <i>v3.x.x</i>). If omitted, the latest stable version is installed by default.<br><br><b><b>--install-dir &lt;PATH&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the target directory where the Pulumi CLI binaries will be placed. The default location is typically <i>~/.pulumi</i>.<br><br><b><b>--no-modify-path</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents the installation script from automatically attempting to modify your shell's profile configuration file (e.g., <i>.bashrc</i>, <i>.zshrc</i>) to add the Pulumi binary to your system's PATH environment variable.<br><br><b><b>--yes</b><br>or <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs the installation process non-interactively, bypassing any prompts for user confirmation during execution.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays usage information and a list of available command-line options for the installation script.<br><br>


title: DESCRIPTION
content:
The <b>pulumi-install</b> utility, typically invoked by piping a shell script from get.pulumi.com into `sh`, automates the entire installation process for the Pulumi Command Line Interface (CLI) on Linux systems. This script handles downloading the correct Pulumi binary tailored to your system's architecture, extracting it, and placing it in a designated installation directory. A key feature is its default attempt to modify your shell's PATH environment variable, ensuring the <b>pulumi</b> command becomes immediately accessible from any terminal session. This streamlined approach significantly simplifies setup, removing the need for manual downloads, extractions, or complex, distribution-specific package management steps, making it ideal for quick developer onboarding.


title: CAVEATS
content:
Internet connectivity is mandatory for the script to download both itself and the Pulumi CLI binaries.<br>By default, the script modifies your shell's configuration file (e.g., <i>.bashrc</i>, <i>.zshrc</i>). Users may need to restart their shell or manually source the configuration file for the PATH changes to take effect.<br>If the specified installation directory is a system-wide path (e.g., <i>/usr/local/bin</i>), root privileges (via <i>sudo</i>) will likely be required.<br>The script relies on common Linux utilities such as <i>curl</i> or <i>wget</i> for downloading, <i>sh</i> (or <i>bash</i>/<i>zsh</i>) for execution, and <i>unzip</i>/<i>tar</i> for archive extraction.


title: USAGE NOTES
content:
The command is typically executed by piping the output of <i>curl</i> or <i>wget</i> directly into a shell interpreter (<i>sh</i>). This allows the installation script to run immediately after being downloaded, streamlining the entire installation process.<br>After a successful installation, you should generally run <i>pulumi login</i> to configure your Pulumi backend and authenticate your CLI.


title: HISTORY
content:
The <b>pulumi-install</b> script is a foundational component of the Pulumi ecosystem, specifically engineered to deliver a consistent and user-friendly installation experience for the Pulumi CLI across various Linux distributions. Its development underscores Pulumi's commitment to simplifying developer onboarding and ensuring quick access to its infrastructure-as-code capabilities, by abstracting away the complexities of manual binary management or reliance on specific operating system package managers.


title: PARAMETERS
content:
<b><i>url</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The URL of the Pulumi Cloud, a self-hosted Pulumi service, or a local filesystem path. If omitted, it defaults to the Pulumi Cloud (https://api.pulumi.com).<br><br><b><b>--cloud-url</b> <i>&lt;url&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a URL to log in to a particular Pulumi Cloud instance or self-hosted Pulumi service. This flag is an alternative to providing the URL as a positional argument.<br><br><b><b>--cloud-url-insecure</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables SSL certificate validation when logging into the Pulumi Cloud or a self-hosted Pulumi service. <i>Use with extreme caution, as it makes your connection vulnerable to man-in-the-middle attacks.</i><br><br><b><b>--local-state</b> <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Designates a local directory path to use for storing Pulumi state files. This flag allows state to be managed entirely on your local machine without a remote backend.<br><br><b><b>--login-secrets-provider</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the type of secrets provider to use for encrypting and decrypting secrets. Supported values include 'default', 'aws', 'azure', 'gcp', 'hashicorp', or 'passphrase'. Defaults to 'default'.<br><br><b><b>--non-interactive</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses interactive prompting during the login process, useful for automation scripts and CI/CD environments. Requires a <b>--token</b> for authentication when used with remote backends.<br><br><b><b>--organization</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the Pulumi organization to log into. This is relevant for managing access and resources within a specific organizational context in the Pulumi Cloud.<br><br><b><b>--save-url</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Persists the provided URL as the default backend for all future Pulumi commands, eliminating the need to specify it repeatedly.<br><br><b><b>--token</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides a Pulumi access token for authentication, primarily used in non-interactive scenarios or for logging in with specific credentials without a browser prompt.<br><br><b><b>--team</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the team within an organization to log into. This helps scope access and operations to specific teams.<br><br>


title: DESCRIPTION
content:
The <b>pulumi login</b> command establishes a connection between your Pulumi CLI and a specified backend service. This backend is crucial for storing your Pulumi program's state, managing secrets, and enabling collaboration on infrastructure projects. It supports logging into the official <i>Pulumi Cloud</i> (the default if no URL is specified), a <i>self-hosted Pulumi service</i>, or even a <i>local filesystem path</i> for state management.<br><br>Upon successful login, the CLI is configured to use the specified backend for all subsequent Pulumi commands, such as <b>pulumi up</b>, <b>pulumi destroy</b>, and <b>pulumi stack</b>. This command handles the authentication process, which might involve interactive browser-based authentication for the Pulumi Cloud or using an access token for automated environments.


title: CAVEATS
content:
The <b>--service-url</b> flag is deprecated; use <b>--cloud-url</b> instead. Using <b>--cloud-url-insecure</b> is a significant security risk and should be avoided in production environments.<br><br>For non-interactive use (e.g., in CI/CD pipelines), an access token (via <b>--token</b>) is typically required, as browser-based authentication is not possible.


title: DEFAULT LOGIN BEHAVIOR
content:
By default, if no URL is provided, <b>pulumi login</b> attempts to authenticate with the Pulumi Cloud at <i>https://api.pulumi.com</i>. If you're not already logged in, it will typically open a browser window to guide you through the authentication flow.


title: CREDENTIAL STORAGE LOCATION
content:
Upon successful login, your Pulumi credentials (including the access token for the active backend) are securely stored in your home directory, typically at <i>~/.pulumi/credentials.json</i> on Linux systems. This file is protected with appropriate file permissions to safeguard your sensitive information.


title: HISTORY
content:
The <b>pulumi login</b> command has been a fundamental part of the Pulumi CLI since its public release around 2018. As Pulumi gained traction for Infrastructure as Code, the ability to seamlessly connect to various state backends, especially the Pulumi Cloud, became central to its design. The command has evolved to support different authentication methods and backend types, reflecting the growing needs for secure and flexible state management in cloud environments.


title: PARAMETERS
content:
<b>[<url>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b><i>Optional.</i></b> Specifies the URL of the Pulumi backend to log out from. If omitted, the command attempts to log out from the currently active backend.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the <i>logout</i> command.<br><br><b>--all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Logs out from all configured Pulumi backends, removing all cached credentials.<br><br><b>-f, --force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the logout operation to proceed even if the command is not currently logged into the specified or current backend. This prevents an error from being returned in such cases.<br><br><b>--non-interactive</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables interactive prompts during the logout process. This is useful for scripting or automated environments.<br><br><b>--cloud-url <url></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b><i>Deprecated.</i></b> Use the direct URL argument instead. Specifies a different Pulumi Cloud URL to log out from.<br><br>


title: DESCRIPTION
content:
The <i>pulumi logout</i> command is used to terminate an authenticated session with a Pulumi backend. This backend can be the managed Pulumi Cloud (api.pulumi.com) or a self-hosted alternative such as a Git repository, Amazon S3 bucket, Azure Blob Storage, or Google Cloud Storage. Executing this command removes the locally cached access tokens and session credentials, effectively logging the user out.<br><br>When invoked without any arguments, <i>pulumi logout</i> attempts to log out from the currently active backend, which is typically the one the user last logged into or specified for a project. To log out from a specific backend URL, the URL can be provided as an argument. Alternatively, the <i>--all</i> option allows users to log out from all configured backends simultaneously, removing all stored credentials. This command is crucial for security, enabling users to clear their session information from a machine, particularly before leaving a shared or public environment. It ensures that subsequent Pulumi CLI operations will require re-authentication.


title: CAVEATS
content:
<ul><li>If no URL is provided, <i>pulumi logout</i> targets the <b>currently active</b> backend, which might not be the one you intend if you have multiple backends configured.</li><li>The <i>--cloud-url</i> option is deprecated and its use is discouraged in favor of passing the backend URL directly as an argument.</li><li>Logging out using <i>pulumi logout --all</i> will remove all locally stored Pulumi access tokens, requiring re-authentication for any Pulumi backend you wish to interact with later.</li><li>This command only removes credentials stored locally by the Pulumi CLI; it does not invalidate any tokens on the Pulumi backend service itself (e.g., if you generated an API token directly).</li></ul>


title: SECURITY IMPLICATIONS
content:
Logging out is a critical security practice, especially when using shared machines or public terminals. It ensures that your Pulumi Cloud credentials are not left exposed after use.


title: CREDENTIAL STORAGE
content:
Pulumi typically stores credentials in a secure location on the user's local machine (e.g., the <i>~/.pulumi</i> directory on Linux/macOS, or <i>%USERPROFILE%/.pulumi</i> on Windows). The <i>pulumi logout</i> command cleans up these specific credential files.


title: HISTORY
content:
The <i>pulumi</i> CLI and its core commands like <i>login</i> and <i>logout</i> have been fundamental since the early public releases of Pulumi, starting around 2018. They were designed to provide a secure and manageable way for users to interact with the Pulumi Cloud and other state backends. As Pulumi evolved to support various self-hosted backend options (S3, Azure Blob, GCS, Git), the <i>logout</i> command was adapted to accommodate these diverse environments, allowing users to disconnect from any configured backend. The deprecation of <i>--cloud-url</i> in favor of a direct URL argument reflects an effort to unify and simplify the command's interface for all backend types.


title: PARAMETERS
content:
<b>--stack <stack-name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Operates on a specific Pulumi stack by name. If omitted, the currently selected stack is used.<br><br><b>--target <resource-urn></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a URN (Uniform Resource Name) of a resource to target for the preview. Only changes related to this resource will be shown.<br><br><b>--target-dependents</b><br>&nbsp;&nbsp;&nbsp;&nbsp;If used with <i>--target</i>, also include changes to resources that depend on the specified target resource(s).<br><br><b>--message <message></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Associates a descriptive message with the preview operation, often used for logging or auditing.<br><br><b>--diff</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows full property-level diffs of resource changes, providing a detailed breakdown of what will be modified.<br><br><b>--expect-no-changes</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Causes the command to exit with an error if any changes are proposed during the preview, useful for CI/CD pipelines to ensure idempotency.<br><br><b>--refresh</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Refreshes the state of the stack from the cloud provider before performing the preview, ensuring the most accurate comparison.<br><br><b>--json</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Emits the preview output in JSON format, facilitating programmatic consumption and integration with other tools.<br><br><b>--non-interactive</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables interactive prompts, making the command suitable for automated scripts and CI/CD environments.<br><br><b>--policy-pack <path-or-url></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a policy pack to apply during the preview, allowing early detection of policy violations against your infrastructure plan.<br><br><b>--color <mode></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls colorization of the output. Modes include 'auto', 'always', or 'never'.<br><br><b>--show-replacement-steps</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays detailed steps involved when a resource needs to be replaced, highlighting destructive actions.<br><br>


title: DESCRIPTION
content:
The <i>pulumi-preview</i> command provides a 'dry run' of your Pulumi program, showing exactly what infrastructure changes Pulumi intends to make without actually applying them. It calculates the desired state of your infrastructure based on your code and compares it against the current state of your cloud resources, producing a detailed plan of proposed additions, modifications, and deletions. This command is an essential safety and planning tool, enabling developers and operators to review potential impacts, identify errors early, and ensure that infrastructure updates align with expectations before committing to any deployments. The output typically includes a comprehensive diff, highlighting property-level changes for each resource.


title: CAVEATS
content:
While <i>pulumi-preview</i> provides a robust forecast, it doesn't guarantee a completely successful <i>pulumi up</i>. Runtime issues, transient cloud provider errors, or external service limitations are not always predictable. Furthermore, the preview primarily reflects declarative changes and might not fully capture side effects of custom code within Pulumi programs or external system interactions that occur only during actual deployment.


title: POLICY ENFORCEMENT INTEGRATION
content:
<i>pulumi-preview</i> serves as an early gate for policy enforcement. By integrating with Pulumi Policy as Code, it can automatically run policy checks against your proposed infrastructure changes. This enables you to catch compliance violations, security misconfigurations, or cost inefficiencies before they are deployed, ensuring that your infrastructure adheres to organizational standards from the very beginning of the deployment lifecycle.


title: HISTORY
content:
Pulumi emerged in 2018 as an Infrastructure as Code (IaC) solution, distinguishing itself by enabling infrastructure definition using general-purpose programming languages. From its inception, the <i>pulumi-preview</i> command has been a cornerstone feature, embodying Pulumi's dedication to safe and transparent infrastructure management. It has consistently allowed users to meticulously inspect proposed infrastructure changes before they are committed, significantly reducing deployment risks and enhancing developer confidence.


title: PARAMETERS
content:
<b><b>--stack</b>, <b>-s</b> <i>&lt;STACK_NAME&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the stack to refresh. If omitted, the currently selected stack is used.<br><br><b><b>--message</b>, <b>-m</b> <i>&lt;MESSAGE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A message to associate with the refresh operation in the history.<br><br><b><b>--target</b> <i>&lt;URN&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a URN (Uniform Resource Name) of a resource to refresh. Only this resource will be checked for drift. Can be specified multiple times.<br><br><b><b>--target-dependents</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Refresh dependents of a <b>--target</b> resource as well. Use with <b>--target</b>.<br><br><b><b>--skip-preview</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skip the refresh preview and proceed directly to applying the state changes without confirmation.<br><br><b><b>--non-interactive</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable interactive prompts, useful for automation and scripting.<br><br><b><b>--config</b> <i>&lt;KEY=VALUE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set a configuration value for the refresh, overriding stack config values.<br><br><b><b>--config-file</b> <i>&lt;PATH&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use a specific configuration file instead of the default 'Pulumi.<stack-name>.yaml'.<br><br><b><b>--json</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Emit output as JSON. Useful for programmatic consumption of refresh results.<br><br><b><b>--color</b> <i>&lt;auto|always|never&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Customize output colorization for the console.<br><br><b><b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable debug logging, providing more verbose output for troubleshooting.<br><br><b><b>--logtostderr</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force logging to stderr instead of files.<br><br><b><b>--tracing</b> <i>&lt;ENDPOINT&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable OpenTracing for detailed performance analysis.<br><br>


title: DESCRIPTION
content:
<b>pulumi refresh</b> is a command within the Pulumi Infrastructure as Code (IaC) framework designed to synchronize the Pulumi state file with the actual deployed cloud resources. Unlike <b>pulumi up</b>, which applies changes from your code to the cloud, <b>pulumi refresh</b> inspects the live cloud environment and updates Pulumi's internal state to accurately reflect any changes that may have occurred outside of Pulumi's management.<br><br>This process is crucial for detecting and rectifying "drift," where the actual infrastructure diverges from the expected state defined in your Pulumi program. The command performs a dry run by querying the current status of all resources managed by the stack. If it finds resources that have been manually modified, deleted, or added out-of-band, it will update the state file accordingly.<br><br>For example, if a resource was deleted directly in the cloud console, <b>pulumi refresh</b> will remove that resource from the Pulumi state, effectively "forgetting" about it. If a resource's properties were changed manually, <b>refresh</b> will update the state to reflect these new properties. It's an essential tool for maintaining the integrity of your Pulumi state, ensuring that subsequent <b>pulumi up</b> operations start from a correct understanding of the existing infrastructure, preventing unintended destructive actions or misleading previews.


title: CAVEATS
content:
While <b>pulumi refresh</b> itself does not modify cloud resources, it <i>does</i> modify the Pulumi state file. This modification can be significant: if resources have been deleted out-of-band, <b>refresh</b> will remove them from the state, meaning Pulumi will no longer manage them. If properties were changed externally, the state will be updated to reflect those changes, which could lead to unexpected behavior if subsequent <b>pulumi up</b> operations are run without understanding these state shifts. Always review the refresh plan carefully before confirming, especially in production environments, to ensure the proposed state changes align with your expectations.


title: DRIFT DETECTION
content:
<b>pulumi refresh</b> is the primary mechanism for detecting 'drift' in your infrastructure. Drift occurs when the actual state of your cloud resources deviates from the state recorded in your Pulumi program and state file. Running <b>refresh</b> regularly can help identify and resolve these discrepancies before they cause issues with subsequent deployments or system behavior, maintaining the integrity of your IaC pipeline.


title: IMPACT ON SUBSEQUENT DEPLOYMENTS
content:
After a successful <b>pulumi refresh</b>, subsequent <b>pulumi up</b> commands will operate on the updated state. If <b>refresh</b> removed resources from the state (e.g., they were deleted manually from the cloud), <b>pulumi up</b> will no longer attempt to manage or recreate them. If properties were updated, <b>pulumi up</b> might then attempt to correct them back to the desired state in your code (if the code specifies that property), or simply acknowledge the change if the code is flexible.


title: HISTORY
content:
Pulumi, launched in 2018, revolutionized Infrastructure as Code by enabling developers to define cloud infrastructure using general-purpose programming languages (like TypeScript, Python, Go, C#, Java, YAML). The <b>pulumi refresh</b> command was an integral part of the CLI from early stages, addressing the critical need for state synchronization in dynamic cloud environments. Its development reflects Pulumi's commitment to providing robust tools for managing infrastructure drift and maintaining a single source of truth for cloud resources, evolving alongside the core Pulumi engine to support new cloud providers and resource types. It ensures that the declared intent in code remains aligned with the actual deployed cloud infrastructure.


title: SYNOPSIS
content:
<b>pulumi stack</b> <i>[command] [options]</i><br><br>Common <b>pulumi stack</b> commands:<br><br><b>init</b> <i>[name]</i> [--secrets-provider=<i>type</i>]<br><b>select</b> <i>[name]</i> [--create]<br><b>ls</b> [--all] [--json]<br><b>rm</b> <i>[name]</i> [--force] [--yes] [--config-only]<br><b>rename</b> <i>[old-name] [new-name]</i><br><b>tag</b> <i>[add|rm|ls] [key] [value]</i> [--json]<br><b>export</b> [--file=<i>path</i>] [--json]<br><b>import</b> [--file=<i>path</i>] [--force]<br><b>output</b> <i>[name]</i> [--json] [--show-secrets]<br><b>graph</b><br><b>history</b>


title: PARAMETERS
content:
<b>--all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Used with <b>ls</b>) Lists all stacks, including those not associated with the current project.<br><br><b>--create</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Used with <b>select</b>) Creates the stack if it doesn't already exist when selecting it.<br><br><b>--cwd <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs the command in a different directory, useful for multi-project repositories.<br><br><b>--config-only</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Used with <b>rm</b>) Only removes the stack's configuration and encrypted secrets from the project's <i>Pulumi.yaml</i>, not its state from the backend.<br><br><b>--file <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Used with <b>export</b>, <b>import</b>) Specifies the file path for stack state operations.<br><br><b>--force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Used with <b>rm</b>, <b>import</b>) Forces the operation, e.g., removes a stack even if it's not empty, or overwrites an existing state file during import.<br><br><b>--json</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Emits output as JSON, useful for programmatic consumption.<br><br><b>--project <name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Used with <b>ls</b>) Only lists stacks associated with a specific project name.<br><br><b>--secrets-provider <type></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Used with <b>init</b>) The type of secrets provider to use for the new stack (e.g., <i>default</i>, <i>passphrase</i>, <i>awskms</i>, <i>azurekeyvault</i>, <i>gcpkms</i>).<br><br><b>--show-secrets</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Used with <b>output</b>) Displays stack outputs marked as secrets (use with caution).<br><br><b>--stack <name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the stack to operate on. If not specified, the currently selected stack is used.<br><br><b>--yes / -y</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Used with <b>rm</b>) Skips confirmation prompts for destructive operations.<br><br>


title: DESCRIPTION
content:
The <b>pulumi-stack</b> command is a fundamental part of the Pulumi CLI, designed for managing <i>stacks</i>. In Pulumi, a stack represents an isolated, independently configurable instance of your Pulumi program. You typically use different stacks for different deployment environments, such as development, staging, and production. Each stack maintains its own state file, tracking the cloud resources it manages, and has its own configuration values, including secrets.<br><br><b>pulumi-stack</b> provides various subcommands to interact with these stacks. You can initialize new stacks (<i>init</i>), switch between existing ones (<i>select</i>), list all available stacks (<i>ls</i>), or remove them (<i>rm</i>). It also allows for advanced operations like renaming a stack (<i>rename</i>), adding or removing tags (<i>tag</i>), and exporting or importing stack state (<i>export</i>, <i>import</i>). The <b>pulumi-stack</b> command ensures that your deployments are isolated, preventing accidental changes across environments and enabling consistent, repeatable infrastructure provisioning. It's crucial for organizing your cloud infrastructure projects into distinct, manageable deployments.


title: CAVEATS
content:
<ul><li><b>Data Loss Risk:</b> Using <b>pulumi stack rm</b> can lead to permanent data loss if the stack's resources are not first destroyed via <b>pulumi destroy</b>. Using <i>--force</i> with <b>rm</b> will remove the stack even if it manages existing resources, potentially leaving orphaned infrastructure in your cloud account.</li><li><b>State Management:</b> Stacks rely on a backend to store their state. Issues with backend connectivity or permissions can prevent <b>pulumi-stack</b> from operating correctly.</li><li><b>Secrets Handling:</b> Stacks manage encrypted secrets. Ensure your secrets provider is correctly configured and accessible when working with sensitive stack configurations or outputs.</li><li><b>Active Stack:</b> Always be aware of which stack is currently selected (use <b>pulumi stack ls</b> to see the active stack) to avoid unintended operations on the wrong environment.</li></ul>


title: STACK CONCEPT
content:
A Pulumi <i>stack</i> is an isolated instance of your infrastructure program. It manages a distinct set of cloud resources, its own configuration settings (including encrypted secrets), and its own state file, which tracks the deployed resources. This isolation is crucial for managing separate development, staging, and production environments without interference.


title: DEFAULT STACK
content:
When you first initialize a Pulumi project with <b>pulumi new</b>, a default stack (often named <i>dev</i> or derived from the project name) is created and automatically selected. If no stack is explicitly selected for a subsequent Pulumi operation, the CLI will typically default to the currently active stack.


title: SECRETS MANAGEMENT
content:
Each stack is configured with a <i>secrets provider</i> (e.g., passphrase, AWS KMS, Azure Key Vault, Google Cloud KMS). This provider is responsible for encrypting and decrypting sensitive configuration values and stack outputs, ensuring that secrets are not stored in plaintext within the state file, enhancing security.


title: HISTORY
content:
Pulumi was founded in 2017 with a vision to enable developers to define, deploy, and manage cloud infrastructure using familiar programming languages. <i>Stacks</i> are a core concept introduced early in Pulumi's development, providing the necessary isolation and lifecycle management for different deployment environments. The <b>pulumi-stack</b> command set has evolved to offer robust control over these isolated deployments, reflecting the growing needs for infrastructure as code practices that support multiple environments and continuous delivery workflows.


title: SYNOPSIS
content:
<b>pulumi-state</b> <I>subcommand</I> [<I>arguments</I>...] [<I>options</I>]<br><br>Common subcommands include:<br><b>pulumi-state</b> <B>delete</B> <I>&lt;URN&gt;</I> [--force]<br><b>pulumi-state</b> <B>edit</B><br><b>pulumi-state</b> <B>import</B> <I>&lt;type&gt;</I> <I>&lt;name&gt;</I> <I>&lt;ID&gt;</I> [--parent <I>&lt;parent-URN&gt;</I>]<br><b>pulumi-state</b> <B>rename</B> <I>&lt;old-URN&gt;</I> <I>&lt;new-URN&gt;</I><br><b>pulumi-state</b> <B>show</B> [--URN <I>&lt;URN&gt;</I> | --id <I>&lt;ID&gt;</I>] [--json] [--plain]


title: PARAMETERS
content:
<b><b>&lt;subcommand&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The specific action to perform on the state file. Common subcommands include <I>delete</I>, <I>edit</I>, <I>import</I>, <I>rename</I>, and <I>show</I>.<br><br><b><b>--stack</b> &lt;name&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the stack to operate on. If omitted, the currently selected stack is used. This is a global Pulumi option applicable to state commands.<br><br><b><b>--json</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Emit output as JSON, suitable for programmatic consumption. Available for many subcommands, e.g., <I>show</I>.<br><br><b><b>--non-interactive</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable interactive prompts, useful for automation scripts where no user input is desired.<br><br><b><b>delete</b> <b>&lt;URN&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remove a specific resource from the state file by its Uniform Resource Name (URN). This operation does <B>not</B> delete the actual cloud resource; it only removes Pulumi's tracking of it.<br><br><b><b>delete --force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with the <B>delete</B> subcommand to skip confirmation prompts, allowing for non-interactive removal of resources from the state.<br><br><b><b>import</b> <b>&lt;type&gt; &lt;name&gt; &lt;ID&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Integrate an existing cloud resource into the Pulumi state file. This requires specifying the Pulumi resource type (e.g., <I>aws:s3/bucket:Bucket</I>), a logical name for the resource within your program, and its physical ID in the cloud provider.<br><br><b><b>show</b> <b>[--URN &lt;URN&gt; | --id &lt;ID&gt;]</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the detailed contents of the Pulumi state file. Can be used to view the entire state, or filtered to show details for a specific resource using its URN or its physical cloud ID.<br><br><b><b>edit</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Open the state file in an interactive text editor (typically <I>vi</I>, <I>nano</I>, or the editor defined by your <I>EDITOR</I> environment variable) for manual modification. Use with <B>extreme caution</B> as incorrect edits can corrupt the state.<br><br>


title: DESCRIPTION
content:
The <I>pulumi-state</I> command is a crucial part of the Pulumi infrastructure-as-code (IaC) ecosystem, designed for managing and interacting with the Pulumi state file. This file acts as the authoritative record of your deployed cloud resources, mapping your desired infrastructure (as defined in your Pulumi program) to the actual resources provisioned in your cloud provider. The command provides a powerful set of subcommands to inspect, modify, and troubleshoot your deployment state.<br><br>It allows users to view resource details, remove resources from the state without affecting the cloud, import existing cloud resources into the state, and even edit the state file directly (with extreme caution). Proper management of the state file is essential for consistent and reliable infrastructure deployments, as it ensures that Pulumi can accurately track and manage your cloud environment, facilitating updates, rollbacks, and diff operations.


title: CAVEATS
content:
Directly editing the Pulumi state file using <I>pulumi-state edit</I> is highly risky and should only be performed by advanced users with extreme caution. Incorrect modifications can corrupt your state, leading to inconsistencies between your Pulumi program and your deployed cloud resources, potentially causing resource loss or unexpected deployments. The <B>delete</B> subcommand removes resources only from the state file, <B>not</B> from your cloud provider; the actual cloud resource will remain. Always ensure you have a backup of your state, especially when performing manual operations. Concurrent manual state edits by multiple users can also lead to state corruption.


title: STATE BACKEND CONFIGURATION
content:
Pulumi state can be stored in various backends, including the Pulumi Service (the default for new projects), local files, or cloud storage solutions like AWS S3, Azure Blob Storage, or Google Cloud Storage. The specific backend used for a stack is configured separately, and <I>pulumi-state</I> commands automatically interact with the currently configured backend for the selected stack.


title: BEST PRACTICES FOR STATE MANAGEMENT
content:
While <I>pulumi-state</I> offers powerful tools for advanced scenarios and troubleshooting, it's generally best practice to manage your infrastructure through your Pulumi program (written in TypeScript, Python, Go, C#, Java, or YAML) and use commands like <I>pulumi up</I>, <I>pulumi refresh</I>, and <I>pulumi destroy</I> for routine operations. Direct manipulation of the state file should be reserved for specific, well-understood advanced operations, and always be done with a clear understanding of the implications and with appropriate backups.


title: HISTORY
content:
The concept of state management has been fundamental to Pulumi since its inception around 2017. As an infrastructure-as-code platform, Pulumi relies on a robust state file to track and manage deployed cloud resources. The <I>pulumi-state</I> command suite was developed as an essential set of utilities to interact with this state file directly. It evolved to provide capabilities for inspecting, debugging, and performing surgical operations on the state, addressing advanced use cases and troubleshooting scenarios that go beyond typical <I>pulumi up</I> or <I>destroy</I> operations. Its importance grew as users needed finer control and visibility into their infrastructure's declared state.


title: PARAMETERS
content:
<b>--stack <name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specify the stack to operate on.</i><br><br><b>--message <string></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Attach an optional message to the update operation for history.</i><br><br><b>--yes</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Automatically approve and skip confirmation prompts. Use with caution.</i><br><br><b>--diff</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Display a full diff of proposed resource changes.</i><br><br><b>--target <urn></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Target a specific resource by URN for update (can be repeated).</i><br><br><b>--replace <urn></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Force replacement of a specific resource by URN (can be repeated).</i><br><br><b>--skip-preview</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Execute without first showing a preview of changes.</i><br><br><b>--expect-no-changes</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Exit with an error if any changes are proposed. Useful for CI/CD pipelines.</i><br><br><b>--policy-pack <path|urn></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Apply one or more policy packs during the update for governance.</i><br><br><b>--parallel <N></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Set the maximum number of parallel resource operations (default is 16).</i><br><br><b>--secrets-provider <type></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specify the secrets encryption provider to use for the stack.</i><br><br><b>--config <key=value></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Set or override a stack configuration value (can be repeated).</i><br><br><b>--show-secrets</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Display secret values in the output.</i><br><br><b>--show-urns</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Display resource URNs in the output.</i><br><br><b>--show-config</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Display the stack's configuration in the output.</i><br><br><b>--show-resource-outputs</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Display resource outputs in the output.</i><br><br><b>--show-stack-outputs</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Display stack outputs in the output.</i><br><br><b>--color <always|never|auto></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Control output coloring (default is 'auto').</i><br><br><b>--debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Enable debug logging.</i><br><br><b>--logtostderr</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Log messages to standard error instead of files.</i><br><br><b>--verbose <number></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Set the verbosity level for logging.</i><br><br>


title: DESCRIPTION
content:
The <b>pulumi-up</b> command is the core operation in Pulumi for deploying and managing cloud infrastructure. When executed, Pulumi analyzes your program (written in languages like TypeScript, Python, Go, C#) to determine the desired state of your cloud resources. It then compares this desired state with the current state of your deployed resources (tracked in the Pulumi state file).<br><br>A "preview" is generated, showing a detailed list of proposed changes (creations, updates, deletions). The user is prompted to confirm these changes before they are applied to the cloud provider. <b>pulumi-up</b> handles the orchestration of these changes, ensuring resources are created/updated in the correct order, managing dependencies, and retrying operations as needed. It's an idempotent operation, meaning running it multiple times with the same program will converge to the same infrastructure state. This command is fundamental for managing the lifecycle of your cloud environments, from initial deployment to ongoing updates and configuration changes.


title: CAVEATS
content:
Using <b>--yes</b> bypasses critical review; it is highly recommended to review the preview before applying changes, especially in production environments.<br>Deletions of resources are destructive and typically irreversible from the cloud provider's side.<br>Direct manipulation of the Pulumi state file is not recommended and can lead to inconsistencies.


title: IDEMPOTENCY
content:
<b>pulumi-up</b> is an idempotent operation. Running it multiple times with the same Pulumi program will always converge to the same desired state for your infrastructure, only making changes if there is a detected drift or an update to your program.


title: STATE MANAGEMENT
content:
Pulumi maintains a state file for each stack, which acts as a source of truth for the deployed resources and their properties. The <b>pulumi-up</b> command relies heavily on this state file to understand the current infrastructure and compute the necessary changes.


title: HISTORY
content:
Pulumi was founded in 2017 with the vision to enable developers to build and manage cloud infrastructure using familiar programming languages. The <b>pulumi-up</b> command has been central to this vision from its inception, embodying the core deployment mechanism. Over time, it has gained advanced features like policy enforcement, targeted resource operations, and improved preview capabilities, reflecting the evolving needs of infrastructure as code.


title: SEE ALSO
content:
<b>pulumi preview</b>(1), <b>pulumi destroy</b>(1), <b>pulumi refresh</b>(1), <b>pulumi state</b>(1), <b>pulumi config</b>(1)


title: PARAMETERS
content:
<b><I>--debug</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose debug logging for the update operation.<br><br><b><I>--diff</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display verbose diffs of all resource changes, showing property-level modifications.<br><br><b><I>--expect-no-changes</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Fails the update if any changes are detected, useful for CI/CD pipelines to ensure idempotency.<br><br><b><I>--json</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Emit output as JSON, suitable for programmatic consumption.<br><br><b><I>--logflow</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Log resource operations in a streaming fashion as they occur.<br><br><b><I>--message <string></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Associates a message with the update operation, which is recorded in the stack's history.<br><br><b><I>--parallel <number></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls the maximum number of concurrent resource operations. Default is 16.<br><br><b><I>--refresh</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Before performing the update, refresh the state of the stack to match the real world.<br><br><b><I>--skip-preview</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skips the interactive preview step and proceeds directly to apply changes. Use with caution.<br><br><b><I>--stack <string></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the stack to operate on. If omitted, the currently selected stack is used.<br><br><b><I>--target <string></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a URN (Uniform Resource Name) of a resource to target for the update. Can be specified multiple times to target multiple resources.<br><br><b><I>--target-dependents</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When using <I>--target</I>, also updates resources that depend on the targeted resources.<br><br><b><I>--yes</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skips prompts and proceeds directly to apply changes. Essential for non-interactive environments and automation.<br><br><b><I>--color <string></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls output coloring (auto|always|never).<br><br><b><I>--secrets-provider <string></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The type of secrets provider to use for the stack (e.g., default, passphrase, awskms, azurekeyvault, gcpkms).<br><br>


title: DESCRIPTION
content:
The <b>pulumi update</b> command is the core operation in the Pulumi workflow, used to deploy and synchronize your infrastructure with the desired state defined in your Pulumi program. When executed, Pulumi performs a "diff" operation, comparing the current state of your cloud resources (as recorded in the stack's state file) with the desired state expressed in your Pulumi code.<br><br>It then presents a preview of the proposed changes (creations, updates, or deletions of resources). Upon confirmation, <b>pulumi update</b> orchestrates the necessary API calls to your cloud provider (e.g., AWS, Azure, GCP, Kubernetes) to bring the infrastructure into alignment with your program.<br><br>This command is idempotent, meaning you can run it multiple times, and it will only apply changes if the desired state differs from the current deployed state. It's crucial for iterating on infrastructure designs, deploying new features, and patching existing deployments.


title: CAVEATS
content:
<b>pulumi update</b> can make destructive changes (e.g., resource deletion or replacement). Always review the preview carefully before confirming.<br><br>Long-running updates can be interrupted due to network issues or other factors, potentially leaving the stack in an inconsistent state. Manual intervention or a subsequent <b>pulumi refresh</b> might be needed to resolve.<br><br>External changes to cloud resources (drift) that are not reflected in the Pulumi state file can lead to unexpected behavior during an update. A <b>pulumi refresh</b> before an update is often recommended to mitigate this.


title: WORKFLOW
content:
The typical <b>pulumi update</b> workflow involves:<br>1.  <b>Preview</b>: Pulumi first performs a <b>preview</b> to show proposed changes to your infrastructure.<br>2.  <b>Confirmation</b>: It then prompts for confirmation (unless <I>--yes</I> is used).<br>3.  <b>Application</b>: Upon confirmation, it applies the changes, creating, updating, or deleting resources as necessary.<br>4.  <b>Reporting</b>: It reports the status of each resource operation, indicating success or failure.


title: ROLLBACKS AND STATE MANAGEMENT
content:
Pulumi maintains a history of updates for each stack, which can be viewed with <b>pulumi history</b>.<br><br>In case of an issue or a failed update, Pulumi provides a <b>pulumi rollback</b> command to revert the stack's state to a previous successful update, helping to recover from deployment issues.


title: HISTORY
content:
Pulumi was founded in 2017 with the vision of bringing modern software engineering practices, like general-purpose programming languages and familiar IDEs, to infrastructure as code (IaC). The <b>pulumi update</b> command has been central to this vision from the outset, serving as the primary mechanism for deploying and managing infrastructure.<br><br>It evolved to handle increasingly complex scenarios, including support for various cloud providers, policy enforcement, and detailed diffing, continuously enhancing the developer experience for IaC operations.


title: SEE ALSO
content:
<b>pulumi preview</b>: Shows a preview of changes without applying them., <b>pulumi refresh</b>: Refreshes the stack's state to match the real world., <b>pulumi destroy</b>: Destroys all resources in a stack., <b>pulumi up</b>: An alias for <b>pulumi update</b>, commonly used interchangeably., <b>terraform apply(1)</b>: (Conceptual) Applies infrastructure changes using Terraform., <b>ansible-playbook(1)</b>: (Conceptual) Executes Ansible playbooks to configure systems.


title: PARAMETERS
content:
<b><b>--json</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output the version information in a machine-readable JSON format. This is particularly useful for scripting and integrating Pulumi version checks into automated workflows.<br><br><b><b>--no-color</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable colorized output. This option is beneficial when running the command in environments that do not support ANSI color codes, or when capturing output for log files where colors might be undesirable.<br><br>


title: DESCRIPTION
content:
The <b>pulumi version</b> command is a utility within the Pulumi Command Line Interface (CLI) used to retrieve and display the current version of the Pulumi CLI installed on your system. This command is crucial for various purposes:<br><br><i>Verification:</i> Confirms that Pulumi is correctly installed and accessible.<br><i>Troubleshooting:</i> Helps in diagnosing issues by providing context about the CLI environment.<br><i>Compatibility:</i> Ensures your CLI version is compatible with your Pulumi projects, cloud providers, or other Pulumi services.<br><i>Updates:</i> Identifies if your CLI is outdated and requires an upgrade. <br><br>The output typically includes the CLI version number, Git commit hash, and build date, offering a comprehensive overview of the installed Pulumi toolchain. It supports different output formats for scripting and automation.


title: CAVEATS
content:
This command specifically reports the version of the Pulumi CLI executable. It does <i>not</i> provide information about the versions of individual Pulumi SDKs or provider packages (e.g., @pulumi/aws, pulumi-kubernetes) used within a Pulumi project. Those dependencies are managed separately by language-specific package managers (e.g., npm, pip, Go modules).<br><br>The Pulumi CLI must be installed and available in the system's PATH for this command to execute successfully.


title: UPDATING PULUMI CLI
content:
To update your Pulumi CLI to the latest version, it is generally recommended to re-run the installation script (e.g., curl -fsSL https://get.pulumi.com/ | sh for Linux/macOS) or use the package manager through which Pulumi was originally installed (e.g., brew upgrade pulumi for Homebrew users).


title: HISTORY
content:
The <b>pulumi version</b> command has been an integral part of the Pulumi CLI since its initial public releases. Its primary function—to provide immediate feedback on the installed client version—has remained consistent, reflecting its foundational role in the Pulumi ecosystem. It serves as a quick and reliable way for users to check their environment.


title: PARAMETERS
content:
<b><b>--json</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Emits the command output in a structured JSON format, useful for programmatic parsing.</I><br><br><b><b>--organization</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Displays the name of the currently selected Pulumi organization associated with the logged-in user.</I><br><br><b><b>--cloud</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Shows the identifier of the currently configured cloud backend or service provider Pulumi is interacting with (e.g., pulumi.com, AWS, Azure).</I><br><br>


title: DESCRIPTION
content:
The <b>pulumi whoami</b> command is a fundamental utility within the Pulumi Command Line Interface (CLI). Its primary purpose is to display the identity of the currently authenticated user in the Pulumi service or backend. This command is crucial for confirming which Pulumi account is active, especially when working with multiple accounts or different cloud backends. It helps developers ensure they are operating within the correct organizational context or against the intended cloud provider when deploying or managing infrastructure. The output typically includes the username or email associated with the logged-in account. Depending on the options used, it can also reveal the currently selected organization or the active cloud backend, providing a comprehensive overview of the current Pulumi environment's authentication state. This command is particularly useful for debugging authentication issues or simply verifying the active session.


title: CAVEATS
content:
This command requires an active Pulumi login. If not logged in, it will typically prompt for login or return an authentication error.<br>The <b>--organization</b> and <b>--cloud</b> flags only display information if applicable to the current configuration or backend.


title: USAGE EXAMPLES
content:
To simply check your current Pulumi user:<br><br><I>pulumi whoami</I><br><br>To see your user and the currently configured organization:<br><br><I>pulumi whoami --organization</I><br><br>To get the output in JSON format for scripting:<br><br><I>pulumi whoami --json</I>


title: HISTORY
content:
Pulumi itself was founded in 2017. The <b>whoami</b> command has been a staple from early versions of the Pulumi CLI, reflecting the fundamental need for users to verify their authentication status. It evolved as the Pulumi service expanded to support organizations and different cloud backends, leading to the addition of flags like <b>--organization</b> and <b>--cloud</b> to provide more context about the current working environment. Its simplicity and directness make it one of the most frequently used diagnostic commands for new and experienced Pulumi users alike.


title: SYNOPSIS
content:
<b>puppet</b> <I>subcommand</I> [<I>options</I>] [<I>arguments</I>]<br><br>Common subcommands include:<br><I><b>agent</b></I>: The client daemon that fetches and applies configurations from a Puppet master.<br><I><b>apply</b></I>: Applies Puppet manifests locally without a master.<br><I><b>master</b></I>: The central server that compiles and serves configurations.<br><I><b>module</b></I>: Manages Puppet modules (install, list, search).<br><I><b>resource</b></I>: Interacts with resource types (e.g., file, service) on the system.<br><I><b>cert</b></I>: Manages SSL certificates for Puppet nodes.


title: PARAMETERS
content:
<b>--debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Global Option.</I> Turns on full debugging output, useful for troubleshooting.<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Global Option.</I> Increases the verbosity of output.<br><br><b>--noop</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Global Option.</I> Enables "no-op" mode, showing what changes would be made without actually applying them. Often used with `puppet agent` or `puppet apply`.<br><br><b>--environment <name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Global Option.</I> Specifies the Puppet environment to use for configuration lookup.<br><br><b>--config <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Global Option.</I> Specifies the path to the main Puppet configuration file (`puppet.conf`).<br><br><b>--test</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Agent-specific Option.</I> Used with `puppet agent` to enable a one-time run in test mode (implies `--noop`, `--verbose`, and disables daemonization).<br><br>


title: DESCRIPTION
content:
Puppet is an open-source <I>configuration management tool</I> used for automating IT infrastructure management. It allows system administrators to define the desired state of their infrastructure using a high-level, declarative language called the <I>Puppet DSL</I> (Domain Specific Language). This "infrastructure as code" approach ensures consistency, repeatability, and scalability across numerous servers.<br><br>Puppet primarily operates in a <I>client-server (agent-master)</I> architecture, where a central Puppet Master compiles configurations (manifests) and agents apply them to individual nodes. It also supports a <I>standalone mode</I> using `puppet apply` for managing single systems without a master. Key features include idempotency (ensuring a resource is configured only if it's not already in the desired state), dependency management, and reporting. Puppet automates tasks like software installation, file management, service management, and user provisioning, significantly reducing manual effort and potential errors in large-scale deployments.


title: CAVEATS
content:
<I>Complexity and Learning Curve</I>: Puppet DSL and concepts (resources, classes, roles, profiles) can be complex for newcomers, requiring a significant learning investment.<br><I>Resource Consumption</I>: The Puppet Master can be resource-intensive, especially in large environments with many agents checking in frequently.<br><I>Dependency Management</I>: Managing complex inter-resource dependencies within manifests can become challenging and lead to unexpected behavior if not handled carefully.<br><I>Debugging</I>: Debugging configuration issues, particularly in complex manifests or with custom types, can sometimes be intricate.


title: KEY CONCEPTS
content:
Puppet operates on several core concepts including:<br><B>Resources</B>: The fundamental units of system configuration (e.g., a file, a service, a user).<br><B>Manifests</B>: Files written in Puppet DSL that describe the desired state of resources.<br><B>Modules</B>: Self-contained, reusable bundles of manifests, templates, and plugins, often shared via the Puppet Forge.<br><B>Facter</B>: A system inventory tool that collects facts about the node (e.g., OS, IP address) for use in manifests.<br><B>Idempotency</B>: Puppet ensures that applying a configuration multiple times has the same effect as applying it once, only making changes if the system deviates from the desired state.


title: OPERATION MODES
content:
<B>Agent/Master Mode</B>: The most common setup, where a Puppet agent on each managed node communicates with a central Puppet master for configurations.<br><B>Standalone Mode (Puppet Apply)</B>: For smaller environments or specific tasks, `puppet apply` directly executes manifests on a local node without requiring a master.


title: HISTORY
content:
Puppet was created by <I>Luke Kanies</I> and first released in <I>2005</I>. It was initially designed to solve the challenges of managing large numbers of servers consistently and efficiently. Over the years, Puppet has evolved significantly, becoming a cornerstone of the DevOps movement and a leading tool for "infrastructure as code."<br><br>Initially known for its agent-master architecture, subsequent releases introduced features like <I>Puppet Apply</I> for standalone operations and improved module management. The company behind Puppet, Puppet Inc. (originally Puppet Labs), was later acquired by <I>Perforce Software</I> in 2023, continuing its development and community support. Its declarative approach profoundly influenced modern system administration practices.


title: SYNOPSIS
content:
<b>puppet-agent</b> [<i>options</i>]<br><br><i>Note:</i> The <b>puppet-agent</b> binary is often a wrapper or symlink that executes the <b>puppet</b> command with its <b>agent</b> subcommand (e.g., <code>puppet agent --test</code>). This synopsis refers to the functionality accessible through this entry point.


title: PARAMETERS
content:
<b>--test</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run the agent once in a verbose and reporting mode, suitable for testing and debugging. Equivalent to <b>--onetime --no-daemonize --verbose --waitforcert 10 --no-use_cached_catalog --detailed-exitcodes --no-skip_noop_self_finish</b>.<br><br><b>--onetime</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run the agent once in the foreground and then exit. Does not daemonize.<br><br><b>--enable</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable the Puppet agent service, allowing it to run periodically or start on boot.<br><br><b>--disable</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable the Puppet agent service, preventing it from running automatically.<br><br><b>--server <i>&lt;HOST&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the hostname of the Puppet Master server to connect to.<br><br><b>--waitforcert <i>&lt;SECONDS&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Wait the specified duration for the Puppet Master to sign the agent's certificate request (CSR).<br><br><b>--noop</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Simulate a run without actually applying any changes to the system. Reports what <i>would</i> have been changed.<br><br><b>--environment <i>&lt;ENV&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the Puppet environment to request a catalog from.<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Log verbosely, showing more information about the agent's operations.<br><br><b>--debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Log with debug messages, providing the most detailed output for troubleshooting.<br><br><b>--daemonize</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run as a background daemon (default behavior if not <b>--onetime</b>).<br><br><b>--no-daemonize</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not daemonize; run in the foreground. Often used with <b>--onetime</b> or for interactive debugging.<br><br><b>--fingerprint</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the SHA256 fingerprint of the agent's SSL certificate, useful for manual certificate verification.<br><br>


title: DESCRIPTION
content:
The <b>puppet-agent</b> is the core client component of the Puppet configuration management system. It's responsible for fetching desired state configurations (called 'catalogs') from a Puppet Master server and applying them to the local system.<br><br>The agent ensures that the system's configuration (files, services, packages, users, etc.) matches the definitions in the Puppet manifests. It operates idempotently, meaning it only makes changes when the current state differs from the desired state. It can run continuously as a daemon, regularly checking in with the master, or be invoked for a one-time run (e.g., for testing or manual application).<br><br>Communication with the Puppet Master is secured using SSL certificates, ensuring authentication and encryption. The <b>puppet-agent</b> is fundamental for maintaining consistent, compliant, and automated infrastructure across a fleet of managed nodes.


title: CAVEATS
content:
The <b>puppet-agent</b> typically requires root or administrator privileges to apply configurations that modify system state (e.g., installing packages, managing services).<br><br>Reliable network connectivity to the Puppet Master is essential for the agent to fetch catalogs and send reports. Issues with network, DNS, or firewalls can prevent the agent from functioning.<br><br>Proper management of SSL certificates is critical for secure communication. If certificates are expired, revoked, or untrusted, the agent will fail to communicate with the master.<br><br>While Puppet strives for idempotency, custom resources or scripts within manifests that are not carefully written might lead to unintended side effects on repeated runs.


title: CONFIGURATION FILES
content:
The primary configuration file for the Puppet agent is <b>puppet.conf</b>, typically located in <i>/etc/puppetlabs/puppet/</i>. This file contains settings such as the Puppet Master's hostname, certificate paths, and logging levels. Other configuration files like <b>hiera.yaml</b> might also be used for data lookup.


title: LOG FILES
content:
By default, the <b>puppet-agent</b> logs its operations to syslog (<i>/var/log/syslog</i> or <i>/var/log/messages</i> on Linux, <i>Event Log</i> on Windows) and/or to a dedicated Puppet log file (e.g., <i>/var/log/puppetlabs/puppet/puppet-agent.log</i>). Log levels can be configured via <b>puppet.conf</b> or command-line options like <b>--verbose</b> or <b>--debug</b>.


title: HISTORY
content:
Puppet was first developed by Luke Kanies in 2005. The agent-master architecture, with the <b>puppet-agent</b> as the client component, has been central to Puppet's design since its early days. Over the years, the agent's capabilities have expanded, including performance optimizations, improved error reporting, and enhanced support for various operating systems and resource types.<br><br>Its development has been driven by the evolving needs of large-scale infrastructure automation, moving from simple configuration management to continuous delivery and desired state enforcement.


title: SYNOPSIS
content:
<b>puppet apply</b> [<i>options</i>] <i>&lt;manifest file(s)&gt;</i><br><b>puppet apply</b> [<i>options</i>] <b>-e</b> <i>&lt;manifest string&gt;</i>


title: PARAMETERS
content:
<b><i>&lt;manifest file(s)&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies one or more Puppet manifest files (.pp) to be applied. These files contain the declarative Puppet code that defines the desired system state.<br><br><b><b>-e</b> <i>&lt;manifest string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows applying a Puppet manifest directly from a string provided on the command line, suitable for quick tests or simple configurations.<br><br><b><b>--modulepath</b> <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the search path for Puppet modules. This can be a single path or a colon-separated list of directories.<br><br><b><b>--environment</b> <i>&lt;name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the Puppet environment to use for the run (e.g., 'production', 'development'), influencing which manifests, modules, and data are loaded.<br><br><b><b>--noop</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a 'no-operation' run, simulating the changes that would be made without actually altering the system. Essential for testing and validating manifests safely.<br><br><b><b>--test</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A convenience option that combines <b>--noop</b>, <b>--debug</b>, and <b>--verbose</b>, providing detailed output for debugging purposes without making actual changes.<br><br><b><b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables highly verbose debug logging, displaying detailed information about Puppet's internal processes for in-depth troubleshooting.<br><br><b><b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases the verbosity of output, providing more information about the resources being processed during the run.<br><br><b><b>--logdest</b> <i>&lt;destination&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Routes log messages to a specified destination, such as 'syslog', 'console', or a file path (e.g., 'file:/var/log/puppet.log').<br><br><b><b>--report</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a report of the Puppet run, which is typically stored locally in Puppet's report directory and can be used for auditing.<br><br><b><b>--show_diff</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the differences between the current state and the desired state of files and other resources when changes are applied.<br><br><b><b>--detailed-exitcodes</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Modifies the exit code of the command to provide more specific information about the outcome of the run (e.g., changes made, failures).<br><br><b><b>--trace</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints a stack trace when errors occur, invaluable for pinpointing issues within Puppet code or the Puppet environment.<br><br>


title: DESCRIPTION
content:
The <b>puppet apply</b> command is a fundamental component of the Puppet configuration management suite, enabling users to compile and apply Puppet manifests directly on the local system. In contrast to the standard master/agent architecture, where a central Puppet master distributes configurations, <b>puppet apply</b> operates in a standalone mode. This makes it exceptionally useful for several key scenarios:<br><br><i>Testing and Development:</i> Developers can quickly test Puppet code changes and observe their effects without a full master infrastructure.<br><i>Small-Scale Deployments:</i> Ideal for configuring single machines or small clusters where the overhead of a dedicated Puppet master is unnecessary.<br><i>Ad-hoc Configuration:</i> Useful for applying specific configurations or performing one-off system adjustments.<br><br>It processes Puppet code (from a file or a string), compiles it into a resource catalog, and then enforces the desired state on the local machine. This command leverages the same core compilation and application logic as the Puppet agent, ensuring consistent and idempotent resource management.


title: CAVEATS
content:
While powerful, <b>puppet apply</b> has certain limitations:<br><br><i>No Centralized Reporting or Orchestration:</i> It lacks the centralized reporting, external node classification integration, and orchestration capabilities provided by a Puppet master.<br><i>Manual or External Scheduling:</i> Requires manual invocation or external scheduling mechanisms (like <b>cron</b> or systemd timers) for periodic application, unlike the continuously running Puppet agent.<br><i>Privilege Requirements:</i> Typically demands root or administrator privileges to enact system-level changes, similar to other configuration management tools.<br><i>Scalability:</i> Less suitable for large-scale infrastructure management where a robust master-agent architecture offers better scalability, reporting, and management features.


title: IDEMPOTENCY
content:
Like all Puppet operations, <b>puppet apply</b> is inherently idempotent. This means that executing the same manifest multiple times will only cause changes if the system's current state deviates from the desired state defined in the manifest. If the system is already in the correct state, <b>puppet apply</b> will make no modifications, ensuring system consistency and preventing unintended side effects from repeated runs.


title: DETAILED EXIT CODES
content:
When the <b>--detailed-exitcodes</b> option is used, <b>puppet apply</b> provides more specific exit codes to indicate the run's outcome:<br><i>0:</i> The run completed successfully with no changes or failures.<br><i>1:</i> The run failed due to an error.<br><i>2:</i> The run completed successfully, and some resources were changed.<br><i>4:</i> The run completed, but some resources failed to be applied.<br><i>6:</i> The run completed, with some resources changed and some resources failed.


title: HISTORY
content:
Puppet was initially released in 2005, and <b>puppet apply</b> has been a foundational command from its inception. It served as a critical tool for developers to test and iterate on Puppet code rapidly without the necessity of a full server setup. This standalone mode was instrumental in the early adoption and growth of the Puppet ecosystem, enabling quick prototyping, local development, and the management of small, independent systems. Even as the master-agent architecture became the standard for larger environments, <b>puppet apply</b> has maintained its importance for testing, debugging, and specific standalone deployments.


title: PARAMETERS
content:
<b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a summary of available command-line options for the script.<br><br><b><b>-V</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the version information for the <I>purge-old-kernels</I> script.<br><br><b><b>--keep</b> <i>&lt;NUMBER&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the number of old kernel versions to retain on the system. The default is typically 2, ensuring fallback options.<br><br><b><b>--purge</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly instructs the script to purge (remove) the identified old kernels. This is usually the default behavior if no other action is specified.<br><br><b><b>--no-purge</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents the script from actually purging kernels. This option is useful when combined with <b>--dry-run</b> to preview actions without making changes.<br><br><b><b>--dry-run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Simulates the kernel removal process without making any actual changes to the system. It shows which kernels would be removed.<br><br><b><b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the removal of all old kernels, even if the current kernel is not running. <B><I>Use with extreme caution</I></B> as it can lead to an unbootable system.<br><br><b><b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, displaying more detailed information about the script's operations during execution.<br><br><b><b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses most of the script's output messages, making it suitable for scripting or automated tasks where minimal output is desired.<br><br><b><b>--all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes all kernel images that are not currently running. <B><I>Use with caution</I></B> as it removes all older fallback kernel versions, leaving only the active kernel.<br><br>


title: DESCRIPTION
content:
<I>purge-old-kernels</I> is a shell script primarily found in Debian-based Linux distributions (like Ubuntu) designed to automatically remove old, unused kernel images and their associated header packages. As new kernel versions are installed during system updates, older versions are typically retained, allowing users to boot into a previous kernel if the new one causes issues. However, over time, these accumulated old kernels can consume significant disk space. The <I>purge-old-kernels</I> script helps manage this by identifying and removing all but the most recent (and typically one or two fallback) kernel versions, preventing disk space exhaustion and keeping the system tidy. It is often run with superuser privileges and is a crucial utility for system maintenance, especially on systems with limited storage or those undergoing frequent updates. While its functionality has largely been integrated into package managers like <I>apt</I> (e.g., via <I>apt autoremove</I>), the standalone script remains a direct way to perform this specific cleanup.


title: CAVEATS
content:
<b>Disk Space:</b> While designed to free up disk space, removing too many kernels can leave you without a working fallback option if your current kernel encounters issues.<br><br><b>Boot Issues:</b> Using options like <b>--force</b> or <b>--all</b> can potentially lead to an unbootable system if the latest kernel has problems and all older fallback options are removed.<br><br><b>Distribution Specific:</b> The availability and exact behavior of <I>purge-old-kernels</I> can vary between Linux distributions. In many modern Debian/Ubuntu systems, <I>apt autoremove</I> handles much of this functionality automatically. This specific script is often part of the <I>debian-goodies</I> package.


title: DEFAULT BEHAVIOR
content:
By default, <I>purge-old-kernels</I> aims to keep the currently running kernel and two previous versions. This provides a balance between disk space conservation and system stability by ensuring readily available fallback boot options.


title: AUTOMATIC REMOVAL VIA APT
content:
In many modern Debian/Ubuntu setups, old kernels that are no longer referenced by other packages are automatically marked as no longer needed. They can typically be purged simply by running <I>sudo apt autoremove</I>. The <I>purge-old-kernels</I> script offers more explicit and granular control beyond this automatic mechanism.


title: HISTORY
content:
The <I>purge-old-kernels</I> script has been a long-standing utility within the Debian/Ubuntu ecosystem, designed to address the accumulation of old kernel packages. Its development was driven by the practical need to manage disk space on systems that frequently received kernel updates. While initial versions might have been simpler shell scripts, its functionality was refined and, in many cases, integrated into the <I>apt</I> package management system, particularly with the introduction and widespread use of <I>apt autoremove</I>. Despite this integration, a standalone <I>purge-old-kernels</I> script (often provided by the <I>debian-goodies</I> package) persists, offering a more direct and sometimes more configurable way to perform this specific cleanup task, especially for users who prefer granular control or need to override default behaviors.


title: PARAMETERS
content:
<b><I>dir</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pushes the current working directory onto the stack, then changes to the specified <I>dir</I>.<br><br><b>+<I>N</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Rotates the N-th directory (0-indexed from the left, top is 0) to the top of the stack and makes it the current working directory.<br><br><b>-<I>N</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Rotates the N-th directory (0-indexed from the right, top is 0) to the top of the stack and makes it the current working directory.<br><br><b>(no arguments)</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Swaps the top two directories on the stack and changes to the new top directory.<br><br>


title: DESCRIPTION
content:
The <b>pushd</b> command allows users to manipulate the directory stack, a list of recently visited directories. When invoked with a directory path, it pushes the current working directory onto the stack, then changes to the specified new directory, and finally displays the updated stack. If no directory is specified, <b>pushd</b> swaps the top two directories on the stack, making the second directory the current working directory. The command can also be used with numerical arguments to rotate specific directories to the top of the stack. This functionality is invaluable for navigating complex file systems efficiently, allowing users to quickly jump between frequently used locations without typing full paths repeatedly. It works in conjunction with <b>popd</b> to remove directories from the stack and <b>dirs</b> to merely list its contents.


title: CAVEATS
content:
<I>pushd</I> is a shell built-in command, meaning it is an integral part of your interactive shell (e.g., Bash, Zsh) rather than an external executable. Its behavior and available options can vary slightly between different shell implementations. The directory stack is specific to the current shell session.


title: THE DIRECTORY STACK DISPLAY
content:
After any <I>pushd</I> operation, the shell typically displays the entire directory stack. The leftmost directory in this display is always the current working directory, and subsequent directories are older entries on the stack.


title: DIRSTACK ENVIRONMENT VARIABLE
content:
The directory stack is internally represented by an array variable called DIRSTACK. Users can inspect or manipulate this variable directly, although it's generally recommended to use <I>pushd</I>, <I>popd</I>, and <I>dirs</I> for safe stack management.


title: HISTORY
content:
The concept of a directory stack and commands like <I>pushd</I>, <I>popd</I>, and <I>dirs</I> originated in the C shell (<I>csh</I>) in the late 1970s at UC Berkeley. This innovation provided a much-needed mechanism for users to manage and navigate frequently visited directories more efficiently than with the basic <I>cd</I> command alone. It was later adopted by other popular shells, including Bash and Zsh, becoming a standard and highly useful feature in modern Unix-like environments.


title: SYNOPSIS
content:
<B>putty</B> [<I>options</I>] [<I>user</I>@]<I>host</I><br><B>putty</B> <I>-ssh</I> [<I>options</I>] [<I>user</I>@]<I>host</I><br><B>putty</B> <I>-telnet</I> [<I>options</I>] [<I>user</I>@]<I>host</I><br><B>putty</B> <I>-rlogin</I> [<I>options</I>] [<I>user</I>@]<I>host</I><br><B>putty</B> <I>-raw</I> [<I>options</I>] [<I>user</I>@]<I>host</I><br><B>putty</B> <I>-serial</I> [<I>options</I>] <I>COM<I>n</I></I><br><B>putty</B> <I>-load session_name</I>


title: PARAMETERS
content:
<b><I>-load <session_name></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Loads a previously saved PuTTY session configuration.<br><br><b><I>-ssh | -telnet | -rlogin | -raw | -serial</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the network protocol to use for the connection.<br><br><b><I>-l <username></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the username for the remote login.<br><br><b><I>-P <port></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the port number to connect to.<br><br><b><I>-pw <password></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the password for authentication. <B>Use with extreme caution; highly insecure.</B><br><br><b><I>-i <keyfile></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the private key file (<I>.ppk</I> format) for SSH public-key authentication.<br><br><b><I>-loghost <hostname></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Records the host name in the session log file.<br><br><b><I>-logfilename <filename></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the file path to log the session output.<br><br><b><I>-L <[listen-IP:]listen-port:host:port></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Configures local port forwarding (e.g., <I>-L 8080:localhost:80</I>).<br><br><b><I>-R <[listen-IP:]listen-port:host:port></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Configures remote port forwarding.<br><br><b><I>-X</I> or <I>-x</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables X11 forwarding for graphical applications.<br><br><b><I>-N</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents starting a remote shell or command; useful for port forwarding only.<br><br><b><I>-t</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces allocation of a pseudo-terminal.<br><br><b><I>-T</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables pseudo-terminal allocation.<br><br><b><I>-v</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays PuTTY's version information and exits.<br><br>


title: DESCRIPTION
content:
PuTTY is a widely-used, <I>free and open-source</I> terminal emulator, serial console, and network file transfer application. Primarily developed for Microsoft Windows, it supports various network protocols including <B>SSH</B> (Secure Shell), <B>Telnet</B>, <B>Rlogin</B>, and raw socket connections. It serves as a crucial tool for securely connecting to remote servers, executing commands, and transferring files over an encrypted channel. <br><br>Its robust SSH capabilities include support for multiple authentication methods (password, public key), <B>port forwarding</B> (local, remote, dynamic), and <B>X11 forwarding</B>, making it indispensable for system administrators, developers, and anyone managing remote Unix-like systems. PuTTY also offers a highly configurable interface for session management, allowing users to save connection details, terminal appearance, and various protocol-specific settings for quick access.


title: CAVEATS
content:
PuTTY is primarily a <B>graphical application</B> for Windows; command-line usage is mainly for automating session launches or specific configurations. <br><br>Passing sensitive information like passwords via the command line using <I>-pw</I> is <B>highly insecure</B> as it exposes credentials in system process lists and history. <br><br>PuTTY uses its own private key format (<I>.ppk</I>); OpenSSH private keys require conversion using the accompanying <B>PuTTYgen</B> tool before use.


title: KEY GENERATION (PUTTYGEN)
content:
The PuTTY suite includes <B>PuTTYgen.exe</B>, a utility for generating SSH public and private key pairs. It also supports converting private keys between PuTTY's native <I>.ppk</I> format and OpenSSH formats, which is essential for cross-platform compatibility when using public-key authentication.


title: COMPANION COMMAND-LINE TOOLS
content:
In addition to the main PuTTY client, the package provides other command-line utilities: <B>PSCP.exe</B> (PuTTY Secure Copy client) for secure file transfers, and <B>PSFTP.exe</B> (PuTTY SFTP client) for interactive SFTP sessions, offering functionality similar to the <I>scp</I> and <I>sftp</I> commands on Linux.


title: HISTORY
content:
PuTTY was first developed by <I>Simon Tatham</I> and released around <I>1999</I>. It quickly gained popularity among Windows users due to the lack of a built-in SSH client in older versions of Microsoft Windows. Its development has been continuous, with ongoing updates improving security, adding new features, and enhancing compatibility across various server environments. It has established itself as a standard tool for remote access on the Windows platform.


title: SEE ALSO
content:
<I>ssh(1)</I>, <I>scp(1)</I>, <I>sftp(1)</I>, <I>telnet(1)</I>, <I>rlogin(1)</I>, <I>ssh-keygen(1)</I>


title: SYNOPSIS
content:
<b>pv</b> [<i>options</i>] [<i>file</i>...]<br><i>command1</i> | <b>pv</b> [<i>options</i>] | <i>command2</i><br><b>pv</b> [<i>options</i>] < <i>inputfile</i> > <i>outputfile</i>


title: PARAMETERS
content:
<b><b>-s</b> <i>SIZE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the total data size to <i>SIZE</i> bytes. This is crucial for calculating percentage complete and ETA, especially when <b>pv</b> cannot determine the size from its input (e.g., from a pipe).<br><br><b><b>-L</b> <i>RATE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limits the transfer rate to <i>RATE</i> bytes per second. Useful for throttling bandwidth or disk I/O.<br><br><b><b>-p, -t, -e, -r, -b</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;These flags control the display components: progress bar (<i>-p</i>), time elapsed (<i>-t</i>), ETA (<i>-e</i>), transfer rate (<i>-r</i>), and bytes transferred (<i>-b</i>). Most are displayed by default when <b>pv</b> is used interactively.<br><br><b><b>-q</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Quiet mode</i>. Suppresses all progress output. Useful when <b>pv</b> is used solely for rate limiting (with <b>-L</b>) without visual feedback.<br><br><b><b>-d</b> <i>PID</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instead of reading from standard input, monitors the file descriptors of a specific process ID (<i>PID</i>). Can be used to attach to running <b>dd</b> or <b>cp</b> commands.<br><br><b><b>-W</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Wait</i> for input. Normally, <b>pv</b> exits if its input file reaches EOF. This option makes <b>pv</b> wait for more input instead, which is useful for monitoring growing files or ongoing streams.<br><br><b><b>-F</b> <i>FORMAT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows specifying a custom output format string, providing fine-grained control over the displayed progress information and its layout.<br><br>


title: DESCRIPTION
content:
<b>pv</b> (Pipe Viewer) is a lightweight, terminal-based utility designed to monitor the progress of data flowing through a pipeline. It acts as a transparent filter, reading data from its standard input and writing it to its standard output, while simultaneously displaying a visual indication of the data's transfer.<br><br>The progress information, which includes a progress bar, the time elapsed, the current data transfer rate, the total amount of data transferred, and an estimated time of arrival (ETA), is displayed to standard error, ensuring it doesn't interfere with the data stream itself. This makes <b>pv</b> an invaluable tool for operations involving large files or lengthy processes where visual feedback is crucial, such as copying files, creating archives, or processing data streams.<br><br>It is commonly integrated into shell scripts and command-line operations alongside tools like <b>dd</b>, <b>tar</b>, <b>cat</b>, <b>cp</b>, and <b>gzip</b>. By inserting <b>pv</b> into a pipeline (e.g., <i>command1</i> | <b>pv</b> | <i>command2</i>), users gain real-time insight into the progress of data transfer, helping to gauge remaining time and identify potential bottlenecks. It can also be used to limit the data transfer rate, useful for throttling network or disk I/O.


title: CAVEATS
content:
For <b>pv</b> to provide accurate percentage and ETA estimates, especially when used in a pipe, it often needs to know the total size of the data to be processed. This can be specified using the <i><b>-s SIZE</b></i> option. If the total size is unknown, <b>pv</b> will only display elapsed time, transfer rate, and bytes transferred, but not percentage or ETA.<br><br>The progress output is directed to <i>standard error</i> (stderr), ensuring it doesn't interfere with the actual data stream passing from <i>standard input</i> to <i>standard output</i>. This means if you redirect stderr (e.g., to <i>/dev/null</i>), you might lose the progress output.


title: HOW IT WORKS
content:
<b>pv</b> operates as a simple pass-through filter. It reads data from its <i>standard input</i> (stdin), passes that data unchanged to its <i>standard output</i> (stdout), and simultaneously sends progress updates to its <i>standard error</i> (stderr). This design allows it to be seamlessly inserted into any pipeline without affecting the data content or its integrity. It does not buffer or store the data itself, acting purely as a monitor.


title: PRACTICAL USAGE EXAMPLES
content:
To copy a large file with a progress bar and rate limit, you might use:<br><br><i><b>cat largefile.img | pv -L 10m -s $(stat -c%s largefile.img) > newfile.img</b></i><br><br>Here, <i><b>-L 10m</b></i> limits the transfer to 10 megabytes per second, and <i><b>-s $(stat -c%s largefile.img)</b></i> provides the total size of the input file to <b>pv</b> for accurate percentage and ETA calculation.<br><br>For copying raw disk images with progress:<br><br><i><b>dd if=/dev/sda | pv -s 500G | dd of=/dev/sdb</b></i><br><br>Or to monitor a network download with <b>wget</b>:<br><br><i><b>wget -O - http://example.com/largefile.iso | pv > largefile.iso</b></i>


title: HISTORY
content:
<i>pv</i> (Pipe Viewer) was created by Andrew Wood to address a common need in Unix-like environments: providing visual feedback for long-running data transfer operations, which traditionally offer no progress indication. Since its initial release, it has become a widely adopted and popular tool for enhancing the user experience of command-line operations involving data pipelines, filling a niche that other core utilities do not natively cover.


title: SYNOPSIS
content:
<b>pvchange</b> [<i>OPTIONS</i>] <i>PV_PATH</i>...<br><br><i>PV_PATH</i>...: Specifies one or more paths to the physical volumes whose attributes are to be changed.


title: PARAMETERS
content:
<b><b>-x</b> {y|n} or <I>--allocatable</I> {y|n}</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets or clears the allocatable attribute for the specified physical volume(s). If 'y', extents can be allocated on the PV. If 'n', no new extents can be allocated on this PV, and existing extents cannot be moved off it unless explicitly specified during an <I>lvmove</I> operation. Setting to 'n' is useful for maintenance purposes.<br><br><b><b>-u</b> <I>UUID</I> or <I>--uuid</I> <I>UUID</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows changing the <I>Universally Unique Identifier (UUID)</I> of a physical volume. This is a very rare and potentially dangerous operation; use with extreme caution as it can corrupt LVM metadata if not managed properly. Typically, LVM assigns UUIDs automatically.<br><br><b><b>-f</b> or <I>--force</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses all confirmation prompts and forces the operation to proceed, even if it might seem unsafe. Use with extreme caution, as it can lead to unintended consequences.<br><br><b><b>-y</b> or <I>--yes</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Answers yes to all questions, allowing the command to proceed without interactive confirmation.<br><br><b><b>-v</b> or <I>--verbose</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases the verbosity of the command's output, providing more detailed information about the operations being performed.<br><br><b><b>-q</b> or <I>--quiet</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses most output messages, only showing errors or critical warnings.<br><br><b><I>--version</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version of the LVM tools currently installed.<br><br><b><I>--help</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message with available options and usage information for the <I>pvchange</I> command.<br><br>


title: DESCRIPTION
content:
<I>pvchange</I> is an essential utility within the Linux <I>Logical Volume Manager (LVM)</I> framework. It allows administrators to modify various attributes of existing <I>Physical Volumes (PVs)</I>. The primary function of <I>pvchange</I> is to control the <I>allocatable</I> status of a PV, which dictates whether logical volume extents can be placed on or removed from it. This command is crucial for maintenance operations, such as temporarily taking a PV out of service for underlying storage modifications or when preparing a PV for removal from a <I>Volume Group (VG)</I> without completely deactivating it. While less common, it can also be used to change the <I>Universally Unique Identifier (UUID)</I> of a PV, though this operation should be approached with extreme caution as it can disrupt LVM metadata if not handled correctly. <I>pvchange</I> operates on specified PV paths, applying the desired attribute changes directly to the PV's metadata on disk.


title: CAVEATS
content:
<I>pvchange</I> directly modifies LVM metadata on disk. Incorrect use, especially with the <I>--uuid</I> option, can lead to data loss or render LVM volumes inaccessible. Always ensure you have backups of critical data before performing LVM metadata changes. This command typically requires root privileges to execute. Setting a PV to non-allocatable (<b>-x n</b>) does not remove existing data; it only prevents new data from being written.


title: USE CASE: MAINTENANCE
content:
<code>pvchange -x n /dev/sdb1</code><br>This command makes <code>/dev/sdb1</code> non-allocatable. This is useful when you need to perform maintenance on the underlying disk (e.g., SMART tests, firmware updates) but don't want LVM to try allocating new extents on it. After maintenance, you can set it back to allocatable with <code>pvchange -x y /dev/sdb1</code>.


title: IMPACT OF NON-ALLOCATABLE PV
content:
When a PV is marked as non-allocatable, LVM will not use it for new allocations when creating or extending logical volumes. However, existing logical volumes that span this PV will continue to function normally. To move data off a non-allocatable PV, you would typically use <I>pvmove</I> or other LVM migration tools.


title: HISTORY
content:
The <I>Logical Volume Manager (LVM)</I> concept originated in Hewlett-Packard's HP-UX operating system. LVM for Linux, often referred to as <I>LVM1</I>, was developed in the late 1990s. The <I>LVM2</I> iteration, which brought significant improvements in scalability, performance, and flexibility, became the standard in the early 2000s and is the version commonly used today. <I>pvchange</I> has been a fundamental component of LVM since its early days, consistently providing the capability to modify individual physical volume attributes, reflecting the modular design of LVM that separates physical storage management from logical volume organization. Its functionality, particularly the <b>-x</b> (allocatable) option, has remained crucial for managing PV lifecycle within a volume group.


title: PARAMETERS
content:
<b><i>PhysicalVolumePath</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more paths to the physical volume(s) to check (e.g., <i>/dev/sdb1</i>).<br><br><b><b>-d</b>, <b>--dry-run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform a simulated check without making any actual changes to the metadata.<br><br><b><b>-r</b>, <b>--repair</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempt to repair detected metadata corruption. <b>Use with extreme caution and after ensuring recent backups!</b> This operation carries a risk of data loss if not used properly.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increase the verbosity of the output, showing more details about the check process and findings.<br><br><b><b>--reportformat {basic|json}</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the output format for the check results, either plain text (basic) or JSON for programmatic parsing.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message with command usage and options, then exit.<br><br><b><b>-V</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display version information about the <b>pvck</b> command and LVM, then exit.<br><br>


title: DESCRIPTION
content:
<b>pvck</b> is an LVM (Logical Volume Manager) command used to <br>inspect and verify the integrity of the metadata stored on <br>physical volumes. LVM organizes storage into physical volumes <br>(PVs), volume groups (VGs), and logical volumes (LVs). <br>The metadata on PVs contains crucial information about the LVM <br>structure, including the allocation of extents and details <br>about the volume group it belongs to. <br>Corruption of this metadata can lead to unmountable file <br>systems, lost logical volumes, or even render an entire <br>volume group unusable. <br><b>pvck</b> helps identify such corruption and, with the <br>appropriate option, can attempt to repair it, making it an <br>essential tool for maintaining the health and stability of <br>LVM-managed storage.


title: CAVEATS
content:
Using the <b>-r</b> (<i>--repair</i>) option can be <br>dangerous and may lead to data loss if not used correctly <br>or in cases of severe, unrecoverable corruption. <br>Always ensure you have recent backups before attempting <br>any repairs. <br><b>pvck</b> primarily checks LVM metadata integrity; it does not <br>check the integrity of the underlying filesystem on the <br>logical volumes or the actual data blocks themselves.


title: METADATA CORRUPTION EXPLAINED
content:
LVM metadata describes the layout of physical <br>volumes, how they form volume groups, and how logical <br>volumes are carved out of those groups. Corruption can <br>occur due to power failures, disk errors, or improper <br>system shutdowns. Even a single bit flip in critical <br>metadata can prevent LVM from recognizing its volumes, <br>making <b>pvck</b> vital for diagnostics and potential recovery.


title: WHEN TO USE PVCK
content:
<b>pvck</b> should be run if you suspect <br>LVM metadata issues, such as after a system crash, <br>unexpected power loss, or when LVM commands fail to <br>recognize or activate volume groups. It's also a good <br>precautionary step before performing significant LVM <br>operations like physical volume migration, resizing, or <br>adding new physical volumes to a volume group.


title: HISTORY
content:
<b>pvck</b> is an integral part of the <br><i>Logical Volume Manager (LVM)</i> suite of tools. LVM <br>itself has been a standard feature in Linux distributions <br>for many years, providing flexible storage management <br>capabilities. <b>pvck</b> specifically addresses the need for <br>metadata integrity checks, which are crucial for the <br>robustness of any volume management system. Its functionality <br>has evolved alongside LVM, adapting to new features and <br>ensuring the reliability of physical volume metadata within <br>modern Linux environments.


title: PARAMETERS
content:
<b>-f, --force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the creation of a PV, overriding safety checks. Use with extreme caution as this can destroy existing data.<br><br><b>-u, --uuid <uuid></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the UUID for the new physical volume. If not provided, a random UUID will be generated.<br><br><b>-y, --yes</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assume 'yes' to all prompts, useful for scripting. Use with caution.<br><br><b>-Z, --zero <y|n></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Zero (or do not zero) the first 4KB of the device. This is often used to clear old signatures. Default is 'y'.<br><br><b>--dataalignment <bytes></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Align the start of the data area. Useful for performance with certain storage devices like SSDs or RAID arrays.<br><br><b>--metadatacopies <num></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the number of metadata copies to store on the PV. Default is 1 or 2 depending on setup.<br><br><b>--bootloaderareasize <bytes></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reserves a small area at the beginning of the device for a bootloader. Important when using LVM on a bootable disk.<br><br>


title: DESCRIPTION
content:
<i><b>pvcreate</b></i> is a fundamental command in Linux's Logical Volume Manager (LVM) framework. It initializes a block device, such as a hard disk, disk partition, or RAID array, for use as a physical volume (PV) within LVM. A PV is the lowest layer in the LVM hierarchy, serving as a building block for volume groups (VGs). <br><br>By creating a PV, <b>pvcreate</b> writes an LVM metadata header to the device, making it recognizable and usable by LVM for subsequent operations like creating a volume group with <i>vgcreate</i>. This command prepares the device to store LVM metadata and user data, allowing for flexible and dynamic storage management. It's typically the first step in setting up an LVM storage solution.


title: CAVEATS
content:
Using <b>pvcreate</b> on a device that contains an active filesystem or important data will permanently destroy that data. Always ensure you have a complete backup before running this command. <br><br>The command requires root privileges to execute. Ensure the specified device is a raw block device and not currently mounted or in use by another process.


title: USAGE NOTES
content:
Before running <b>pvcreate</b>, it's a good practice to ensure the target device does not contain any critical data. You can optionally wipe the device clean with tools like <i>dd</i> or <i>wipefs</i> beforehand, especially if it was previously used.


title: LVM HIERARCHY
content:
<b>pvcreate</b> forms the foundation of LVM. Once a physical volume is created, it can be added to a Volume Group (VG) using <i>vgcreate</i> or <i>vgextend</i>. Logical Volumes (LVs) are then created on top of VGs using <i>lvcreate</i>, which can be formatted with filesystems and mounted.


title: HISTORY
content:
Logical Volume Manager (LVM) was originally developed for HP-UX in the 1980s. The LVM tools, including <b>pvcreate</b>, were later ported to Linux and became a standard part of most Linux distributions in the early 2000s, providing advanced storage management capabilities that were previously only available in proprietary Unix systems.


title: SYNOPSIS
content:
pvdisplay [<I>options</I>] [<I>PhysicalVolumePath</I> | <I>PhysicalVolumeUUID</I> ...]<br>Common usage examples:<br>&nbsp;&nbsp;&nbsp;&nbsp;pvdisplay<br>&nbsp;&nbsp;&nbsp;&nbsp;pvdisplay /dev/sdb1<br>&nbsp;&nbsp;&nbsp;&nbsp;pvdisplay -C -o pv_name,vg_name,pv_size


title: PARAMETERS
content:
<b>-a, --all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays information for all physical volumes present on the system.<br><br><b>-C, --reportmode</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates output in a columnar report format, similar to 'pvs', which is useful for scripting or concise viewing.<br><br><b>-m, --maps</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows a detailed physical-to-logical extent map for each physical volume, illustrating how PEs are mapped to LVs.<br><br><b>-o, --options <field_list></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies custom output fields to display when using --reportmode. Common fields include 'pv_name', 'vg_name', 'pv_size', 'pv_uuid', 'pv_free', 'pv_attr'.<br><br><b>-s, --short</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays only the size of the physical volume(s) in a concise format.<br><br><b>--units <unit></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the units for size reporting (e.g., 's' for sectors, 'k' for kilobytes, 'm' for megabytes, 'g' for gigabytes, 't' for terabytes).<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases the verbosity of the command's output, showing more runtime information.<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 the version of the LVM utilities and exits.<br><br>


title: DESCRIPTION
content:
pvdisplay is a fundamental command within the LVM2 (Logical Volume Manager) suite in Linux, designed to <br>display detailed information about physical volumes (PVs). PVs are the foundational storage components <br>—typically disk partitions or entire disk devices—that LVM uses to construct volume groups. This command <br>provides a comprehensive, human-readable overview of each PV, including its unique identifier (UUID), <br>device path, overall size, the volume group it belongs to (if any), and crucial statistics like <br>total and free Physical Extents (PEs). <br><br>Administrators frequently use pvdisplay to quickly ascertain the status, capacity, and allocation of <br>physical storage resources managed by LVM. Its output is invaluable for tasks such as monitoring disk <br>space, verifying LVM configurations, and diagnosing storage-related issues. While pvs offers a more <br>concise, script-friendly columnar output, pvdisplay's default detailed view is preferred for <br>in-depth human inspection and troubleshooting. It provides a deeper insight into the physical layer <br>of an LVM setup.


title: CAVEATS
content:
Running pvdisplay typically requires <B>root privileges</B> to access and interpret LVM metadata. <br>The command is strictly for displaying information and <B>cannot modify</B> any aspects of physical volumes or LVM configurations. <br>While its default output is highly detailed, it can be extensive, making it less ideal for automated <br>script parsing compared to the more succinct pvs or pvdisplay -C.


title: OUTPUT INTERPRETATION
content:
The default output of pvdisplay presents each physical volume in a block format, including fields like <B>PV Name</B>, <B>VG Name</B>, <B>PV Size</B>, <B>Allocatable</B> (yes/no), <B>Free PE</B>, and <B>Total PE</B>. These fields provide a comprehensive view of the PV's state and its contribution to the LVM storage pool. The <B>PV UUID</B> (Universal Unique Identifier) ensures each physical volume is uniquely identifiable across reboots or system changes.


title: USING WITH ARGUMENTS
content:
You can specify one or more physical volume paths (e.g., /dev/sdb1 /dev/sdc1) or UUIDs as arguments to pvdisplay to limit the output to specific PVs. If no arguments are provided, pvdisplay will display information for all known physical volumes on the system.


title: HISTORY
content:
pvdisplay is an integral component of the <B>LVM2</B> (Logical Volume Manager version 2) project, <br>a sophisticated disk management system for Linux. LVM, first introduced in Linux around 1998, <br>revolutionized storage abstraction by allowing administrators to manage disk space more flexibly <br>than traditional partitioning schemes. LVM2, a complete rewrite, emerged in the early 2000s, <br>bringing significant improvements in performance, stability, and feature set. <br>pvdisplay has consistently been a core utility within both LVM1 and LVM2, providing system <br>administrators with critical insights into the physical storage layer managed by LVM.


title: SYNOPSIS
content:
<b>pvecm</b> <I>command</I> [<I>options</I>]<br><br>Common commands:<br><b>pvecm add</b> <I>IP-address</I> [<I>options</I>]<br><b>pvecm delnode</b> <I>node-name</I> [<I>options</I>]<br><b>pvecm status</b><br><b>pvecm nodes</b><br><b>pvecm qdevice</b> <I>sub-command</I> [<I>options</I>]<br><b>pvecm expected</b> <I>count</I>


title: PARAMETERS
content:
<b><b>--help</b>, <b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show a help message and exit.<br><br><b><b>--version</b>, <b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show version information and exit.<br><br>


title: DESCRIPTION
content:
<code>pvecm</code> is the central command-line utility for managing a Proxmox VE High Availability cluster. It provides an interface to the underlying <I>Corosync</I> cluster engine and the <I>Proxmox Cluster Filesystem (PMXCFS)</I>, allowing administrators to perform crucial tasks such as creating new clusters, adding or removing nodes, checking cluster status and membership, and configuring quorum devices (<I>QDevice</I>).<br><br>The command ensures the health and integrity of the HA cluster, which is essential for maintaining high availability of virtual machines and containers by enabling features like live migration and automatic failover in case of node failures. It is a critical tool for scaling Proxmox VE deployments and ensuring resilience against hardware outages and provides a unified interface for complex cluster operations.


title: CAVEATS
content:
<ul><li><I>Cluster Quorum:</I> A cluster must maintain quorum (a majority of nodes online) to operate. Loss of quorum can halt VMs/CTs on affected nodes.</li><li><I>Network Stability:</I> Highly dependent on stable, low-latency network communication between nodes. Unreliable networking can lead to split-brain scenarios or cluster instability.</li><li><I>Node Removal:</I> Removing a node (especially using <code>delnode</code>) requires careful planning. The node should be powered off and ideally removed from the cluster cleanly before physical removal. Forcing removal of an active node is dangerous and can cause cluster inconsistencies.</li><li><I>IP Address Changes:</I> Changing a node's IP address within an active cluster is complex and not directly supported via <code>pvecm</code>. It usually requires specific manual procedures.</li><li><I>Backup:</I> Always back up configuration files (e.g., <code>/etc/pve/</code>) before making significant cluster changes.</li></ul>


title: COMMON SUBCOMMANDS
content:
<ul><li><b>pvecm add</b> <I>IP-address</I> [<I>options</I>]: Joins a new node to an existing cluster. The IP address must be of an existing cluster member.<br>Options include <code><i>--force</i></code> (force join, use with caution), <code><i>--nodeid</i></code> (assign a specific ID), <code><i>--ring0_addr</i></code> (specify network for primary Corosync ring), and <code><i>--ring1_addr</i></code> (specify network for secondary Corosync ring for redundancy).<br></li><li><b>pvecm delnode</b> <I>node-name</I> [<I>options</I>]: Removes a node from the cluster. The node should ideally be powered off and removed from the cluster cleanly before using this command. Using <code><i>--force</i></code> is highly discouraged on an active node.<br></li><li><b>pvecm status</b>: Displays the current cluster status, including quorum information, active nodes, and Corosync health.<br></li><li><b>pvecm nodes</b>: Lists all nodes that are members of the cluster, showing their node IDs and status.<br></li><li><b>pvecm qdevice</b> <I>sub-command</I> [<I>options</I>]: Manages a QDevice (Quorum Device).<br>Common sub-commands: <code><i>setup</i></code> (configures a QDevice), <code><i>destroy</i></code> (removes QDevice configuration), <code><i>status</i></code> (shows QDevice status). A QDevice is crucial for maintaining quorum in two-node clusters.</li></ul>


title: QUORUM AND QDEVICE
content:
In a Corosync cluster, quorum is achieved when a majority of votes are present. Each node typically contributes one vote. For a cluster to operate, more than half of the total votes must be online. This mechanism prevents split-brain scenarios where two halves of a cluster could operate independently, leading to data corruption.<br><br>For a two-node cluster (total 2 votes), a simple majority isn't possible (e.g., if one node fails, only 1 out of 2 votes remain, which is 50%, not a majority). A <I>QDevice</I> (Quorum Device) provides an additional third vote from an external server. If one node fails, the remaining node plus the QDevice can form a majority (2 out of 3 votes), allowing the cluster to remain active and maintain HA services.


title: CLUSTER NETWORK REQUIREMENTS
content:
Proxmox VE clusters require a dedicated, low-latency, and high-bandwidth network for Corosync communication. It is highly recommended to use at least two redundant network interfaces (configured as <code>ring0</code> and <code>ring1</code>) for Corosync to ensure high availability of the cluster communication itself. These interfaces should ideally be on separate physical networks or VLANs to protect against single points of failure, ensuring robust cluster operation even during network component failures.


title: HISTORY
content:
Proxmox VE's cluster capabilities have evolved significantly, primarily leveraging <I>Corosync</I> for robust inter-node communication and quorum management. <code>pvecm</code> emerged as the primary user-facing tool, abstracting the complexities of Corosync configuration into simplified commands. Early versions of Proxmox VE also relied on CMAN/OpenAIS before fully transitioning to Corosync. The continuous development focuses on improving cluster stability, ease of management, and integrating new features like QDevice for better quorum handling in two-node clusters.


title: PARAMETERS
content:
<b>full</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs all available benchmarks, including disk I/O, CPU, memory/context, and open file limit tests.<br><br><b>io</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs sequential disk I/O benchmarks, measuring read and write speeds using a temporary file.<br><br><b>cpu</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes CPU-intensive benchmarks, such as SHA-1 hashing and prime number calculations, to assess CPU computational speed.<br><br><b>mconf</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Benchmarks memory access and context switching performance.<br><br><b>openfile</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Checks the system's maximum number of open files limit.<br><br>


title: DESCRIPTION
content:
<I>pveperf</I> is a command-line utility designed for Proxmox Virtual Environment (PVE) hosts. Its primary purpose is to quickly assess the performance of the underlying hardware, specifically focusing on disk I/O and CPU computational speed. It runs a series of simple, built-in benchmarks to provide a baseline performance measurement. These benchmarks include sequential disk write and read tests (using a temporary file) and CPU-intensive operations (like SHA-1 hashing and prime number calculations). The output provides various metrics, such as disk throughput (MB/s) and CPU operations per second. While not a comprehensive benchmarking suite, <I>pveperf</I> is invaluable for a rapid health check, identifying potential hardware bottlenecks, or comparing the performance of different Proxmox hosts or storage configurations within a virtualized environment. It helps ensure the host can adequately support virtual machines and containers.


title: CAVEATS
content:
Results from <I>pveperf</I> are indicative and provide a quick overview, not a comprehensive or highly detailed performance analysis. For in-depth benchmarking, more specialized tools like <I>fio</I> or <I>sysbench</I> are recommended. The disk I/O tests temporarily use a file, which might slightly impact other disk operations during the test run. It's crucial to interpret results in context; a lower score might indicate hardware limitations, but could also be influenced by background processes or specific storage configurations. It is best used for comparative analysis between systems or configurations.


title: TYPICAL OUTPUT
content:
The output of <I>pveperf</I> presents various metrics related to CPU and disk performance. Key indicators include: <br> <b>CPU BOGOMIPS</b>: A basic CPU speed measurement. <br> <b>SHA1</b>: Performance of SHA-1 hashing operations, reflecting general CPU integer performance. <br> <b>PRIME</b>: Speed of prime number calculations, another CPU-intensive metric. <br> <b>FSYNCS/SEC</b>: The number of file synchronizations per second, crucial for understanding metadata write performance. <br> <b>HD Write/Read</b>: Sequential disk throughput in Megabytes per second (MB/s) for both write and read operations. These values are derived from tests performed on a temporary file.


title: USAGE CONTEXT
content:
Use <I>pveperf</I> for rapid assessment of your Proxmox VE host performance. It is particularly useful for: <br> - Verifying hardware performance during initial setup or after hardware changes. <br> - Identifying potential bottlenecks when virtual machines or containers experience performance issues. <br> - Comparing the performance of different Proxmox hosts or storage configurations. <br> - As a quick health check after system updates or reboots.


title: HISTORY
content:
<I>pveperf</I> is an integral utility within the Proxmox Virtual Environment (PVE) distribution. It was developed specifically to provide Proxmox administrators with a quick and straightforward method to assess the fundamental performance characteristics of their host systems. Its evolution has been intertwined with the development and growth of Proxmox VE, serving as a key diagnostic and health-check tool within the PVE ecosystem.


title: PARAMETERS
content:
<b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays verbose output, including detailed version information for all installed Proxmox-related packages and libraries. This option provides a comprehensive overview of the Proxmox VE software stack, useful for in-depth analysis.<br><br>


title: DESCRIPTION
content:
<i>pveversion</i> is a specialized command integral to the Proxmox Virtual Environment (PVE), an open-source server virtualization management solution.<br><br>Its primary function is to report the installed versions of various Proxmox VE components, including the main <b>proxmox-ve</b> meta-package, the running Linux kernel, and <b>pve-manager</b>. This utility is indispensable for system administrators seeking to quickly ascertain the exact state of their Proxmox VE installation.<br><br>It's crucial for troubleshooting, ensuring software compatibility, and planning system upgrades, as it provides precise version numbers required when seeking support or checking for known issues. By consolidating this vital information, <i>pveversion</i> simplifies the process of verifying that the correct component versions are active, ensuring the stability and security of the virtualized environment.


title: CAVEATS
content:
The <i>pveversion</i> command is exclusively available on systems running Proxmox Virtual Environment. It is not a standard Linux command found on general-purpose distributions.<br><br>The exact output format may vary slightly across different major versions of Proxmox VE, although the core information regarding primary components remains consistent.


title: KEY OUTPUT COMPONENTS
content:
The standard output of <i>pveversion</i> typically includes:<br><i><b>proxmox-ve</b></i>: The version of the Proxmox VE meta-package, indicating the overall Proxmox release.<br><i><b>pve-manager</b></i>: The version of the Proxmox web interface and management tools.<br><i><b>kernel</b></i>: The version of the Linux kernel currently running on the system.<br>Other lines may list versions of core libraries and services like <i>pve-lib-perl</i>, <i>pve-common</i>, etc., especially when using the verbose (<b>-v</b>) option.


title: HISTORY
content:
The <i>pveversion</i> command has been a core component of the Proxmox Virtual Environment since its early development stages, designed to provide a centralized and consistent method for administrators to query system version information. Its existence reflects the need within a specialized appliance-like distribution (PVE) to quickly identify the specific build and component versions, aiding in support and upgrade processes. It has remained largely consistent in its functionality, reflecting its stable and essential role within the Proxmox ecosystem.


title: SYNOPSIS
content:
<b>pvmove</b> [<I>OPTIONS</I>] [<I>SOURCE_PV</I>[:<I>PE</I>[-<I>PE</I>]...]] [<I>DEST_PV</I>[:<I>PE</I>[-<I>PE</I>]...]...]<br><b>pvmove</b> [<I>OPTIONS</I>] <I>SOURCE_PV</I><br><b>pvmove</b> <B>--abort</B>


title: PARAMETERS
content:
<b>SOURCE_PV</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The physical volume from which extents will be moved. Can be optionally followed by extent ranges (e.g., 'pv_name:100-200').<br><br><b>DEST_PV</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The physical volume(s) to which extents will be moved. Optional if moving all data off a source PV.<br><br><b>--alloc <I>allocation_policy</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the allocation policy for new physical extents (e.g., 'normal', 'contiguous', 'anywhere').<br><br><b>-b, --background</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs the pvmove process in the background, allowing the terminal to be freed.<br><br><b>-i <I>seconds</I>, --interval <I>seconds</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reports progress at specified time intervals, updating the status of the move.<br><br><b>--atomic</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempts to move all data in one go, without allowing partial completion. Use with caution for large moves as it consumes significant resources.<br><br><b>--abort</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Aborts a currently running or suspended pvmove operation.<br><br><b>--nofsck</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skips filesystem consistency checks. Use with extreme caution as it bypasses critical safeguards and may lead to data corruption if the filesystem is not clean.<br><br><b>--profile <I>profile_name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a configuration profile from the LVM configuration file to the command.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases the verbosity of the command's output, showing more details about the operation.<br><br><b>-y, --yes</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assumes 'yes' to all questions, bypassing interactive prompts and proceeding with the operation automatically.<br><br><b>--noui, -j</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses the interactive user interface for progress reporting, useful for scripting.<br><br>


title: DESCRIPTION
content:
<b>pvmove</b> is a crucial command within the Linux Logical Volume Manager (LVM) suite. It enables administrators to move allocated physical extents from one physical volume (PV) to another within the same volume group (VG). This operation is frequently performed to free up space on a specific PV, remove a PV from a volume group (e.g., before decommissioning a disk), replace a failing physical disk, or rebalance data across PVs for improved performance or redundancy.<br><br>The process involves identifying the extents to be moved and copying them to designated target PVs, updating LVM metadata as it progresses. <b>pvmove</b> can operate on specific logical volumes, specific source PVs, or automatically move all data off an entire PV. Crucially, <b>pvmove</b> can be a long-running operation, especially with large amounts of data, and it is designed to be resumable and safe against system reboots during the move.


title: CAVEATS
content:
Moving data can be a lengthy process (potentially hours or days for large PVs) and may temporarily impact the I/O performance of affected logical volumes. <br>Ensure sufficient free extents on target physical volumes before initiating a move, as insufficient space will cause the operation to fail. <br>While <b>pvmove</b> is designed to be resumable across reboots, it's crucial to ensure system stability during the operation. <br>The <B>--nofsck</B> option should be used with extreme caution as it bypasses critical filesystem checks and could lead to data corruption if the underlying filesystem has issues.


title: PROGRESS MONITORING
content:
During a <b>pvmove</b> operation, progress can be monitored by running <b>pvmove</b> in a separate terminal with the <B>-i</B> or <B>--interval</B> option, or by simply running <B>pvmove</B> without any arguments (which will display the status of any active moves).


title: RESUMING A MOVE
content:
If a <b>pvmove</b> operation is interrupted (e.g., by a system reboot or power failure), it can usually be resumed by simply running <b>pvmove</b> without any source or destination arguments. LVM automatically detects and continues any suspended moves when the command is re-executed.


title: HISTORY
content:
The Logical Volume Manager (LVM) framework, which includes <b>pvmove</b>, has been a core component of Linux storage management since its integration in the 2.4 kernel series. <b>pvmove</b> itself was introduced as a fundamental utility to provide online data migration capabilities, allowing administrators to move data between physical volumes without system downtime. This capability has been crucial for tasks such as decommissioning old disks, replacing failing hardware, or rebalancing storage, evolving alongside the increasing demand for flexible and dynamic storage solutions in enterprise and data center environments.


title: SEE ALSO
content:
lvm(8), pvcreate(8), vgcreate(8), lvcreate(8), vgextend(8), vgreduce(8), pvdisplay(8), vgdisplay(8), lvdisplay(8)


title: PARAMETERS
content:
<b><<i>PhysicalVolume</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the physical volume (e.g., /dev/sdb1) from which to remove LVM metadata.<br><br><b>-f, --force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the removal of LVM metadata, overriding certain checks. Use with extreme caution as it can lead to data loss if the PV is still in use.<br><br><b>-y, --yes</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assumes 'yes' to all prompts, allowing the command to run non-interactively.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Produces more detailed output, showing progress and additional information.<br><br><b>-Z, --zero y/n</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls whether the first 4KB of the device (where LVM metadata resides) should be zeroed out. 'y' (yes) is the default; 'n' leaves the metadata untouched, which is rarely desired for a true 'removal'.<br><br><b>-d, --debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables debug logging for diagnostic purposes.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the LVM2 package version.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints a help message describing the command's usage and options.<br><br><b>--devices <<i>file</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only scan devices listed in the specified file for LVM objects.<br><br><b>--config <<i>string</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Configures LVM by overriding global settings. Can be used multiple times.<br><br><b>--commandprofile <<i>profile_name</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects a command profile to apply custom settings for the command.<br><br>


title: DESCRIPTION
content:
<i>pvremove</i> is a command-line utility used to remove LVM (Logical Volume Manager) metadata from a designated physical volume (PV). A PV is the underlying storage device (e.g., a disk partition or entire disk) that LVM uses. By removing the LVM metadata, <i>pvremove</i> effectively unregisters the device from the LVM system, making it no longer recognizable as an LVM component.<br><br>This command is typically used when decommissioning a physical volume from an LVM setup, for instance, before repurposing the disk for non-LVM use or re-adding it to a new LVM volume group. It is crucial to understand that <i>pvremove</i> only removes the LVM metadata; it does <b>not</b> erase any user data stored on the physical volume. If the PV was part of an active Volume Group (VG) and contained Logical Volumes (LVs) with data, those LVs must first be migrated or removed from the VG using commands like <i>vgreduce</i> before <i>pvremove</i> can be safely used. Forcing the removal of an active PV can lead to severe data loss. It is part of the LVM2 suite of tools.


title: CAVEATS
content:
<b>Data Loss Risk</b>: If the physical volume is still part of an active Volume Group (VG) and contains Logical Volumes (LVs) with data, using <i>pvremove</i> (especially with -f) will lead to severe data loss. Always ensure the PV is removed from its VG using <i>vgreduce</i> <b>before</b> attempting <i>pvremove</i>.<br><b>Metadata Only</b>: <i>pvremove</i> only removes the LVM metadata. It does not wipe or zero out the entire physical volume. Any user data residing on the device will remain, though it will no longer be accessible via LVM.<br><b>Root Privileges</b>: This command requires root (superuser) privileges to execute successfully.


title: TYPICAL USAGE WORKFLOW
content:
When decommissioning an LVM physical volume, the typical workflow involves several steps to ensure data integrity:<br>1. <i>Migrate or Remove Logical Volumes</i>: If the PV contains active Logical Volumes, migrate their data to other PVs in the Volume Group (<i>pvmove</i>) or remove the LVs entirely (<i>lvremove</i>).<br>2. <i>Remove PV from Volume Group</i>: Detach the physical volume from its Volume Group using <b>vgreduce <<i>VolumeGroup</i>> <<i>PhysicalVolume</i>></b>.<br>3. <i>Remove LVM Metadata</i>: Finally, use <b>pvremove <<i>PhysicalVolume</i>></b> to clear the LVM metadata from the device, making it available for other purposes.


title: HISTORY
content:
The <i>pvremove</i> command is an integral part of the Logical Volume Manager (LVM) framework, a flexible disk management system for Linux. LVM was initially developed in the late 1990s, with LVM2 (the current prevalent version) significantly improving upon its predecessor. <i>pvremove</i> has consistently served as the command-line utility for de-registering physical volumes from LVM control, essential for system administrators managing dynamic storage.


title: SYNOPSIS
content:
<b>pvresize</b> [<i>options</i>] <i>physical_volume_path</i>...<br><br>Examples:<br><b>pvresize</b> <i>/dev/sda1</i><br><b>pvresize</b> <i>--setphysicalvolumesize 500G /dev/sdb</i>


title: PARAMETERS
content:
<b><i>physical_volume_path</i>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the physical volume(s) to be resized (e.g., <i>/dev/sda1</i>, <i>/dev/mapper/mpatha</i>). This argument is mandatory.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message and exits.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases the verbosity of the command's output, showing more details about the operation.<br><br><b><b>-t</b>, <b>--test</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables test mode. The command will perform all operations as if it were making changes, but it will not actually write anything to disk.<br><br><b><b>--setphysicalvolumesize</b> <i>size</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly sets the physical volume size to the specified <i>size</i>. This can be used for both expanding and (dangerously) shrinking a PV. Size can include units like 'G' for Gigabytes or 'T' for Terabytes.<br><br><b><b>-y</b>, <b>--yes</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assumes 'yes' to all questions, allowing for non-interactive execution. Use with caution.<br><br><b><b>--zero</b> <i>n|y</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls whether newly allocated space on the physical volume should be zeroed out. 'y' will zero the space, 'n' will not. Default is typically 'y' for safety.<br><br>


title: DESCRIPTION
content:
<i>pvresize</i> is a crucial LVM (Logical Volume Manager) command used to update the size of a physical volume (PV) to reflect changes in its underlying block device. When a disk partition or entire disk, which is used as an LVM physical volume, is resized (typically expanded, e.g., in a virtual machine), the LVM system needs to be informed of this new size. <i>pvresize</i> performs this update, allowing the additional space to be recognized by the volume group (VG) and subsequently used by logical volumes (LVs) built upon it. It is imperative to resize the underlying block device using tools like <i>fdisk</i>, <i>parted</i>, or cloud provider utilities <b>before</b> running <i>pvresize</i>. While primarily used for expansion, it can also shrink a PV, though this is extremely risky and should only be attempted with extreme caution after ensuring no data occupies the space to be removed, as it can lead to data loss.


title: CAVEATS
content:
<b>1. Resize Underlying Device First:</b> <i>pvresize</i> only updates LVM metadata; it does <b>not</b> resize the actual disk partition or block device. You <b>must</b> expand the underlying device using tools like <i>fdisk</i>, <i>parted</i>, or a cloud provider's disk expansion feature <b>before</b> running <i>pvresize</i>.<br><br><b>2. Shrinking a PV is Risky:</b> Shrinking a physical volume is extremely dangerous and can lead to immediate data loss if logical volumes or any data reside in the space being removed. Always back up your data and ensure the space is truly unused before attempting to shrink a PV. <i>pvresize</i> does not relocate or check for data on its own.<br><br><b>3. LVM Metadata Only:</b> This command modifies LVM metadata on the PV. It does not affect the file system residing on any logical volumes built on top of this PV. Further steps (like resizing the logical volume and then the file system) are usually required to make the space usable.


title: FULL LVM RESIZING WORKFLOW (EXPANSION)
content:
To fully expand a file system that resides on a logical volume, the typical sequence of operations is:<br>1.  Expand the underlying disk or partition (e.g., using a virtualization platform, <i>fdisk</i>, or <i>parted</i>).<br>2.  Run <b>pvresize</b> on the physical volume(s) to recognize the new size.<br>3.  Extend the logical volume using <b>lvextend</b> to utilize the newly available space from the PV/VG.<br>4.  Expand the file system on the logical volume (e.g., <b>resize2fs</b> for ext2/3/4, or <b>xfs_growfs</b> for XFS) to make the space accessible to applications.


title: ONLINE OPERATION
content:
<i>pvresize</i> can generally be run on a physical volume even if logical volumes residing on it are active and file systems are mounted. This is because it only modifies LVM metadata and does not directly interact with or unmount file systems. However, other steps in the full resizing workflow (like <i>resize2fs</i>) may require careful consideration depending on the file system type and version.


title: HISTORY
content:
<i>pvresize</i> is an integral component of the Linux Logical Volume Manager (LVM) suite, which has been a cornerstone of flexible storage management on Linux systems since its inception. It was developed to provide the dynamic resizing capabilities essential for modern server and virtualized environments, where storage requirements frequently change without the luxury of system downtime. Its core functionality—updating PV metadata to reflect underlying block device size changes—has remained a stable and critical feature within LVM's evolution.


title: SEE ALSO
content:
pvcreate(8), pvdisplay(8), vgextend(8), vgreduce(8), lvextend(8), lvreduce(8), fdisk(8), parted(8), resize2fs(8), xfs_growfs(8)


title: PARAMETERS
content:
<b><b>-o</b> <i>field</i>[,<i>field</i>...], <b>--options</b> <i>field</i>[,<i>field</i>...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies which information <i>fields</i> to display. Common fields include <i>pv_name</i>, <i>vg_name</i>, <i>pv_size</i>, <i>pv_free</i>, <i>pv_attr</i>, etc.<br><br><b><b>-a</b>, <b>--all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays information about all physical volumes, including those that are not yet assigned to a volume group.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides more detailed output regarding the physical volumes.<br><br><b><b>--noheadings</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses the display of column headings in the output, useful for scripting.<br><br><b><b>--units</b> <i>unit</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the units for displayed sizes. Examples include <i>b</i> (bytes), <i>k</i> (kilobytes), <i>m</i> (megabytes), <i>g</i> (gigabytes), etc.<br><br><b><b>--separator</b> <i>string</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses a custom string as a field separator for easier parsing, especially when used with <b>-o</b>.<br><br>


title: DESCRIPTION
content:
The <b>pvs</b> command is a fundamental utility within the Linux Logical Volume Manager (LVM) framework. It is used to display comprehensive information about <i>physical volumes</i> (PVs). A physical volume represents a disk or disk partition that has been initialized for use by LVM. <br><br><b>pvs</b> provides crucial details such as the PV's device path (e.g., <i>/dev/sdb1</i>), its unique identifier (UUID), the volume group (VG) it belongs to (if any), its total capacity (size), the amount of free space remaining on it, and its current status (e.g., <i>allocatable</i> or <i>missing</i>). This command is indispensable for system administrators to monitor the health and allocation status of their storage infrastructure, assist in troubleshooting LVM-related issues, and plan for storage expansion or modifications. It supports various options for filtering, sorting, and customizing the output format.


title: CAVEATS
content:
To ensure accurate and complete information, <b>pvs</b> typically requires root privileges. It specifically focuses on disks or partitions that have been initialized as LVM physical volumes and will not display information for uninitialized raw disk partitions or filesystems not managed by LVM.<br>While powerful, interpreting extensive output without specific options like <b>-o</b> or <b>--noheadings</b> can sometimes be challenging, especially for scripting purposes.


title: OUTPUT FIELDS
content:
<b>pvs</b> can display a wide range of information about physical volumes. When using the <b>-o</b> option, you can select specific fields such as <i>pv_uuid</i>, <i>pv_attr</i> (attributes like allocatable/exported), <i>pv_size</i>, <i>pv_used</i>, <i>pv_free</i>, <i>pv_alloc_le</i> (allocated extents), and <i>pe_start</i> (physical extent start).


title: FILTERING OUTPUT
content:
By providing specific <i>PhysicalVolumePath</i>, <i>VolumeGroupName</i>, or <i>LogicalVolumeName</i> arguments after the options, you can filter the output to show information only for relevant PVs. For example, <i>pvs /dev/sdb1</i> will show details only for that specific physical volume.


title: HISTORY
content:
The Logical Volume Manager (LVM) framework, which includes <b>pvs</b>, was initially developed for Linux around 1998/1999. The original LVM (often called LVM1) laid the groundwork for flexible storage management. LVM2, a significant rewrite, was introduced to address limitations of LVM1, offering enhanced performance, scalability, and stability. <b>pvs</b> has been a consistent and core utility throughout LVM's evolution, providing administrators with a standardized way to inspect the status of their physical volumes.


title: PARAMETERS
content:
<b>--devices <i><path></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies device(s) to scan. Using this limits scanning only to the specified paths, improving efficiency.<br><br><b>-u, --uuid</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the Universal Unique Identifier (UUID) of physical volumes in the output.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases the verbosity level of the output, showing more details about the scanning process.<br><br><b>-q, --quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses non-essential output, useful for scripting or when only errors are of interest.<br><br><b>-P, --partial</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows the command to process physical volumes even if their LVM metadata is only partially available or corrupt.<br><br><b>-S, --select <i><selection></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects physical volumes based on specific criteria for reporting. This allows filtering PVs based on attributes like size, UUID, or belonging to a specific volume group.<br><br><b>-o, --options <i><fields></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a comma-separated list of fields to display in the output, allowing for custom reporting (e.g., <i>pv_name,pv_size,vg_name</i>).<br><br><b>--reportformat <i><format></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output format for the report, such as <i>json</i> or <i>json+cols</i>, enabling programmatic parsing of the output.<br><br>


title: DESCRIPTION
content:
The <b>pvscan</b> command is an essential component of the Logical Volume Manager (LVM) suite in Linux. Its primary function is to scan all block devices on the system for LVM physical volumes (PVs).<br><br>When executed, <b>pvscan</b> reads the metadata on these devices to identify any existing PVs. It then builds an in-memory list of these discovered LVM metadata areas. This list is crucial for other LVM commands (like <b>vgscan</b> or <b>lvscan</b>) to operate correctly, as they rely on <b>pvscan</b> to locate and understand the LVM structure across the system's storage.<br><br><b>pvscan</b> is often run during system boot to ensure that LVM structures are properly recognized and accessible. It helps in detecting new physical volumes or refreshing the LVM's understanding of the current storage layout, especially after hardware changes or disk additions. Its output typically provides information about the PVs found, including their device paths, unique identifiers (UUIDs), and the volume groups they belong to.


title: CAVEATS
content:
Running <b>pvscan</b> without any options will scan <i>all</i> available block devices, which can be time-consuming on systems with many disks or slow storage. It's primarily a scanning tool; it does not make changes to the LVM metadata or activate/deactivate volume groups or logical volumes directly (though some related options can influence activation behavior during a scan). Always ensure LVM tools are updated for compatibility with the latest LVM metadata formats.


title: METADATA SCANNING
content:
<b>pvscan</b> primarily focuses on finding and reading LVM metadata headers located on block devices. These headers contain essential information about the physical volume, including its UUID, size, and which volume group it belongs to. Without this metadata, other LVM commands cannot correctly identify or manage the physical volume.


title: INTEGRATION WITH SYSTEM STARTUP
content:
On many Linux distributions, <b>pvscan</b> (or equivalent LVM initialization steps) is automatically executed during system boot. This ensures that the LVM framework is aware of all physical volumes and their associated volume groups and logical volumes before higher-level services or user applications attempt to access them.


title: HISTORY
content:
The <b>pvscan</b> command is an integral part of the original LVM (Logical Volume Manager) framework, which was first introduced in Linux kernel 2.4. Developed to provide flexible disk space management, LVM allows for dynamic resizing of partitions and easier volume management. <b>pvscan</b> has been a core utility since the early days of LVM, responsible for discovering the foundational physical volume components that make up LVM's storage hierarchy. Its functionality has remained consistent, evolving mainly with the addition of more sophisticated filtering, output formatting, and error handling options.


title: SYNOPSIS
content:
pw-cat [<i>OPTIONS</i>] [<i>FILENAME</i>]<br>Where <i>FILENAME</i> can be an input file for playback or an output file for recording.


title: PARAMETERS
content:
<b><i>-h</i>, <i>--help</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display help information and exit.<br><br><b><i>--version</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show program version.<br><br><b><i>-p</i>, <i>--playback</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable playback mode to a PipeWire sink (default if no <i>-r</i> is used).<br><br><b><i>-r</i>, <i>--record</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable recording mode from a PipeWire source.<br><br><b><i>-R</i>, <i>--loop</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Loop playback indefinitely. (Playback mode only)<br><br><b><i>-m</i>, <i>--monitor</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Record from a monitor output of a source. (Recording mode only)<br><br><b><i>-v</i>, <i>--verbose</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increase verbosity of output.<br><br><b><i>-P</i>, <i>--properties=PROPERTIES</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set stream properties as a key=value string (e.g., "node.target=my_sink").<br><br><b><i>-l</i>, <i>--latency=LATENCY</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set stream latency (e.g., "100ms", "4/48000").<br><br><b><i>-d</i>, <i>--driver=DRIVER</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force a specific driver for the stream.<br><br><b><i>-q</i>, <i>--quality=QUALITY</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set audio quality parameters (e.g., "rate=48000", "channels=2").<br><br><b><i>-i</i>, <i>--input=FILENAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly specify the input audio file.<br><br><b><i>-o</i>, <i>--output=FILENAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly specify the output audio file.<br><br><b><i>-s</i>, <i>--server=SERVER</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connect to a specific PipeWire server.<br><br><b><i>-n</i>, <i>--name=NAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the client application name for PipeWire.<br><br><b><i>--raw</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Treat audio data as raw PCM (no WAV header).<br><br><b><i>--rate=RATE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the sample rate in Hz (e.g., 48000). Implies <i>--raw</i> if no format is specified.<br><br><b><i>--channels=CHANNELS</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the number of audio channels (e.g., 2 for stereo). Implies <i>--raw</i> if no format is specified.<br><br><b><i>--format=FORMAT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the sample format (e.g., s16le, f32le). Implies <i>--raw</i>.<br><br><b><i>--volume=VOLUME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the playback/recording volume (0.0 to 1.0).<br><br><b><i>--target=TARGET</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the target node (sink or source) by name.<br><br>


title: DESCRIPTION
content:
<i>pw-cat</i> is a command-line utility for playing and recording audio streams through the PipeWire sound server. It operates similarly to the standard <i>cat</i> command, but designed for audio data. Users can specify an input <i>FILENAME</i> for playback or an output <i>FILENAME</i> for recording. If no filename is provided, <i>pw-cat</i> defaults to reading audio from standard input (<i>stdin</i>) and writing it to standard output (<i>stdout</i>), making it highly versatile for piping audio data between processes.<br><br>It supports various audio formats, including raw PCM and WAV files, and offers numerous options to control parameters such as sample rate, number of channels, audio format, latency, and specific target audio devices. This tool is part of the <i>pipewire-utils</i> package and is engineered for low-latency audio operations within the PipeWire ecosystem.


title: CAVEATS
content:
Requires a running PipeWire daemon. When using <i>stdin</i>/<i>stdout</i> for raw audio, parameters like <i>--rate</i>, <i>--channels</i>, and <i>--format</i> are crucial, as <i>pw-cat</i> cannot infer these from a WAV header. The <i>FILENAME</i> argument is positional and can be ambiguous without <i>--input</i> or <i>--output</i> flags if you want to explicitly define source/destination when stdin/stdout is not intended.


title: STANDARD I/O BEHAVIOR
content:
When no <i>FILENAME</i> is specified, <i>pw-cat</i> reads audio data from standard input (<i>stdin</i>) and writes it to standard output (<i>stdout</i>). This behavior allows it to be easily integrated into shell pipelines, processing or generating audio streams on the fly. For raw audio through <i>stdin</i>/<i>stdout</i>, it's essential to explicitly define audio parameters such as <i>--rate</i>, <i>--channels</i>, and <i>--format</i>.


title: DEFAULT MODES
content:
By default, <i>pw-cat</i> operates in <b>playback</b> mode unless the <i>-r</i> (record) option is explicitly used. This means if a <i>FILENAME</i> is provided, it will play the audio from that file. If no <i>FILENAME</i> is given and <i>-r</i> is not used, it will attempt to play audio from standard input (<i>stdin</i>).


title: HISTORY
content:
<i>pw-cat</i> is a relatively recent addition to the Linux audio landscape, emerging as part of the PipeWire project. PipeWire itself was developed to address limitations of existing audio (PulseAudio, JACK) and video (V4L2, GStreamer) infrastructures, aiming for a unified, low-latency multimedia graph. <i>pw-cat</i> simplifies basic audio I/O, providing a familiar <i>cat</i>-like interface for developers and users working with PipeWire streams, often used in scripting or for quick tests alongside other command-line tools. Its development parallels the growth and adoption of PipeWire as a modern audio and video server.


title: SYNOPSIS
content:
<b>pw-cli</b> [<I>OPTIONS</I>] [<I>COMMAND</I>] [<I>ARGUMENTS</I>]<br><br>Common <b>OPTIONS</b>:<br>&nbsp;&nbsp;<code><I>-h</I></code>, <code><I>--help</I></code><br>&nbsp;&nbsp;<code><I>-v</I></code>, <code><I>--version</I></code><br>&nbsp;&nbsp;<code><I>-r NAME</I></code>, <code><I>--remote=NAME</I></code><br><br>Common <b>COMMANDS</b>:<br>&nbsp;&nbsp;<code><I>info</I></code><br>&nbsp;&nbsp;<code><I>nodes</I></code><br>&nbsp;&nbsp;<code><I>links</I></code><br>&nbsp;&nbsp;<code><I>connect</I></code><br>&nbsp;&nbsp;<code><I>disconnect</I></code>


title: PARAMETERS
content:
<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;Show version information and exit.<br><br><b>-r, --remote=NAME</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connect to a specific PipeWire remote daemon instance by name.<br><br><b>-l, --list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;List information in a compact format without detailed properties.<br><br><b>-c, --command=COMMAND</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Execute a single command and exit, without entering interactive mode.<br><br><b>-m, --monitor</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Monitor and print events from the PipeWire daemon in real-time.<br><br><b>-P, --playback</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Start an interactive playback shell (legacy mode for specific tests).<br><br><b>-V, --record</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Start an interactive record shell (legacy mode for specific tests).<br><br><b>help [COMMAND]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display help for <b>pw-cli</b> or a specific command (e.g., <code><I>help nodes</I></code>).<br><br><b>quit</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exit the <b>pw-cli</b> interactive shell.<br><br><b>info [ID]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display detailed information about all PipeWire objects or a specific object by its numeric ID.<br><br><b>nodes</b><br>&nbsp;&nbsp;&nbsp;&nbsp;List all active PipeWire nodes (processing units).<br><br><b>links</b><br>&nbsp;&nbsp;&nbsp;&nbsp;List all active PipeWire links (connections between ports).<br><br><b>devices</b><br>&nbsp;&nbsp;&nbsp;&nbsp;List all PipeWire devices (hardware abstractions).<br><br><b>clients</b><br>&nbsp;&nbsp;&nbsp;&nbsp;List all connected PipeWire clients (applications).<br><br><b>ports</b><br>&nbsp;&nbsp;&nbsp;&nbsp;List all active PipeWire ports (connection points on nodes).<br><br><b>connect ID_OUT ID_IN</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connect an output port (ID_OUT) to an input port (ID_IN).<br><br><b>disconnect ID_LINK</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disconnect a specific PipeWire link by its ID.<br><br><b>create-node NAME</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Create a new PipeWire test node (e.g., <code><I>test-sink</I></code>, <code><I>test-source</I></code>).<br><br><b>enum-params ID [PARAM]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enumerate parameters of an object by its ID, optionally filtering by parameter name.<br><br><b>set-param ID PARAM_DATA</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set parameters for an object by ID using a JSON string or key=value properties string.<br><br><b>parse-info TEXT</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Parse PipeWire info data from TEXT (primarily for scripting and internal use).<br><br><b>log-level LEVEL</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the PipeWire daemon's log level (0-3 for error, info, debug, trace messages).<br><br><b>load-module NAME [ARGUMENTS]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Load a PipeWire module (e.g., <code><I>libpipewire-module-loopback</I></code>) with optional arguments.<br><br><b>unload-module ID</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Unload a PipeWire module by its numeric ID.<br><br>


title: DESCRIPTION
content:
<b>pw-cli</b> is a versatile command-line tool designed for inspecting and managing the PipeWire multimedia server. It allows users to gain deep insights into the PipeWire graph, including active nodes, links, devices, clients, and ports. This tool is invaluable for debugging PipeWire setups, understanding how audio and video streams flow, and for advanced configuration and control. It can be used to manually connect and disconnect graph objects, load or unload modules, and query detailed properties of any PipeWire object. While primarily a diagnostic and administrative utility for developers and power users, <b>pw-cli</b> also serves as a scripting interface for automating PipeWire interactions.


title: CAVEATS
content:
Requires the PipeWire daemon to be running for full functionality. <br> The output can be very verbose, especially for complex graphs, necessitating piping to `grep` or `less`. <br> Understanding PipeWire's graph model (nodes, ports, links) is essential for effective use. <br> <b>pw-cli</b> is primarily a power-user and developer tool; casual users might find simpler graphical frontends like `qpwgraph` more suitable.


title: INTERACTIVE VS. NON-INTERACTIVE MODE
content:
<code><I>pw-cli</I></code> can be used in two main modes: <br> 1. <b>Interactive shell:</b> Running <code><I>pw-cli</I></code> without arguments drops you into an interactive prompt where you can execute multiple commands sequentially. <br> 2. <b>Non-interactive (one-shot):</b> Using the <code><I>-c</I></code> or <code><I>--command</I></code> option executes a single command and immediately exits, which is useful for scripting and automation.


title: PIPEWIRE OBJECT TYPES
content:
<code><I>pw-cli</I></code> interacts with various PipeWire object types, each identified by a unique numeric ID: <br> <b>Nodes:</b> Represent processing units, such as applications (e.g., Firefox, MPV) or hardware devices (e.g., sound cards, webcams). <br> <b>Ports:</b> Connection points on nodes, categorized as input or output, which allow data to flow between nodes. <br> <b>Links:</b> Direct connections established between an output port and an input port. <br> <b>Devices:</b> Abstract representations of physical or virtual hardware components controlled by PipeWire. <br> <b>Clients:</b> Applications or services connected to the PipeWire daemon that interact with the graph. <br> Each object has properties and parameters that can be queried and sometimes modified using commands like <code><I>info</I></code>, <code><I>enum-params</I></code>, and <code><I>set-param</I></code>.


title: HISTORY
content:
<code><I>pw-cli</I></code> is an integral part of the PipeWire project, which emerged as a modern multimedia framework for Linux, aiming to supersede and unify functionalities previously handled by PulseAudio (for audio) and JACK (for professional audio), as well as provide robust video stream management. PipeWire was initially developed by Wim Taymans at Red Hat, with its first stable release in 2020. <code><I>pw-cli</I></code> was designed from the outset as the primary command-line interface for direct interaction with the PipeWire daemon, essential for debugging, scripting, and advanced system administration tasks related to multimedia.


title: PARAMETERS
content:
<b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message and exits.<br><br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the PipeWire version and exits.<br><br><br><b><b>-a</b>, <b>--all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with the <i>list</i> command to show all available configuration files, including those not yet installed.<br><br><br><b><b>-p</b>, <b>--path</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the full path to configuration files when used with <i>list</i> or <i>show</i> commands.<br><br><br><b><b>-n</b>, <b>--name</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays only the base name of configuration files when used with <i>list</i>.<br><br><br><b><b>-s</b>, <b>--system</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Operates on system-wide configuration files (typically in <i>/etc/pipewire/</i>). Requires superuser privileges for installation.<br><br><br><b><b>-u</b>, <b>--user</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Operates on user-specific configuration files (typically in <i>~/.config/pipewire/</i>). This is often the default behavior.<br><br><br><b><b>-t</b> <i>&lt;directory&gt;</i>, <b>--target</b> <i>&lt;directory&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative target directory for <i>install</i> or <i>uninstall</i> commands. Overrides default user or system paths.<br><br><br><b><i>COMMANDS</i>:</b><br>&nbsp;&nbsp;&nbsp;&nbsp;These are positional arguments that define the action to perform on configuration files.<br><br><br><b><b>install</b> [<i>&lt;file&gt;</i>...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Copies specified (or all, if none specified) default PipeWire configuration files to the target directory.<br><br><br><b><b>uninstall</b> [<i>&lt;file&gt;</i>...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes specified (or all, if none specified) PipeWire configuration files from the target directory.<br><br><br><b><b>list</b> [<i>&lt;file&gt;</i>...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists available or currently installed PipeWire configuration files, potentially filtered by name.<br><br><br><b><b>show</b> <i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the content of a specified PipeWire configuration file.<br><br><br>


title: DESCRIPTION
content:
The <b>pw-config</b> command is a utility provided with the PipeWire multimedia framework. It simplifies the management of PipeWire configuration files by allowing users to easily <i>install</i>, <i>uninstall</i>, <i>list</i>, and <i>show</i> various configuration settings.<br><br>PipeWire is a low-latency multimedia graph framework that aims to provide a unified solution for handling audio, video, and hardware streams on Linux. <b>pw-config</b> helps users customize their PipeWire setup without directly modifying system-wide defaults, typically by copying default configuration files from system locations (e.g., <i>/usr/share/pipewire/</i>) to user-editable directories (e.g., <i>~/.config/pipewire/</i> or <i>/etc/pipewire/</i>). This enables individual users or system administrators to fine-tune PipeWire's behavior for specific hardware, applications, or performance requirements.


title: CAVEATS
content:
<b>pw-config</b> requires the <i>PipeWire</i> multimedia framework to be installed on the system.<br>Modifying PipeWire configuration files can significantly impact audio and video routing, device behavior, and system performance. Exercise caution and back up configurations before making major changes.<br>The <b>uninstall</b> command only removes files that <b>pw-config</b> previously installed. It will not remove manually created or modified files that were not originally sourced by <b>pw-config</b>.<br>When using <b>--system</b>, administrative privileges (e.g., <i>sudo</i>) are typically required for <i>install</i> and <i>uninstall</i> operations.<br>


title: CONFIGURATION FILE STRUCTURE
content:
PipeWire configuration files are typically written in a JSON-like format or in a format parsed by <i>libspa-json</i>, controlling various aspects such as loaded modules, device profiles, stream routing, and performance parameters. Common file types include <i>.conf</i> for main configuration, <i>.modules</i> for loaded SPA (Simple Plugin API) modules, and <i>.rules</i> for conditional logic.<br>


title: TYPICAL USAGE
content:
A common use case for <b>pw-config</b> is to copy the default PipeWire configuration for a user: <i>pw-config install</i>. Users can then edit these files in <i>~/.config/pipewire/</i> to customize their setup, ensuring that system updates to the default configurations in <i>/usr/share/pipewire/</i> do not overwrite their personal settings.<br>


title: HISTORY
content:
<b>pw-config</b> emerged as part of the <i>PipeWire</i> project, which began development around 2017 to address shortcomings of existing Linux audio/video frameworks (like PulseAudio and JACK) and provide a modern solution for media processing. As PipeWire gained adoption and became a default component in major Linux distributions, utilities like <b>pw-config</b> were developed to simplify the often complex task of managing its configuration, making it more user-friendly for both end-users and system administrators to customize their multimedia environments.


title: PARAMETERS
content:
<b><b>-o FILE</b>, <b>--output=FILE</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Write output to FILE instead of standard output.<br><br><b><b>-q</b>, <b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress diagnostic output.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display help and exit.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display version and exit.<br><br>


title: DESCRIPTION
content:
<b>pw-dot</b> is a utility designed to visualize password generation rules, typically those used by the <b>pass-gen</b> program.<br><br>It reads a specified file containing these rules and translates them into a Graphviz DOT file. This DOT file describes a directed graph, where nodes represent states or elements in the password generation process and edges represent transitions or conditions. Users can then process this <i>.dot</i> file using Graphviz tools, such as <b>dot(1)</b>, to render it into various image formats (e.g., PNG, SVG, PDF). This visualization helps in understanding the complexity, structure, and potential entropy sources of the defined password generation rules, aiding in auditing or designing secure password schemes. It makes the often-abstract rules tangible and inspectable.


title: CAVEATS
content:
The <b>pw-dot</b> command does not directly generate images; its output is a Graphviz DOT file. To visualize the rules, a separate Graphviz utility like <b>dot(1)</b> is required to convert the DOT file into a graphical format (e.g., PNG, SVG).<br><br>Additionally, <b>pw-dot</b> expects its input file to conform to the specific rule format used by the <b>pass-gen</b> program, limiting its applicability to other password generation schemes.


title: INPUT FILE FORMAT
content:
<b>pw-dot</b> expects an input file that describes password generation rules. This file typically defines character sets, sequences, and constraints. Its format is specific to the <b>pass-gen</b> project.


title: GRAPHVIZ INTEGRATION
content:
The primary purpose of <b>pw-dot</b> is to generate a <i>.dot</i> file, which is a plain text graph description language. This output is then fed into Graphviz tools (e.g., <b>dot</b>, <b>neato</b>, <b>fdp</b>) to render the graph. For example: <i>pw-dot rules.conf | dot -Tpng > rules_graph.png</i>


title: HISTORY
content:
<b>pw-dot</b> is part of the <b>pass-gen</b> project, which focuses on flexible and auditable password generation based on defined rules. Its development is intertwined with the <b>pass-gen</b> tool itself, providing a crucial debugging and understanding utility for the rule sets.<br><br>It emerged as a way to demystify complex password generation logic by providing a visual representation of the underlying state machine or rules. While its specific history might not be extensively documented as a standalone tool, it serves as an important component for users and developers working with <b>pass-gen</b>'s advanced rule capabilities.


title: PARAMETERS
content:
<b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show help options and exit.<br><br><b>-o, --output-file=<I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Direct the output to the specified <I>FILE</I> instead of standard output (stdout).<br><br><b>-N, --no-colors</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable colorized output, if applicable (output is typically non-colored by default).<br><br><b>-m, --monitor</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Monitor for changes in the PipeWire graph and continuously dump new or updated information as it occurs.<br><br><b>-a, --full-dump</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform a full dump, including all objects and details that might be omitted in a default, concise dump.<br><br><b>-i, --id=<I>ID</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Dump only the object with the specified <I>ID</I> (PipeWire object identifier).<br><br>


title: DESCRIPTION
content:
<b>pw-dump</b> is a powerful diagnostic tool for the <i>PipeWire</i> media server. It provides a comprehensive snapshot of the current state of the <i>PipeWire</i> daemon and its active objects, including nodes, ports, links, devices, and metadata. The output is typically presented in <i>JSON</i> format, making it easy to parse and analyze programmatically or inspect manually.<br><br>This utility is invaluable for debugging audio and video routing issues, understanding the intricate connections within the <i>PipeWire</i> graph, and verifying the configuration of sources, sinks, and processing modules. It allows users and developers to gain deep insights into how media streams are managed and processed by <i>PipeWire</i>, aiding in troubleshooting and development efforts.


title: CAVEATS
content:
<ul><li>Requires a running <i>PipeWire</i> daemon to function correctly.</li><li>The output can be very large and verbose, especially for complex systems or when using the <b>--full-dump</b> option.</li><li>Interpreting the <i>JSON</i> output requires familiarity with <i>PipeWire</i>'s internal object model and graph structure.</li><li>The user running <b>pw-dump</b> must have appropriate permissions to connect to the <i>PipeWire</i> socket.</li></ul>


title: OUTPUT FORMAT
content:
The primary output format of <b>pw-dump</b> is <i>JSON</i>. This structured output typically contains an array of objects representing various <i>PipeWire</i> components (e.g., devices, nodes, ports, links, factories, modules, metadata). This machine-readable format is ideal for scripting, automated analysis, and integration into other diagnostic tools.


title: DEBUGGING AND TROUBLESHOOTING
content:
<b>pw-dump</b> is an essential utility for debugging and troubleshooting audio and video issues on systems utilizing <i>PipeWire</i>. By providing a detailed view of the media graph, it helps identify misconfigurations, analyze data flow paths, and diagnose problems related to audio/video routing, device connectivity, and application interaction with the <i>PipeWire</i> daemon.


title: HISTORY
content:
<i>PipeWire</i>, and consequently its associated tools like <b>pw-dump</b>, emerged as a modern multimedia framework for Linux, aiming to handle audio, video, and hardware access more efficiently than previous systems. Its development began around 2017 with an initial focus on Wayland screen sharing, eventually expanding to encompass professional audio and replace existing solutions like <i>PulseAudio</i> and <i>JACK</i>. <b>pw-dump</b> has been an integral part of the <i>PipeWire</i> debugging toolkit since its early stages, evolving with the framework to provide increasingly detailed insights into its internal operations and assist developers and users in understanding the system's state.


title: SYNOPSIS
content:
<b>pw-link</b> [<i>OPTIONS</i>] [<i>SOURCE_ID/NAME</i>] [<i>SINK_ID/NAME</i>]<br><b>pw-link -l</b> [<i>OPTIONS</i>]<br><b>pw-link -d</b> <i>LINK_ID</i>


title: PARAMETERS
content:
<b><b>-l</b>, <b>--list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>List all available PipeWire nodes and their ports.</i><br><br><b><b>-i</b>, <b>--input</b> <i>&lt;ID/NAME&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specify the input port for a connection.</i><br><br><b><b>-o</b>, <b>--output</b> <i>&lt;ID/NAME&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specify the output port for a connection.</i><br><br><b><b>-p</b>, <b>--passive</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Create a passive link. Passive links do not cause the source node to activate the sink node.</i><br><br><b><b>-d</b>, <b>--disconnect</b> <i>&lt;ID&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Disconnect a specific link by its ID.</i><br><br><b><b>-m</b>, <b>--monitor</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Monitor link changes in real-time, printing events as they occur.</i><br><br><b><b>-P</b>, <b>--playback</b> <i>&lt;ID/NAME&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Alias for <b>--output</b>, typically used for playback streams.</i><br><br><b><b>-R</b>, <b>--record</b> <i>&lt;ID/NAME&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Alias for <b>--input</b>, typically used for record streams.</i><br><br><b><b>-L</b>, <b>--linger</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Keep the link active after <b>pw-link</b> exits, even if the parent terminal is closed.</i><br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Show help message and exit.</i><br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Show version information and exit.</i><br><br><b><i>SOURCE_ID/NAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>The ID or name of the source node or port (output) for a connection.</i><br><br><b><i>SINK_ID/NAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>The ID or name of the sink node or port (input) for a connection.</i><br><br>


title: DESCRIPTION
content:
<i>pw-link</i> is a command-line utility used to manage <i>links</i> between <i>nodes</i> and <i>ports</i> within the <a href="https://pipewire.org">PipeWire</a> multimedia server. PipeWire is a low-latency multimedia graph server designed to handle audio and video streams efficiently on Linux systems, aiming to unify functionalities previously covered by PulseAudio and JACK Audio Connection Kit.<br><br>The primary function of <i>pw-link</i> is to establish and remove connections, allowing audio or video data to flow from an output port of one node to an input port of another. This is crucial for routing signals between applications, hardware devices, and virtual processors within the PipeWire ecosystem. For instance, you can use <i>pw-link</i> to connect the output of a music player to the input of a recording application, or route microphone input to a specific conferencing tool.<br><br>It operates by identifying nodes and ports using their unique numeric IDs or names. Users typically first list available nodes and ports with <i>pw-link -l</i> or <i>pw-cli ls</i> to identify the desired connection points, and then use <i>pw-link</i> with source and sink IDs to create the link. This provides a powerful, scriptable way to configure complex audio/video routing setups.


title: CAVEATS
content:
<i><b>pw-link</b> requires the PipeWire daemon to be running. Node and port IDs are dynamic and can change between PipeWire daemon restarts or system reboots, making scripts using hardcoded IDs potentially brittle. It is recommended to use node/port names where possible, or combine with <b>pw-cli ls</b> to dynamically resolve IDs. Understanding PipeWire's graph model is beneficial for effective use.</i>


title: <B>IDENTIFYING NODES AND PORTS</B>
content:
<i>Before creating a link, you often need to identify the numeric IDs or names of the desired source (output) and sink (input) ports. This can be done using <b>pw-link -l</b>, which lists all active nodes and their associated ports, or <b>pw-cli ls</b> for a more detailed overview of all PipeWire objects.</i>


title: <B>ACTIVE VS. PASSIVE LINKS</B>
content:
<i>By default, <b>pw-link</b> creates active links. An active link ensures that the source node activates the sink node when data is present. A passive link (created with <b>-p</b> or <b>--passive</b>) does not cause the source node to activate the sink. Passive links are useful when the sink node is already active for other reasons or managed externally.</i>


title: HISTORY
content:
<i><b>pw-link</b> is an integral part of the <a href="https://pipewire.org">PipeWire</a> project, initiated by Wim Taymans (Red Hat) around 2017. PipeWire was developed to provide a modern, secure, and performant multimedia framework for Linux, addressing limitations found in existing systems like JACK and PulseAudio. <b>pw-link</b> specifically emerged as the command-line tool to manage the fundamental concept of "links" within PipeWire's graph architecture, enabling dynamic audio/video routing capabilities essential for both desktop and professional audio/video workflows. Its design reflects the need for a programmatic way to control media streams without reliance on graphical tools.</i>


title: PARAMETERS
content:
<b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message with available options.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the version information of the <b>pw-loopback</b> utility.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose logging, providing more detailed output for debugging purposes.<br><br><b><b>-t</b>, <b>--latency</b> <I>latency</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the target latency for the loopback device in milliseconds (ms). A lower value generally means lower latency but might require more CPU resources.<br><br><b><b>-n</b>, <b>--name</b> <I>name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a custom name for the created PipeWire node. This name will appear in tools like <b>pw-cli</b> or graphical PipeWire graph viewers.<br><br><b><b>--media-type</b> <I>media-type</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the type of media stream to loop back. Possible values include <i>audio</i> or <i>video</i>. Mutually exclusive with <b>--audio</b> and <b>--video</b> if only one type is desired.<br><br><b><b>--audio</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Configures the loopback for audio streams. This is often the default or explicitly used for audio-only scenarios.<br><br><b><b>--video</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Configures the loopback for video streams. This is used for video-only scenarios.<br><br><b><b>--rate</b> <I>rate</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the sample rate (e.g., 48000, 44100) for audio streams. Only applicable for audio loopbacks.<br><br><b><b>--channels</b> <I>channels</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the number of audio channels (e.g., 1 for mono, 2 for stereo). Only applicable for audio loopbacks.<br><br><b><b>--format</b> <I>format</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the sample format for audio streams (e.g., <i>S16</i> for 16-bit signed integer, <i>F32</i> for 32-bit float). Only applicable for audio loopbacks.<br><br><b><b>--target</b> <I>node_id</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the PipeWire node ID from which the loopback should capture audio/video. This is the 'input' to the loopback, usually a sink (playback) node.<br><br><b><b>--source</b> <I>node_id</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the PipeWire node ID to which the loopback should output audio/video. This is the 'output' from the loopback, usually a source (capture) node.<br><br><b><b>--monitor</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When used with <b>--target</b>, the loopback will monitor (listen to) the target node without consuming its stream, allowing the original stream to continue to its default destination. Useful for non-intrusive monitoring.<br><br><b><b>--playback</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates playback (sink) nodes that applications can use as an output. Useful when you want the loopback to act as an application's output device, routing its content somewhere else.<br><br><b><b>--record</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates record (source) nodes that applications can use as an input. Useful when you want the loopback to act as an application's input device, receiving content from somewhere else.<br><br><b><b>--input</b> <I>node_id</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Alias for <b>--target</b>. Specifies the input node ID for the loopback.<br><br><b><b>--output</b> <I>node_id</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Alias for <b>--source</b>. Specifies the output node ID for the loopback.<br><br><b><b>--capture</b> <I>node_id</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Another alias for <b>--target</b>. Specifies the capture node ID for the loopback.<br><br><b><b>--play</b> <I>node_id</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Another alias for <b>--source</b>. Specifies the play node ID for the loopback.<br><br>


title: DESCRIPTION
content:
The <b>pw-loopback</b> command is a utility provided by the PipeWire multimedia server. It creates a virtual loopback device that routes audio or video streams from a specified PipeWire <i>sink</i> (output) to a <i>source</i> (input), or vice versa. This is invaluable for various audio/video processing and monitoring tasks, such as capturing output from an application and feeding it into another, recording system audio, or performing real-time effects processing without requiring physical connections.<br><br>Essentially, it acts as a digital patch cable, enabling applications to interact with their own output or the output of other applications in a seamless and efficient manner within the PipeWire graph. It can be configured for specific media types (audio, video) and formats, offering fine-grained control over the loopback connection.


title: CAVEATS
content:
Using <b>pw-loopback</b> can introduce a small amount of latency, which might be noticeable in very sensitive real-time audio applications. Resource consumption (CPU/memory) will increase with more loopbacks or higher quality/resolution streams. It relies on a running PipeWire daemon; without it, the command will fail. Proper understanding of PipeWire's node and link management is beneficial for effective use, often in conjunction with <b>pw-cli</b>.


title: USAGE SCENARIOS
content:
<b>System Audio Recording:</b> Easily record all system sounds or specific application audio output.<br><br><b>Audio Monitoring:</b> Listen to the output of an application without interrupting its normal audio flow using the <b>--monitor</b> option.<br><br><b>Real-time Effects Processing:</b> Route audio from one application through an effects processor (another application) and then back into a recording or playback application.<br><br><b>Application Interoperability:</b> Connect applications that don't natively support each other's audio/video formats or protocols by using <b>pw-loopback</b> as an intermediary.


title: HISTORY
content:
<b>pw-loopback</b> is an integral part of the PipeWire project, which emerged as a modern multimedia server for Linux, aiming to unify audio (PulseAudio, JACK) and video handling. Developed with a focus on low-latency and efficient media routing, <b>pw-loopback</b> was designed to be a core utility from PipeWire's early stages, providing essential capabilities for inter-application communication and system audio/video management that were previously more cumbersome with older systems.


title: SYNOPSIS
content:
<b><code>pw-metadata</code></b> [<i>OPTIONS</i>] <i>COMMAND</i> [<i>ARGUMENTS...</i>]<br><br><b>Commands:</b><br>&nbsp;&nbsp;<b><code>ls</code></b> [<i>OBJECT_ID</i>]<br>&nbsp;&nbsp;<b><code>set</code></b> <i>OBJECT_ID KEY VALUE</i> [<i>TYPE</i>]<br>&nbsp;&nbsp;<b><code>clear</code></b> <i>OBJECT_ID</i> [<i>KEY</i>]<br>&nbsp;&nbsp;<b><code>dump</code></b>


title: PARAMETERS
content:
<b><b><code>--help</code></b>, <b><code>-h</code></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief help message and exits.<br><br><b><b><code>--version</code></b>, <b><code>-V</code></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the PipeWire version and exits.<br><br><b><b><code>--remote=</code></b><i>NAME</i>, <b><code>-r</code></b> <i>NAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to a specific PipeWire instance identified by <i>NAME</i> instead of the default.<br><br><b><b><code>ls</code></b> [<i>OBJECT_ID</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists metadata. If <i>OBJECT_ID</i> is provided, lists metadata for that specific PipeWire object. If omitted, lists global metadata.<br><br><b><b><code>set</code></b> <i>OBJECT_ID KEY VALUE</i> [<i>TYPE</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a metadata entry. Associates <i>KEY</i> with <i>VALUE</i> for the specified <i>OBJECT_ID</i>. The optional <i>TYPE</i> specifies the data type (e.g., 'string', 'int', 'bool', 'json'). Defaults to 'string'.<br><br><b><b><code>clear</code></b> <i>OBJECT_ID</i> [<i>KEY</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Clears metadata. Removes <i>KEY</i> for the specified <i>OBJECT_ID</i>. If <i>KEY</i> is omitted, all metadata for <i>OBJECT_ID</i> is cleared.<br><br><b><b><code>dump</code></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Dumps all global and object-specific metadata currently known by the PipeWire daemon in a comprehensive format.<br><br>


title: DESCRIPTION
content:
<b><code>pw-metadata</code></b> is a command-line utility for managing metadata associated with objects within the PipeWire multimedia framework. It enables users to inspect, set, and clear key-value metadata pairs for various PipeWire entities, such as audio/video devices, nodes, and links. This metadata can be used by applications to store additional contextual information about these objects, beyond their standard properties. The tool supports operations like listing all metadata, listing metadata for a specific object by its ID, setting new metadata entries (with an optional type like string, int, bool, etc.), and clearing existing entries, either individually or all entries for a given object. It is an essential tool for debugging and configuring PipeWire setups where custom object properties are utilized, providing a direct interface to the daemon's metadata store.


title: CAVEATS
content:
Metadata managed by <b><code>pw-metadata</code></b> is stored by the active PipeWire daemon and is typically volatile, meaning it may not persist across daemon restarts unless specifically configured to do so by the system. Changes might not be immediately reflected in all applications if they cache metadata. Incorrectly setting or clearing metadata can potentially lead to unexpected behavior or misconfiguration of audio/video components.


title: EXAMPLES
content:
<br><b><I>Listing Global Metadata:</I></b><br><code>pw-metadata ls</code><br><br><b><I>Listing Metadata for Object ID 42:</I></b><br><code>pw-metadata ls 42</code><br><br><b><I>Setting a String Metadata Entry:</I></b><br><code>pw-metadata set 42 device.name "My USB Headset" string</code><br><br><b><I>Setting an Integer Metadata Entry:</I></b><br><code>pw-metadata set 100 level 50 int</code><br><br><b><I>Clearing a Specific Metadata Key:</I></b><br><code>pw-metadata clear 42 device.name</code><br><br><b><I>Dumping All Metadata:</I></b><br><code>pw-metadata dump</code>


title: OBJECT IDS
content:
<br>PipeWire objects are identified by unique numerical IDs. These IDs can be discovered using other PipeWire utilities such as <b><code>pw-dump</code></b> or <b><code>pw-cli info</code></b>. Metadata can be applied to various object types, including devices, nodes, links, and even global properties of the PipeWire daemon itself.


title: HISTORY
content:
PipeWire, the modern multimedia server framework for Linux, began its development around 2017, aiming to provide low-latency audio, video, and hardware access. The <b><code>pw-metadata</code></b> utility was introduced as an integral part of the PipeWire ecosystem to provide command-line access and control over the framework's object metadata. This allows for dynamic property management, crucial for integration with various applications and desktop environments that rely on custom object properties. Its development has progressed in tandem with PipeWire's increasing adoption across major Linux distributions, becoming a standard tool for system administrators and developers.


title: SYNOPSIS
content:
<I>pw-mon</I> [<B>-h</B>] [<B>-V</B>] [<B>-n</B>] [<B>-p</B>] [<B>-m</B>] [<B>-M</B>] [<B>-O</B> <I>type</I>] [<B>id</B> ...]<br><I>pw-mon</I> <B>--help</B><br><I>pw-mon</I> <B>--version</B>


title: PARAMETERS
content:
<b>-h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message and exits.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Same as <b>-h</b>.<br><br><b>-V</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the PipeWire version and exits.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Same as <b>-V</b>.<br><br><b>-n</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show object node names (default).<br><br><b>-p</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show object port names.<br><br><b>-m</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show monitor/event messages. This makes <i>pw-mon</i> actively monitor events.<br><br><b>-M</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not show monitor/event messages (default unless <b>-m</b> is used).<br><br><b>-O <I>type</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filter objects by type. Valid types include <I>PipeWire:Interface:Client</I>, <I>PipeWire:Interface:Device</I>, <I>PipeWire:Interface:Node</I>, <I>PipeWire:Interface:Port</I>, <I>PipeWire:Interface:Link</I>, etc.<br><br><b>id ...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display information about specific PipeWire object IDs. These IDs can be found by running <i>pw-mon</i> without arguments.<br><br>


title: DESCRIPTION
content:
<i>pw-mon</i> (PipeWire Monitor) is a command-line utility for inspecting the state of the PipeWire media server. It allows users to view detailed information about PipeWire objects, including clients, devices, nodes, ports, and links. It's an essential tool for debugging audio and video routing issues, verifying device connections, and understanding how applications interact with the PipeWire daemon.<br><br><i>pw-mon</i> can display a dynamic, real-time view of the graph or a static snapshot, providing insights into active streams, their properties, and connections. It helps identify issues like missing audio output, incorrect routing, or applications not connecting to PipeWire as expected.


title: CAVEATS
content:
<i>pw-mon</i> requires the PipeWire daemon to be running and accessible. If PipeWire is not running or if there are D-Bus or socket communication issues, the command may fail or show an empty output. Permissions can also be a factor; generally, it runs under the user session's PipeWire instance. The output can be verbose, especially in active systems, making it challenging to pinpoint specific information without filtering or piping to other tools like <i>grep</i>.


title: INTERACTIVE MONITORING
content:
When run without the <i>id</i> argument and without specifying <b>-M</b> (or with <b>-m</b>), <i>pw-mon</i> provides a dynamic, real-time view of the PipeWire graph. It updates automatically when new objects are created, removed, or their state changes, making it invaluable for observing live multimedia stream activity.


title: OBJECT IDS
content:
Each object in PipeWire (clients, devices, nodes, ports, links) is assigned a unique numerical ID. These IDs are displayed in the main <i>pw-mon</i> output and can be used as arguments to <i>pw-mon</i> to get detailed information about a specific object.


title: HISTORY
content:
<i>pw-mon</i> is an integral part of the PipeWire project, which was initiated by Wim Taymans at Red Hat in 2017. PipeWire aims to provide a low-latency, graph-based multimedia server that can handle audio, video, and hardware access, effectively unifying and modernizing the roles previously served by PulseAudio for audio and JACK for professional audio/video. <i>pw-mon</i> has been available since the early releases of PipeWire, serving as a primary debugging and monitoring tool for developers and users. Its development parallels the evolution of PipeWire itself, continually adapting to new features and interfaces within the framework.


title: PARAMETERS
content:
<b><b>-m</b>, <b>--media-type</b> <i>&lt;TYPE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the media type to record (e.g., 'audio', 'video').<br><br><b><b>-p</b>, <b>--properties</b> <i>&lt;PROPS&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets PipeWire properties for the recording client, e.g., 'media.role=foo'.<br><br><b><b>-d</b>, <b>--disconnect</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Automatically disconnects and exits when the recording source becomes idle or disappears.<br><br><b><b>-r</b>, <b>--rate</b> <i>&lt;RATE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the sample rate for audio recording (e.g., 48000 for 48kHz).<br><br><b><b>-c</b>, <b>--channels</b> <i>&lt;CHANNELS&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the number of audio channels (e.g., 1 for mono, 2 for stereo).<br><br><b><b>-f</b>, <b>--format</b> <i>&lt;FORMAT&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the sample format (e.g., 's16' for 16-bit signed int, 'f32' for 32-bit float).<br><br><b><b>-v</b>, <b>--volume</b> <i>&lt;VOLUME&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the recording volume level (0.0 to 1.0).<br><br><b><b>-P</b>, <b>--port</b> <i>&lt;PORT_NAME&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to a specific PipeWire port by its name.<br><br><b><b>--target</b> <i>&lt;NODE_ID&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to a specific PipeWire node by its ID for recording. Use <i>pw-cli inspect</i> to find IDs.<br><br><b><b>--duration</b> <i>&lt;SECONDS&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the maximum recording duration in seconds.<br><br><b><b>--latency</b> <i>&lt;LATENCY&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the desired PipeWire processing latency.<br><br><b><b>-L</b>, <b>--record-latency</b> <i>&lt;LATENCY&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the buffering latency for the recording stream.<br><br><b><b>--record-buffer</b> <i>&lt;SIZE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the size of the internal recording buffer.<br><br><b><b>--quality</b> <i>&lt;QUALITY&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the encoding quality for lossy formats (0-100).<br><br><b><b>--device</b> <i>&lt;NODE_ID&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Alias for <b>--target</b>, specifying the device node ID to record from.<br><br><b><b>--remote</b> <i>&lt;NAME&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to a PipeWire remote instance by its name.<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;Displays version information and exits.<br><br>


title: DESCRIPTION
content:
<i>pw-record</i> is a command-line utility provided by the PipeWire project, designed for recording audio and/or video data directly from PipeWire streams. It acts as a client to the PipeWire daemon, connecting to specified sources or sinks within the PipeWire graph and capturing their media output to a file. This tool is valuable for various tasks, including testing PipeWire setups, capturing application audio/video output, or performing basic, ad-hoc media recordings.<br><br>It supports recording different media types (audio, video) and allows users to specify various parameters such as sample rate, number of channels, sample format, and recording duration. The actual output file format support depends on the underlying FFmpeg libraries that PipeWire is linked against, enabling popular formats like WAV, FLAC, Ogg, or even MP3/WebM if respective codecs are available. <i>pw-record</i> offers a straightforward way to interact with the PipeWire multimedia framework for capture operations.


title: CAVEATS
content:
<i>pw-record</i> requires a running PipeWire daemon. Its ability to record specific media types and output file formats is dependent on how PipeWire was compiled and what FFmpeg libraries (and their codecs) are available on the system. Identifying the correct PipeWire node or port IDs for advanced recording scenarios often requires prior inspection using tools like <i>pw-cli inspect</i> or <i>pw-top</i>, which can make initial usage less intuitive for complex setups. It's primarily designed for basic recording tasks; for advanced audio/video processing or streaming, other PipeWire-integrated tools or applications might be more suitable.


title: FILE FORMAT AND CODEC SUPPORT
content:
The specific audio and video file formats (e.g., WAV, FLAC, Ogg Vorbis, MP3, WebM) that <i>pw-record</i> can produce are determined by the FFmpeg libraries that PipeWire was compiled against. Availability of certain codecs (like MP3) depends on the system's FFmpeg installation and licensing considerations. If a desired format/codec is not supported, an error may occur, or a fallback format might be used.


title: TARGETING SPECIFIC STREAMS
content:
To record from a particular application's output or a specific input device, users often need to identify its corresponding PipeWire node ID or port name. This can be done using <i>pw-cli inspect</i> or <i>pw-top</i>. Once identified, the <b>--target</b> (or <b>--device</b>) option with the node ID or <b>--port</b> with the port name can be used to direct <i>pw-record</i> to the correct source.


title: HISTORY
content:
<i>pw-record</i> is an integral part of the PipeWire project, which emerged as a modern multimedia framework for Linux, aiming to unify and replace functionalities previously handled by separate servers like PulseAudio (for audio) and JACK (for pro-audio and video). Developed to provide a straightforward command-line interface for capturing media streams, <i>pw-record</i> allows users to interact with PipeWire's graph-based architecture directly. While it offers basic recording capabilities, its role is often complemented or, for simpler tasks, superseded by <i>pw-cat</i>, a more versatile PipeWire command-line utility capable of both playing and recording, thus simplifying the toolset for common media operations within the PipeWire ecosystem.


title: PARAMETERS
content:
<b><b>reserve</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempts to acquire an exclusive reservation for the specified PipeWire audio device.<br><br><b><b>release</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Releases an existing exclusive reservation for the specified PipeWire audio device, making it available to other applications.<br><br><b><b>status</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Checks and displays the current reservation status of the specified PipeWire audio device.<br><br><b><b>help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the usage information and exits.<br><br><b><b>-n</b> <i>&lt;id&gt;</i>, <b>--node-id=</b><i>&lt;id&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the PipeWire <i>node ID</i> of the audio device to operate on. This is a mandatory parameter for <b>reserve</b>, <b>release</b>, and <b>status</b> commands.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, providing more detailed information about the command's execution and status.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief help message and exits.<br><br>


title: DESCRIPTION
content:
<b>pw-reserve</b> is a utility within the PipeWire multimedia framework designed for managing exclusive access to audio devices. Its primary function is to allow a user or application to <i>reserve</i> a specific audio hardware node, ensuring that no other PipeWire client can utilize it concurrently. This is particularly crucial for scenarios where a device does not support simultaneous multi-application access, or for applications that require exclusive control for optimal performance, stability, or low-latency operations, such as professional audio software or media playback systems.<br><br>When a device is reserved, other PipeWire clients attempting to use it will typically fail to acquire access or will be paused until the reservation is explicitly released. The command provides functionalities to <b>reserve</b> a device, <b>release</b> an existing reservation, or <b>status</b> the current reservation state of a device. It interacts directly with the PipeWire session manager to establish or revoke exclusive control over a specified node ID, which represents an audio device within the PipeWire graph. This mechanism is vital for preventing resource conflicts and ensuring predictable audio behavior across various applications.


title: CAVEATS
content:
<ul><li><b>PipeWire Requirement:</b> <b>pw-reserve</b> requires a running PipeWire daemon and session manager to function correctly.</li><li><b>Node ID Discovery:</b> Users must first identify the correct PipeWire <i>node ID</i> for their desired audio device, typically using tools like <b>pw-cli dump Node</b> or <b>pw-top</b>.</li><li><b>Hardware Support:</b> Not all audio hardware or drivers might fully support exclusive access management through PipeWire in the same way, though PipeWire aims to abstract this.</li><li><b>Process Lifetime:</b> Reservations are usually tied to the lifetime of the <b>pw-reserve</b> process. If the process exits without an explicit <b>release</b>, the reservation might be automatically released, but it's best practice to always explicitly release devices.</li><li><b>Potential Inaccessibility:</b> Misusing the command can render an audio device temporarily inaccessible to other applications or system sounds, potentially leading to a 'no sound' situation until the reservation is released.</li></ul>


title: FINDING THE NODE ID
content:
To effectively use <b>pw-reserve</b>, you must first determine the specific <i>node ID</i> of the audio device you intend to manage. This can be achieved by running <b>pw-cli dump Node</b>, which lists all active PipeWire nodes (including audio sinks and sources representing your hardware), or by using <b>pw-top</b> for a live, interactive view. Look for nodes associated with your desired input or output device (e.g., sound card, USB microphone) and note their unique ID number.


title: TYPICAL USE CASES
content:
This command is particularly valuable in scenarios such as:<ul><li><b>Professional Audio Production:</b> Ensuring a Digital Audio Workstation (DAW) has uncontested access to an audio interface for low-latency recording and playback.</li><li><b>Gaming:</b> Dedicated control over audio output to prevent interference from background applications.</li><li><b>Media Centers:</b> Providing exclusive sound output for a movie or music player for an uninterrupted experience.</li><li><b>Voice Chat/Conferencing:</b> Guaranteeing a microphone or speaker is not inadvertently used or blocked by another application.</li></ul>


title: HISTORY
content:
<b>pw-reserve</b> is a relatively modern utility, having been developed as an integral part of the PipeWire project. PipeWire itself emerged around 2017-2018 with the goal of unifying and modernizing audio, video, and hardware handling on Linux, serving as a successor to systems like PulseAudio and JACK. The need for `pw-reserve` arose from common challenges in traditional Linux audio stacks, particularly the management of exclusive access to hardware devices to prevent conflicts between applications. Its inclusion underscores PipeWire's commitment to providing robust and flexible resource management capabilities essential for professional audio workloads and a seamless user experience.


title: PARAMETERS
content:
<b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show program help message and exit.<br><br><b><b>-r</b> <I>interval</I>, <b>--rate=</b><I>interval</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the update interval in seconds. The default interval is 1 second. <I>interval</I> can be a floating-point number (e.g., 0.5 for half a second).<br><br><b><b>-P</b> <I>pid</I>, <b>--pid=</b><I>pid</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filter the displayed statistics to only show nodes and links associated with a specific process ID (<I>pid</I>).<br><br>


title: DESCRIPTION
content:
<b>pw-top</b> is a console-based utility that displays real-time statistics about the PipeWire sound and video server. It provides a dynamic, constantly updated view of active PipeWire nodes, links, and their resource usage. This includes crucial information such as node ID, name, media type (audio/video), direction (input/output), latency, busy time, and CPU usage. It serves as an invaluable tool for diagnosing audio/video routing issues, identifying high-latency components, or understanding the overall health and performance of a PipeWire system. By monitoring the flow of media data, <b>pw-top</b> helps users and developers pinpoint potential bottlenecks and ensure smooth multimedia operation.


title: CAVEATS
content:
<b>pw-top</b> requires the PipeWire multimedia server to be running to display any information. The CPU usage reported by <b>pw-top</b> typically reflects the CPU time spent by the PipeWire server's thread handling a specific node or link, not necessarily the total CPU usage of the application owning that node. Understanding the output columns and interactive controls benefits from basic knowledge of PipeWire concepts (nodes, links, ports).


title: INTERACTIVE CONTROLS
content:
Like <b>top</b>, <b>pw-top</b> offers interactive controls within the running application to change the displayed view and modify sorting. Common keys include:<br><br><b>n</b>: Switch to nodes view (default).<br><b>l</b>: Switch to links view.<br><b>p</b>: Switch to ports view.<br><b>m</b>: Switch to monitor nodes view.<br><b>s</b>: Cycle through sorting columns.<br><b>q</b>: Quit the application.<br><br>The exact available views and interactive keys might vary slightly between PipeWire versions.


title: OUTPUT COLUMNS
content:
When running <b>pw-top</b>, the displayed information is organized into several columns providing detailed statistics for each PipeWire component. Typical columns include:<br><br><b>ID</b>: The unique PipeWire object ID.<br><b>NAME</b>: The name of the node, link, or port.<br><b>PRIORITY</b>: The priority of the node (relevant for scheduling).<br><b>STATE</b>: The current state of the node (e.g., running, suspended).<br><b>LATENCY</b>: The measured audio/video latency.<br><b>BUSY</b>: The percentage of time the node is busy processing data.<br><b>B/S</b>: Bytes per second throughput (for links).<br><b>ERRORS</b>: Number of processing errors.<br><b>CPU</b>: CPU usage percentage for the PipeWire thread handling this component.


title: HISTORY
content:
<b>pw-top</b> is an integral part of the PipeWire project, which was initiated by Wim Taymans at Red Hat in 2017. PipeWire was developed to modernize Linux multimedia by providing a robust framework for professional audio, video, and hardware access, addressing limitations of predecessors like PulseAudio and JACK. As PipeWire evolved into a critical component of the Linux desktop ecosystem, <b>pw-top</b> emerged as an essential debugging and monitoring utility. It provides direct introspection into PipeWire's real-time operations, much like <b>top</b> does for system processes, mirroring the development and increasing adoption of the PipeWire server itself.


title: SYNOPSIS
content:
<b>pw-v4l2</b> <br><I>(Note: This is a PipeWire module and is typically not invoked directly by the user via the command line with options, but rather loaded by a PipeWire session manager based on system configuration.)</I>


title: PARAMETERS
content:
<b>v4l2.source.fd.autodetect</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>(Boolean)</I> When set to true (default), enables automatic detection and exposure of file descriptor-based V4L2 sources (e.g., /dev/video0) as PipeWire nodes. Configured via PipeWire's module configuration files.<br><br><b>v4l2.sink.loopback</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>(Boolean)</I> Enables the creation of virtual V4L2 loopback devices, which act as PipeWire sinks. Applications can then write video data to these virtual devices, which can be consumed by other V4L2-compatible applications. Configured via PipeWire's module configuration files.<br><br><b>v4l2.sink.devices</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>(String Array)</I> Specifies a list of device paths for the virtual V4L2 loopback devices created by the module (e.g., ['/dev/video10']). Only relevant if v4l2.sink.loopback is enabled. Configured via PipeWire's module configuration files.<br><br><b>v4l2.source.devices</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>(String Array)</I> Specifies a list of specific V4L2 source device paths to expose (e.g., ['/dev/video0']). If not specified, all detected devices are usually handled. Configured via PipeWire's module configuration files.<br><br><b>v4l2.source.width, v4l2.source.height</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>(Integer)</I> Preferred resolution for a specific V4L2 source. These are hints and the actual resolution depends on device capabilities and application requests. Configured via PipeWire's module configuration files.<br><br><b>v4l2.source.framerate</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>(Fraction)</I> Preferred framerate for a specific V4L2 source (e.g., '30/1'). Configured via PipeWire's module configuration files.<br><br><b>v4l2.source.format</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>(String)</I> Preferred pixel format for a specific V4L2 source (e.g., 'YUY2'). Configured via PipeWire's module configuration files.<br><br>


title: DESCRIPTION
content:
<I>pw-v4l2</I> is a crucial <I>PipeWire</I> module designed to integrate <I>Video4Linux2 (V4L2)</I> devices into the <I>PipeWire</I> multimedia graph. It acts as a bridge, exposing physical V4L2 sources, such as webcams, capture cards, or other video input devices, as <I>PipeWire</I> video nodes.<br><br>Conversely, <I>pw-v4l2</I> can also create virtual V4L2 loopback devices, acting as <I>PipeWire</I> sinks. This allows applications to capture video output from <I>PipeWire</I> applications (e.g., screen recording tools, video mixers) as if it were a physical V4L2 camera, enabling complex video routing and processing.<br><br>This module is typically loaded automatically by a <I>PipeWire</I> session manager like <I>wireplumber</I> or <I>pipewire-media-session</I> based on system configuration. It handles device enumeration, format negotiation, and stream management, ensuring seamless video integration within the modern Linux desktop environment.


title: CAVEATS
content:
<I>pw-v4l2</I> is a <I>PipeWire</I> module, meaning it's primarily designed to be loaded and managed by a <I>PipeWire</I> daemon and its session manager (like <I>wireplumber</I>). Direct execution from the command line is generally for debugging or specific advanced setups and typically offers no command-line arguments for configuration. All configuration is done through <I>PipeWire</I>'s module configuration files (e.g., <I>/usr/share/pipewire/pipewire-v4l2.conf</I> or <I>/etc/pipewire/pipewire-v4l2.conf</I>). Proper permissions for accessing <I>V4L2</I> devices (e.g., user in 'video' group) are essential for its operation.


title: CONFIGURATION
content:
The behavior of <I>pw-v4l2</I> is primarily controlled via <I>PipeWire</I> configuration files. These files, typically located in <I>/usr/share/pipewire/</I> and <I>/etc/pipewire/</I> (e.g., <I>pipewire-v4l2.conf</I> or module-specific files), contain properties that dictate how the module discovers and exposes <I>V4L2</I> devices, and whether it creates virtual loopback devices. Changes to these files often require restarting the <I>PipeWire</I> service or its session manager for them to take effect.


title: USE CASES
content:
<I>pw-v4l2</I> is essential for applications that rely on webcam input, ensuring they can access physical cameras through the <I>PipeWire</I> infrastructure. It's also vital for creating virtual camera feeds; for instance, broadcasting software like <I>OBS Studio</I> can output its mixed video stream to a <I>PipeWire</I> sink, which <I>pw-v4l2</I> then exposes as a virtual <I>V4L2</I> device. This allows other applications (e.g., video conferencing tools) to select this virtual camera as their input, enabling complex video routing and processing workflows.


title: HISTORY
content:
<I>pw-v4l2</I> is an integral part of the <I>PipeWire</I> project, which emerged to address the complex multimedia requirements of modern Linux desktops, including low-latency audio/video processing, sandboxing support for applications (like Flatpaks), and unified media handling. <I>PipeWire</I> began development around 2017 and gained significant traction, aiming to replace older frameworks like <I>PulseAudio</I> and <I>JACK</I> for many use cases. The <I>pw-v4l2</I> module was developed as a core component to seamlessly integrate existing <I>V4L2</I> hardware and software devices into this new graph-based multimedia system, enabling broad compatibility and advanced video routing capabilities.


title: PARAMETERS
content:
<b><b>-r</b>, <b>--read-only</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Perform checks but do not write any changes to the files. This is useful for auditing before making modifications.<br><br><b><b>-s</b>, <b>--strict-checking</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Enable stricter checking rules. This can detect more subtle issues but might also flag minor inconsistencies that are functionally benign.<br><br><b><b>-q</b>, <b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Suppress all output except for errors. This is useful for scripting or automated checks.<br><br><b><b>-P</b> <i><I>DIR</I></i>, <b>--prefix=</b><i><I>DIR</I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Apply the specified <i>DIR</i> as a prefix to all paths for the password and shadow files. This is typically used in chroot environments.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Display a brief help message and exit.<br><br>


title: DESCRIPTION
content:
pwck is a system utility used to verify the integrity and consistency of the system's password files, namely <i>/etc/passwd</i> and <i>/etc/shadow</i>. It checks for a variety of common errors that can compromise system security or lead to user login issues. These checks include: <br><br> <b>Malformed or truncated entries.</b><br> <b>Invalid or non-existent primary group IDs (GIDs).</b><br> <b>Duplicate user IDs (UIDs) or group IDs (GIDs).</b><br> <b>Inconsistencies between <i>/etc/passwd</i> and <i>/etc/shadow</i>, such as missing entries for a user in one file.</b><br> <b>Users with no password or locked accounts (depending on configuration).</b><br><br> When errors are detected, pwck provides detailed messages and, in some cases, can interactively prompt the administrator to delete or modify the problematic entries. Running pwck regularly is a crucial part of system maintenance to ensure the integrity of user authentication data and prevent security vulnerabilities.


title: CAVEATS
content:
<b>Root Privileges Required:</b> pwck requires root privileges to read and potentially modify <i>/etc/passwd</i> and <i>/etc/shadow</i>. <br><br> <b>Backup Files:</b> Before allowing pwck to make any modifications, it is highly recommended to back up <i>/etc/passwd</i> and <i>/etc/shadow</i> to prevent data loss or system instability in case of unexpected errors. <br><br> <b>Interactive Mode Caution:</b> When run interactively, carefully review proposed changes. Incorrect modifications can render a system unbootable or compromise security. <br><br> <b>Limited Scope:</b> pwck primarily checks file format and basic consistency; it does not verify cryptographic strength of passwords or complex policy compliance.


title: FILES
content:
<i>/etc/passwd</i>: The primary password file containing user account information.<br><i>/etc/shadow</i>: The shadow password file containing encrypted passwords and password aging information.<br><i>/etc/login.defs</i>: Configuration file that defines system-wide login and password policies, used by pwck for certain checks like UID/GID ranges.


title: EXIT STATUS
content:
pwck returns <b>0</b> on success if no inconsistencies were found or all found inconsistencies were corrected successfully. <br><br> A non-zero exit status indicates that errors were found, and not all of them could be corrected, or the command terminated due to a fatal error. Specific non-zero values may indicate different types of errors (e.g., <b>1</b> for syntax errors, <b>2</b> for invalid parameters, <b>3</b> for inconsistencies).


title: HISTORY
content:
pwck is an integral part of the <b>shadow-utils</b> package, which was developed to enhance system security by separating encrypted passwords from the publicly readable <i>/etc/passwd</i> file into the restricted <i>/etc/shadow</i> file. The <b>shadow-utils</b> project originated in the late 1980s and early 1990s as a response to the security limitations of traditional Unix password management. pwck specifically emerged as a tool to ensure the integrity of these new shadow password files alongside the traditional <i>passwd</i> file, evolving with the package to address various file consistency and formatting issues over time. Its continued development ensures robust password file management on Linux systems.


title: SEE ALSO
content:
grpck(8), useradd(8), usermod(8), userdel(8), passwd(5), shadow(5), pwconv(8), pwunconv(8), login.defs(5)


title: PARAMETERS
content:
<b><b>-r</b>, <b>--root</b> <I>CHROOT_DIR</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Apply changes in the specified <I>CHROOT_DIR</I> directory. This allows the command to operate on a different root file system, useful in recovery or container environments.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a brief help message and exit. This option provides a quick overview of the command's usage and available options.<br><br>


title: DESCRIPTION
content:
The <i>pwconv</i> command is used to convert traditional Linux password and group files (<I>/etc/passwd</I> and <I>/etc/group</I>) into their more secure shadow counterparts (<I>/etc/shadow</I> and <I>/etc/gshadow</I>). This process moves the encrypted password hashes from the publicly readable <I>/etc/passwd</I> and <I>/etc/group</I> files to the root-only readable <I>/etc/shadow</I> and <I>/etc/gshadow</I> files respectively. <br><br>After conversion, the password fields in <I>/etc/passwd</I> and <I>/etc/group</I> are replaced with an 'x' placeholder, indicating that the actual password information is stored in the shadow files. This significantly enhances system security by preventing unprivileged users from accessing encrypted password hashes, thereby mitigating brute-force and dictionary attacks. <br><br><i>pwconv</i> intelligently handles existing shadow files by updating them with new entries or merging information. It also creates backup copies of the original files (e.g., <I>/etc/passwd-</I>, <I>/etc/shadow-</I>) before making any modifications, ensuring a safe rollback if needed. This command is a crucial step in setting up a secure Linux system, typically run during initial system configuration or migration from older systems.


title: CAVEATS
content:
Converting to shadow passwords is a significant system change and should be done with caution. <br><br><ul><li>Requires superuser (root) privileges to execute.</li><li>Modifies critical system authentication files; ensure backups are in place.</li><li>Once converted, systems generally rely on shadow files for password authentication. Reverting requires the <i>pwunconv</i> command.</li><li>Does not handle network authentication systems like NIS/YP; it only affects local user and group authentication.</li><li>If the system files are manually edited incorrectly, <i>pwconv</i> might not correctly handle the inconsistencies.</li></ul>


title: FILES
content:
<i>pwconv</i> interacts with and modifies the following system files:<br><ul><li><B>/etc/passwd</B>: The main user account information file.</li><li><B>/etc/shadow</B>: The shadow password file, storing encrypted password hashes and password expiration information.</li><li><B>/etc/group</B>: The main group information file.</li><li><B>/etc/gshadow</B>: The shadow group file, storing encrypted group passwords and group administration information.</li><li><B>/etc/passwd-</B>, <B>/etc/shadow-</B>, <B>/etc/group-</B>, <B>/etc/gshadow-</B>: Backup copies of the original files created before modification.</li></ul>


title: EXIT STATUS
content:
The <i>pwconv</i> command returns an exit status of <b>0</b> upon successful execution. Any non-zero exit status indicates that an error occurred during the conversion process.


title: HISTORY
content:
The concept of shadow passwords emerged as a security enhancement in Unix-like systems. Historically, user password hashes were stored in the publicly readable <I>/etc/passwd</I> file. This posed a security risk as it made encrypted passwords vulnerable to offline brute-force attacks. The introduction of shadow password files (<I>/etc/shadow</I>), readable only by the root user, addressed this vulnerability by separating the password hashes from the public user information.<br><br>The <i>pwconv</i> command is part of the <I>shadow-utils</I> package, which provides a suite of tools for managing user and group accounts and their authentication information. It was developed to facilitate the transition from older systems that stored password hashes directly in <I>/etc/passwd</I> to the more secure shadow password system, making it an essential utility for modern Linux security practices.


title: PARAMETERS
content:
<b><b>-L</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the <i>logical</i> path. This is the default behavior. It shows the path as if symbolic links were part of the directory structure, rather than resolving them to their physical targets.<br><br><b><b>-P</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the <i>physical</i> path. This resolves all symbolic links in the current working directory to their true underlying path, effectively showing the canonical, absolute path.<br><br>


title: DESCRIPTION
content:
The <b>pwd</b> command (Print Working Directory) is a fundamental utility in Unix-like operating systems, including Linux. It displays the full pathname of the current working directory. <br><br>When you navigate the file system using commands like <b>cd</b>, <b>pwd</b> helps you confirm your exact location within the directory hierarchy. This is particularly useful when dealing with complex directory structures, symbolic links, or when you've lost track of your position. <br><br>By default, <b>pwd</b> usually prints the <i>logical</i> path, meaning it resolves symbolic links to the path you used to get there, rather than the underlying physical path. For instance, if you <b>cd</b> into a symbolic link, <b>pwd</b> will show the path including the symlink name, not the path to the actual target directory. This behavior can be altered using options.


title: CAVEATS
content:
In most modern shells (like Bash, Zsh), <b>pwd</b> is often a <i>shell built-in</i> command. This means it's an integral part of the shell itself, rather than a separate executable program. <br><br>While this generally improves performance, it also means that the behavior (especially regarding <b>-L</b> and <b>-P</b>) can sometimes vary slightly between different shell implementations of the built-in and the standalone utility (if one exists). The primary caveat is understanding the difference between logical and physical paths when navigating through symbolic links, as misinterpreting the output can lead to unexpected behavior in scripts or manual operations.


title: SHELL BUILT-IN VS. EXECUTABLE
content:
While <b>pwd</b> exists as an executable (e.g., <b>/bin/pwd</b>), it is almost always implemented as a <i>shell built-in</i> in popular shells like Bash, Zsh, and Ksh. This means that when you type <b>pwd</b>, the shell executes its own internal version of the command, which is faster as it avoids the overhead of launching an external process. You can verify this using <b>type pwd</b> or <b>which pwd</b> (which might point to the external executable but not tell you it's a built-in). The behavior of the built-in can sometimes slightly differ from the standalone utility, though for <b>pwd</b>, the core functionality is identical.


title: ENVIRONMENT VARIABLE PWD
content:
Many shells maintain an environment variable named <b>PWD</b> that stores the current working directory. The <b>pwd</b> command often just outputs the value of this variable. For example, you can see it with <b>echo $PWD</b>. This variable is automatically updated by the shell whenever you change directories using the <b>cd</b> command. This is another reason why <b>pwd</b> is fast, as it typically just reads an already available shell variable.


title: HISTORY
content:
The <b>pwd</b> command has been a staple in Unix-like operating systems since their early days, reflecting the fundamental need for users to know their current location within the hierarchical file system. Its simplicity and utility have ensured its continued presence across various Unix distributions and Linux. <br><br>Historically, its behavior regarding symbolic links has been refined, leading to the introduction of options like <b>-L</b> and <b>-P</b> to explicitly control whether the logical or physical path is displayed. It's often implemented as a shell built-in for efficiency, making it one of the most frequently used commands in interactive terminal sessions.


title: PARAMETERS
content:
<b><i>PID</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The Process ID (PID) of the running process whose current working directory you want to query.<br><br>


title: DESCRIPTION
content:
<i>The <b>pwdx</b> command is a utility used to determine the current working directory (CWD) of a specified running process. It takes a single argument, the Process ID (PID), and outputs the absolute path of the directory from which that process is currently operating. This can be particularly useful for debugging, system monitoring, or understanding the environment of an application.<br><br>Under the hood, <b>pwdx</b> achieves this by reading the symbolic link <b>/proc/</b><i>PID</i><b>/cwd</b>, which points to the process's current working directory. Since it relies on the <b>procfs</b> filesystem, it's highly efficient. It provides a quick way to inspect a process's environment without attaching a debugger or using more complex tools like <b>lsof</b> or <b>strace</b>.</i>


title: CAVEATS
content:
<i>Access to a process's CWD via <b>pwdx</b> is subject to permissions. You can typically query processes owned by your user, but querying processes owned by other users or root often requires root privileges. If the specified PID does not exist, or if you lack sufficient permissions, <b>pwdx</b> will return an error.<br><br>The CWD of a process can change during its lifetime, so the output reflects the CWD at the moment <b>pwdx</b> is executed.</i>


title: <B>UNDERLYING MECHANISM</B>
content:
<i><b>pwdx</b> directly accesses the <b>/proc</b> pseudo-filesystem, which is a standard feature on Linux. For every running process with PID <b><i>N</i></b>, there's a directory <b>/proc/<i>N</i></b>. Inside this directory, the <b>cwd</b> entry is a symbolic link pointing to the process's current working directory. <b>pwdx</b> simply resolves this symlink. This mechanism is fast and lightweight as it avoids scanning system calls or large amounts of data.</i>


title: HISTORY
content:
<i>The <b>pwdx</b> command is part of the <b>procps-ng</b> suite of utilities, which provides various tools for monitoring and interacting with processes on Linux systems by leveraging the <b>/proc</b> filesystem. It was developed as a convenient wrapper around reading the <b>/proc/</b><i>PID</i><b>/cwd</b> symlink, simplifying a common diagnostic task for system administrators and developers.</i>


title: SYNOPSIS
content:
pwgen [<i>options</i>] [<i>length</i>] [<i>number_of_passwords</i>]<br><br>Examples:<br><code>pwgen 12 5</code> (Generate 5 passwords of 12 characters each)<br><code>pwgen -s 16</code> (Generate one highly secure, 16-character password)<br><code>pwgen -cnyB 10</code> (Generate a 10-character password with capitals, numbers, symbols, but no vowels)


title: PARAMETERS
content:
<b><i>length</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the desired length for the generated passwords. If omitted, default to 16 characters.<br><br><b><i>number_of_passwords</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the number of passwords to generate. If omitted, default to 1 password. This can also be controlled by the <i>-N</i> option.<br><br><b>-c, --capitalize</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ensure the generated password contains at least one capital letter.<br><br><b>-n, --numerals</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ensure the generated password contains at least one numeral (digit).<br><br><b>-y, --symbols</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ensure the generated password contains at least one symbol (e.g., !, @, #).<br><br><b>-A, --no-ambiguous</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exclude characters that could be easily confused, such as 'l', '1', 'O', '0'.<br><br><b>-B, --no-vowels</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not use vowels (a, e, i, o, u) when generating pronounceable passwords, making them less pronounceable but potentially harder to guess.<br><br><b>-s, --secure</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate completely random, non-pronounceable passwords for maximum cryptographic strength. This option overrides the pronounceable generation.<br><br><b>-x, --no-repeating</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempt to avoid using repeating characters consecutively in the password, if possible given the character set.<br><br><b>-N num, --num-passwords=num</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate a specific <i>num</i> of passwords. This is an alternative to the positional <i>number_of_passwords</i> argument.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br>


title: DESCRIPTION
content:
pwgen is a command-line utility designed to generate random passwords that are both secure and, optionally, easy for humans to remember and type. Unlike purely random string generators, pwgen can create "pronounceable" passwords by intelligently combining character sets, making them more user-friendly for human recall. It offers extensive options to customize password characteristics, including length, number of passwords, inclusion of capital letters, numerals, and symbols. Users can also specify constraints such as avoiding ambiguous characters (e.g., 'l' and '1') or generating completely random, non-pronounceable passwords for maximum security. This flexibility makes pwgen a versatile tool for various password generation needs, balancing security requirements with practical usability.


title: CAVEATS
content:
While pwgen can create "pronounceable" passwords for easier memorization, these might inherently be less cryptographically secure than completely random strings generated with the <i>-s</i> option, or other tools that prioritize maximum randomness. For highly sensitive accounts, it's generally recommended to use passwords generated by a dedicated password manager or a truly random source like <i>/dev/urandom</i>, especially if pronounceability is not a critical requirement. The effectiveness of "pronounceable" passwords relies on the underlying dictionary and generation logic; an attacker might be able to exploit these patterns if the entropy is low or the method predictable.


title: PRONOUNCEABILITY VS. SECURITY TRADE-OFF
content:
pwgen's unique feature is its ability to generate pronounceable passwords, which can aid memorization. However, this comes with a slight trade-off in pure randomness compared to passwords generated without this constraint. For maximum security, especially for sensitive accounts, it is recommended to use the <i>-s</i> (secure) option, which generates completely random, non-pronounceable passwords, or to rely on tools that prioritize cryptographic randomness above all else.


title: DEFAULT BEHAVIOR
content:
By default, pwgen generates 16-character pronounceable passwords. These passwords will typically include a mix of lowercase letters and sometimes numbers, aiming for a balance between strength and ease of use. To include uppercase letters, numbers, or symbols, explicit options (<i>-c</i>, <i>-n</i>, <i>-y</i>) must be specified.


title: HISTORY
content:
pwgen has been a staple utility in the Linux and Unix-like ecosystem for many years, filling the niche for human-friendly password generation. Its development reflects the ongoing challenge of balancing strong security practices with practical usability. The tool aims to mitigate the common user tendency to choose weak, easily guessable passwords by providing a simple, quick way to generate secure yet memorable alternatives. It's often included in standard Linux distributions as part of the <i>util-linux</i> or similar core utilities packages, showcasing its established role in system administration and general user security.


title: PARAMETERS
content:
<b><i>subcommand</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the particular utility to execute (e.g., <b>template</b>, <b>cyclic</b>, <b>checksec</b>, <b>debug</b>, <b>asm</b>, <b>disasm</b>, <b>shellcraft</b>, <b>elf</b>). Each subcommand has its own specific options and arguments.<br><br><b>[<i>options</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Varies greatly depending on the chosen <i>subcommand</i>. Common options often include <b>--help</b> for subcommand-specific usage, <b>-f</b> for file paths, or <b>-a</b> for architecture.<br><br><b>[<i>arguments</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Input relevant to the subcommand, such as a pattern size for <b>cyclic</b> or a binary path for <b>checksec</b>.<br><br>


title: DESCRIPTION
content:
<i>pwn</i> is not a standalone traditional Linux command but rather a common shorthand or the primary executable for <b>pwntools</b>, a powerful Python library and framework designed for exploit development and CTF (Capture The Flag) challenges. It provides a comprehensive suite of utilities to simplify various aspects of binary exploitation, including assembly, disassembly, shellcode generation, remote interaction, debugging, and ELF file analysis. <b>pwntools</b> automates many repetitive tasks, allowing security researchers and CTF players to focus on the logic of their exploits. Its functionalities are typically accessed by importing the library into Python scripts, but it also provides several command-line subcommands (e.g., <i>pwn template</i>, <i>pwn cyclic</i>, <i>pwn checksec</i>) for quick utility tasks.


title: CAVEATS
content:
<b>pwn</b> is not a standard Linux command; it is part of the <b>pwntools</b> Python library and requires installation (typically via <i>pip</i>).<br>Its primary usage is as a Python library for scripting exploits, with the command-line interface serving as a set of convenient helper tools.<br>Requires Python 3.


title: INSTALLATION
content:
<b>pwntools</b> is installed using pip: <br> <i>pip install pwntools</i> <br> For full functionality, including debugging, additional system dependencies like <b>gdb</b> and <b>strace</b> are often required.


title: SCRIPTING USAGE
content:
While <b>pwn</b> provides command-line tools, its full power is unleashed when used as a Python library within scripts. Users <i>from pwn import *</i> to access its classes and functions for creating complex exploit chains, interacting with targets, and automating vulnerability analysis.


title: CTF FOCUS
content:
<b>pwntools</b> is heavily optimized for Capture The Flag scenarios, offering features like interactive shells, automatic context management (architecture, OS), and rapid prototyping capabilities.


title: HISTORY
content:
<b>pwntools</b> was created to standardize and simplify common tasks in exploit development and CTF competitions. It was initially developed by various contributors in the security community, evolving into a widely adopted open-source framework. Its development focuses on providing a high-level, Pythonic interface to complex low-level operations, significantly reducing the boilerplate code needed for crafting exploits. It continues to be actively maintained and updated by the <b>pwntools</b> team, adapting to new exploitation techniques and security mitigations.


title: SYNOPSIS
content:
<b>pwsh</b> [<b>-Command</b> <i>&lt;scriptBlock&gt;</i> | <b>-File</b> <i>&lt;filePath&gt;</i> [<i>&lt;args&gt;</i>]] [<b>-NoProfile</b>] [<b>-NonInteractive</b>] [<b>-Help</b> | <b>-?</b>]


title: PARAMETERS
content:
<b><b>-Command</b> <i>&lt;scriptBlock&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes specified PowerShell commands or scripts. The script block can be a string literal or a reference to a variable.<br><br><b><b>-File</b> <i>&lt;filePath&gt;</i> [<i>&lt;args&gt;</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs a PowerShell script file at the specified path. Any subsequent arguments are passed to the script.<br><br><b><b>-NoProfile</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents loading the user's PowerShell profile script at startup, which can speed up execution for simple tasks.<br><br><b><b>-NonInteractive</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs PowerShell in a non-interactive mode, suitable for automation scripts that should not prompt for user input.<br><br><b><b>-Help</b>, <b>-?</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays command-line help for <b>pwsh</b>, detailing available options and their usage.<br><br><b><b>-ExecutionPolicy</b> <i>&lt;policy&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the execution policy for the current session, controlling which scripts PowerShell will run. Policies include <i>Bypass</i>, <i>RemoteSigned</i>, etc.<br><br><b><b>-Version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the PowerShell version information and then exits.<br><br>


title: DESCRIPTION
content:
<b>pwsh</b> is the command-line executable for <b>PowerShell</b>, Microsoft's powerful cross-platform automation and configuration tool. It provides a rich, interactive shell experience and a scripting language built on .NET. PowerShell is designed for system administrators and developers to manage systems, automate tasks, and build complex solutions. Unlike traditional Unix shells, PowerShell treats everything as an object, allowing for structured data manipulation through a pipeline. It supports a vast ecosystem of modules and cmdlets, enabling deep integration with various services and technologies, both on-premises and in the cloud. It is available on Linux, macOS, and Windows.


title: CAVEATS
content:
While <b>pwsh</b> provides cross-platform compatibility, some modules and cmdlets designed exclusively for Windows environments might not function or behave as expected on Linux. Its startup time can be slightly longer compared to traditional Unix shells like <b>bash</b> or <b>zsh</b>. Proper installation of the .NET runtime is a prerequisite for <b>pwsh</b> to function.


title: MODES OF OPERATION
content:
<b>pwsh</b> can be used in two primary modes: as an <i>interactive shell</i> for immediate command execution and system administration, or as a <i>scripting engine</i> for executing PowerShell scripts (<code>.ps1</code> files) for complex automation tasks. Its rich command history and tab completion enhance the interactive experience.


title: THE OBJECT PIPELINE
content:
A fundamental difference between <b>pwsh</b> and traditional Unix shells is its object-based pipeline. Instead of passing text strings between commands, <b>pwsh</b> passes structured objects. This allows for powerful and precise data manipulation without the need for extensive text parsing, as demonstrated by commands like <code>Get-Process | Where-Object {$_.CPU -gt 100} | Select-Object -First 5</code>.


title: HISTORY
content:
PowerShell originated as <i>Windows PowerShell</i>, first released by Microsoft in 2006 as a command-line shell and scripting language built on the .NET Framework. In 2016, Microsoft open-sourced PowerShell and made it cross-platform by porting it to .NET Core (now simply .NET), renaming it <i>PowerShell Core</i>. The first stable cross-platform release was PowerShell Core 6.0 in January 2018. The executable name for this cross-platform version became <b>pwsh</b>, distinguishing it from the Windows-only `powershell.exe`. Its development continues with regular updates under the modern .NET platform.


title: PARAMETERS
content:
<b><i>-r root_directory</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an alternate root directory to operate on. This is useful when working on a chroot environment or for system recovery, allowing <b>pwunconv</b> to modify files within a different filesystem hierarchy than the current running system.<br><br>


title: DESCRIPTION
content:
The <b>pwunconv</b> command reverts the system's password and group configuration from using shadow files (<i>/etc/shadow</i> and <i>/etc/gshadow</i>) back to storing all information, including encrypted password hashes, directly within <i>/etc/passwd</i> and <i>/etc/group</i>. It essentially undoes the actions of the <i>pwconv</i> and <i>grpconv</i> commands.<br><br>When executed, <b>pwunconv</b> reads the encrypted password entries from <i>/etc/shadow</i> and merges them into the corresponding user entries in <i>/etc/passwd</i>. Similarly, it takes encrypted group password entries from <i>/etc/gshadow</i> and merges them into <i>/etc/group</i>. After successfully merging the data, it removes the <i>/etc/shadow</i> and <i>/etc/gshadow</i> files. This operation requires root privileges.<br><br>While it can be useful for compatibility with very old systems that do not support shadow passwords or for certain system recovery scenarios, its use is <b>strongly discouraged</b> in modern Linux environments due to significant security implications. Storing password hashes in world-readable <i>/etc/passwd</i> makes them vulnerable to brute-force or dictionary attacks, compromising system security.


title: CAVEATS
content:
<b>Security Risk:</b> The primary and most significant caveat is the severe security risk. By moving password hashes from <i>/etc/shadow</i> (which is only readable by root) to <i>/etc/passwd</i> (which is world-readable), <b>pwunconv</b> makes it much easier for unprivileged users or attackers to obtain and crack password hashes. This significantly weakens system security.<br><br><b>Loss of Shadow Files:</b> After execution, <i>/etc/shadow</i> and <i>/etc/gshadow</i> are deleted. Reverting to shadow passwords with <i>pwconv</i> and <i>grpconv</i> would then regenerate new shadow files based on the (now potentially less secure) <i>/etc/passwd</i> and <i>/etc/group</i> content.<br><br><b>Compatibility:</b> While designed for compatibility with older systems, almost all modern Linux distributions and applications expect and rely on shadow passwords. Using <b>pwunconv</b> might lead to unexpected behavior or incompatibilities with certain services or utilities.


title: USAGE WARNING
content:
Due to the severe security implications, <b>pwunconv</b> should generally <i>not</i> be used on production systems. It is primarily a utility for very specific troubleshooting, recovery, or compatibility needs with extremely old systems. Always ensure a full backup of <i>/etc/passwd</i>, <i>/etc/shadow</i>, <i>/etc/group</i>, and <i>/etc/gshadow</i> before attempting to use this command.


title: POST-CONVERSION STATE
content:
After <b>pwunconv</b> completes, <i>/etc/passwd</i> will contain all user information, including password hashes, in its second field, and <i>/etc/group</i> will contain group passwords (if any) in its second field. The 'x' placeholder in <i>/etc/passwd</i> (indicating a shadowed password) will be replaced by the actual hash. The <i>/etc/shadow</i> and <i>/etc/gshadow</i> files will be removed.


title: HISTORY
content:
The <b>pwunconv</b> command is part of the <i>shadow-utils</i> package, which provides tools for managing user and group accounts and their associated password and group files. The concept of shadow passwords emerged in Unix-like systems during the late 1980s and early 1990s as a critical security enhancement. Prior to this, password hashes were stored directly in <i>/etc/passwd</i>, making them readable by all users and thus susceptible to offline cracking attacks.<br><br>The 'shadow' mechanism separated the sensitive password hash information into a dedicated file (<i>/etc/shadow</i>) readable only by the root user, significantly improving security. <b>pwunconv</b> was included as a utility to revert this configuration, primarily for legacy compatibility or specific recovery scenarios, though its usage has become increasingly rare and discouraged as shadow passwords are now the universal standard.


title: SYNOPSIS
content:
Since <I>pxelinux-options</I> isn't a command, its "synopsis" describes how options are structured within a <I>pxelinux.cfg</I> file:<br><br>DEFAULT <I>&lt;label&gt;</I><br>TIMEOUT <I>&lt;seconds&gt;</I><br>PROMPT <I>&lt;0|1&gt;</I><br>MENU TITLE <I>&lt;title_text&gt;</I><br>LABEL <I>&lt;boot_label&gt;</I><br>&nbsp;&nbsp;&nbsp;&nbsp;KERNEL <I>&lt;path_to_kernel&gt;</I><br>&nbsp;&nbsp;&nbsp;&nbsp;APPEND <I>&lt;kernel_command_line_options&gt;</I><br>&nbsp;&nbsp;&nbsp;&nbsp;INITRD <I>&lt;path_to_initrd&gt;</I><br>&nbsp;&nbsp;&nbsp;&nbsp;TEXT HELP<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<I>&lt;description_text&gt;</I>


title: PARAMETERS
content:
<b>DEFAULT</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the default boot entry label to be loaded if no user input is given.<br><br><b>TIMEOUT</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the timeout (in tenths of a second) before the default entry is automatically booted.<br><br><b>PROMPT</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables (1) or disables (0) the boot prompt, allowing user interaction.<br><br><b>MENU TITLE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the title displayed at the top of the boot menu.<br><br><b>LABEL</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines a specific boot entry with a unique identifier, grouping related options.<br><br><b>KERNEL</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the kernel image or bootable executable to load for the current LABEL.<br><br><b>APPEND</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Passes additional command-line arguments directly to the kernel or bootable executable.<br><br><b>INITRD</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the initial RAM disk (initrd or initramfs) to load alongside the kernel.<br><br><b>IPAPPEND</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Appends network information (e.g., IP address, gateway, DNS) to the kernel command line automatically.<br><br><b>TEXT HELP</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines multi-line descriptive help text displayed for a specific menu entry when selected.<br><br>


title: DESCRIPTION
content:
PXELinux is a component of the Syslinux project, specifically designed for booting Linux and other operating systems from a network using the Preboot eXecution Environment (PXE). The "pxelinux-options" refer to the various directives and parameters used within its configuration files, typically located in the <I>tftpboot/pxelinux.cfg/</I> directory on a TFTP server.<br>These options control the boot process, allowing administrators to define boot menus, specify kernel images, pass kernel command-line arguments, load initial RAM disks, and manage various aspects of the network boot. Instead of being a standalone command, "pxelinux-options" are the <I>syntax and semantics</I> used to configure the PXELinux bootloader's behavior when a client machine requests a network boot.


title: CAVEATS
content:
The term "pxelinux-options" refers to configuration directives within a file, not an executable command.<br>Syntax is specific to the Syslinux project and may exhibit minor variations across different versions.<br>Configuration files must be correctly placed in the TFTP server's root directory (e.g., <I>tftpboot/pxelinux.cfg/</I>) and accessible by the client.<br>Kernel command-line options defined with <I>APPEND</I> are critical for proper system boot and frequently differ based on the Linux distribution and desired boot behavior.


title: CONFIGURATION FILE STRUCTURE
content:
PXELinux searches for configuration files in a specific hierarchical order, providing flexibility for different client needs:<br>1. Files matching the client's MAC address (e.g., <I>01-aa-bb-cc-dd-ee-ff</I>).<br>2. Files matching the client's hexadecimal IP address (e.g., <I>C0A80101</I> for <I>192.168.1.1</I>).<br>3. Files based on the client's IP subnet (e.g., <I>C0A80100</I> for <I>192.168.1.0/24</I>).<br>4. The generic <I>default</I> file.<br>This allows administrators to apply configurations ranging from highly specific per-machine settings to broad defaults for an entire network.


title: MENU SYSTEM
content:
PXELinux incorporates a comprehensive menu system, allowing users to select various boot options, operating systems, or diagnostic utilities directly from the boot prompt. This functionality is configured using a set of <I>MENU</I> directives (e.g., <I>MENU LABEL</I>, <I>MENU DEFAULT</I>, <I>MENU HIDE</I>), enabling interactive and user-friendly network booting environments.


title: HISTORY
content:
PXELinux is an integral part of the Syslinux project, originally developed by H. Peter Anvin. It emerged as a crucial tool for large-scale deployments and system provisioning, enabling machines to boot over a network without requiring local storage or optical drives. Its development has focused on providing a robust and flexible framework for network-based operating system installation and recovery, evolving alongside network booting standards and PXE capabilities.


title: SYNOPSIS
content:
<B>py-spy</B> <I>command</I> [options] (--pid <I>PID</I> | -- <I>CMD</I> [ARGS...])<br><br>Common Commands:<br>&nbsp;&nbsp;<B>py-spy record</B> [record_options] (--pid <I>PID</I> | -- <I>CMD</I> [ARGS...])<br>&nbsp;&nbsp;<B>py-spy dump</B> [dump_options] (--pid <I>PID</I> | -- <I>CMD</I> [ARGS...])<br>&nbsp;&nbsp;<B>py-spy top</B> [top_options] (--pid <I>PID</I> | -- <I>CMD</I> [ARGS...])


title: PARAMETERS
content:
<b><I>command</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The <B>py-spy</B> subcommand to execute: <b>record</b> (for flame graphs), <b>dump</b> (for snapshot), or <b>top</b> (for live view).<br><br><b>--pid <I>PID</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attach to a running Python process specified by its Process ID.<br><br><b>-- <I>CMD</I> [ARGS...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run a command and profile the Python process it spawns. Arguments after `--` are passed directly to the command.<br><br><b>--threads</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Profile all Python threads within the target process, not just the main thread.<br><br><b>--subprocesses</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Profile all Python subprocesses spawned by the target process.<br><br><b>--output <I>FILE</I> (-o)</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Used with <b>record</b>) Output the profiling data to the specified file, commonly an SVG for flame graphs.<br><br><b>--format <I>FORMAT</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Used with <b>record</b>) Specify the output format: <B>svg</B> (default), <B>raw</B> (folded stacks), or <B>speedscope</B>.<br><br><b>--rate <I>RATE</I> (-r)</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Used with <b>record</b>, <b>top</b>) Set the sampling rate in samples per second (default is 100 Hz).<br><br><b>--duration <I>SECONDS</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Used with <b>record</b>) Record for a fixed duration in seconds then exit.<br><br><b>--idle</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Used with <b>record</b>) Include frames where the interpreter is idle (e.g., waiting on I/O) in the profiling data.<br><br><b>--full-stack</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Used with <b>dump</b>) Show full Python stack traces, including internal interpreter frames.<br><br><b>--locals</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Used with <b>dump</b>) Include local variables in the stack dump (use with caution as it can reveal sensitive data).<br><br>


title: DESCRIPTION
content:
<B>py-spy</B> is a sampling profiler for Python programs. It allows you to profile any running Python program without restarting the process or modifying the code. Built in Rust for speed and safety, <B>py-spy</B> attaches to the target Python process and samples its call stack at a regular interval. This approach results in <B>very low overhead</B>, making it ideal for use in production environments. It can generate flame graphs, display live `top`-like views of CPU usage, or dump a snapshot of the current call stack. <B>py-spy</B> is particularly useful for identifying performance bottlenecks, CPU utilization issues, and understanding where your Python code spends its time, even when C extensions or native code are involved.


title: CAVEATS
content:
On Linux, <B>py-spy</B> requires either root privileges or the <B>CAP_SYS_PTRACE</B> capability to attach to other processes. It works by directly reading from the target process's memory, which means it may not correctly interpret data if the Python interpreter's internal structures change significantly across Python versions. While low, there is still <B>some overhead</B> introduced by sampling. Ensure the Python interpreter is not stripped of symbols for optimal results.


title: HOW IT WORKS
content:
On Linux, <B>py-spy</B> uses the `ptrace` system call to attach to a running Python process. It then directly reads memory from the target process to identify the Python interpreter's state and reconstruct the call stack. This direct memory access allows it to work without requiring any changes to the Python application's code or interpreter, making it truly non-invasive.


title: PROFILING OUTPUT
content:
The primary output format for the <B>record</B> command is an <B>interactive SVG flame graph</B>. Flame graphs provide a visual representation of the call stack, showing where time is being spent and highlighting hot paths. <B>py-spy</B> also supports raw call stack data output (useful for other analysis tools) and the <B>speedscope</B> format for analysis in the speedscope.app UI, which offers various visualization modes.


title: HISTORY
content:
Developed by Ben Frederickson, <B>py-spy</B> was created to address the need for a <B>low-overhead, non-invasive</B> Python profiler that could be used in production environments without requiring code modifications or application restarts. It is notable for being written entirely in <B>Rust</B>, which contributes to its performance and safety characteristics. Its development started around 2018 and quickly gained traction in the Python community due to its unique capabilities and ease of use compared to traditional Python profilers.


title: SEE ALSO
content:
perf(1), strace(1), gdb(1), Built-in Python profilers (e.g., cProfile, profile), Linux `top` command (for similar live process view)


title: PARAMETERS
content:
<b><b>-v, --verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print versions in a more verbose format, e.g., 'Python 3.x is available.' Each line includes a descriptive message.<br><br><b><b>-r, --requirements</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print versions in a format suitable for <i>requirements.txt</i> files, e.g., 'python3.x'. Useful for specifying interpreter dependencies.<br><br><b><b>-p, --print-path</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the full absolute path to the Python 3 interpreter executable for each detected version. This helps in directly invoking a specific Python version.<br><br><b><b>[VERSIONS]</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional. A space-separated list of Python 3 versions to check for availability. If provided, <i>py3versions</i> will only print versions from this list that are actually installed on the system.<br><br>


title: DESCRIPTION
content:
<i>py3versions</i> is a utility predominantly found on Debian-based Linux distributions (like Ubuntu) that helps identify and list the installed Python 3 interpreter versions. It's often used by maintainer scripts of Python packages to determine which Python 3 versions are available for building or installation. The command lists each detected version on a new line, allowing for easy parsing by other scripts.<br><br>It can also format the output for <i>requirements.txt</i> files or print the full paths to the interpreters. This tool simplifies the process of managing multiple Python 3 installations, ensuring compatibility and proper execution of Python applications across different environments by providing a standardized way to query available versions.


title: CAVEATS
content:
<i>py3versions</i> is primarily a Debian/Ubuntu specific utility and may not be available on other distributions (e.g., Fedora, CentOS, Arch) or might have different behavior. It relies on the standard Python packaging conventions of the distribution; custom Python installations (e.g., via <i>pyenv</i>, <i>conda</i>, or source compilation outside of system paths) might not be detected unless symlinked into standard locations.


title: ENVIRONMENT VARIABLES
content:
The behavior of <i>py3versions</i> can be influenced by environment variables:<br><b>PY3VERSIONS_PRINT_PATH</b>: If this variable is set to any value, it effectively enables the functionality of the <b>--print-path</b> option, causing the command to output full interpreter paths.<br><b>PYBUILD_SYSTEM</b>: While not directly controlling <i>py3versions</i>, this variable relates to <i>pybuild</i>, which uses similar logic for Python version detection, indicating the underlying dependency on this utility for consistent build environments.


title: HISTORY
content:
<i>py3versions</i> emerged as part of the Debian Python packaging efforts, particularly with the transition and co-existence of Python 2 and Python 3. It was designed to standardize how system-wide Python 3 versions are identified and managed by package maintainers. Its development is intertwined with the <i>python3-defaults</i> and <i>python3-minimal</i> packages, providing a stable API for scripts to query available interpreters without hardcoding version numbers, which became crucial as Python 3.x releases continued to evolve. This utility ensures that Python packages can correctly target and utilize the appropriate Python 3 interpreters available on a system.


title: SYNOPSIS
content:
<b>py_compilefiles</b> <i>[OPTIONS]</i> <i>[PATH...]</i><br><i>PATH</i> can be one or more Python source files or directories containing them.


title: PARAMETERS
content:
<b>PATH</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more paths (files or directories) containing Python source code to be compiled. If a directory is specified, it is typically traversed recursively.<br><br><b><b>-O</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Compile with optimization level 1, removing <i>assert</i> statements and storing bytecode in <i>.pyo</i> files. Often controlled by environment or build system.<br><br><b><b>-OO</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Compile with optimization level 2, removing <i>assert</i> statements and <i>docstrings</i>, storing bytecode in <i>.pyo</i> files. Often controlled by environment or build system.<br><br><b><b>-f, --force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force recompilation of all files, even if their timestamps indicate they are up-to-date with their bytecode.<br><br><b><b>-q, --quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress most output messages during the compilation process.<br><br><b><b>-x REGEX</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exclude files or directories matching the specified regular expression during recursive compilation.<br><br>


title: DESCRIPTION
content:
<i>py_compilefiles</i> is a utility primarily used in <i>Linux distribution packaging</i> (e.g., RPMs, Debian packages) to batch compile Python source code files (<i>.py</i>) into optimized bytecode files (<i>.pyc</i> and optionally <i>.pyo</i>). This process translates human-readable Python code into an intermediate format that the Python interpreter can execute more quickly. <br><br>While not a standalone command on all systems, it typically wraps the Python standard library's <i>compileall</i> module, simplifying the compilation of entire directories or specified file lists. Its main purpose is to prepare Python applications for distribution, ensuring faster startup times and efficient execution without needing to compile on the end-user's system.


title: CAVEATS
content:
This command is often an abstraction or a macro provided by Python packaging tools (like <i>python-rpm-macros</i> or <i>dh_python</i> in Debian) rather than a standalone executable with a fixed command-line interface. Its exact behavior and available options can depend on the specific packaging environment or wrapper script implementation. <br><br>Compiled bytecode (<i>.pyc</i> or <i>.pyo</i>) is specific to the Python version it was compiled with and might not be compatible across major Python versions (e.g., Python 3.8 <i>.pyc</i> is not compatible with Python 3.9).


title: PURPOSE IN PACKAGING
content:
In distribution packaging, <b>py_compilefiles</b> is crucial for optimizing deployed Python applications. It avoids the need for on-the-fly compilation at runtime, reducing application startup overhead and improving overall performance for end-users, especially for large Python codebases.


title: BYTECODE OUTPUT
content:
By default, bytecode files (<i>.pyc</i>) are generated in a <i>__pycache__</i> subdirectory next to the corresponding source file. When optimization is applied (e.g., with <b>-O</b>), the files are named <i>.pyo</i> (though often still placed in <i>__pycache__</i> with a specific tag reflecting optimization level).


title: HISTORY
content:
The concept of pre-compiling Python source code into bytecode has been integral to Python since its early versions to improve execution speed. The <i>compileall</i> module, which <i>py_compilefiles</i> typically leverages, was introduced to simplify batch compilation. Over time, as Python gained popularity for application development, packaging systems for Linux distributions (like RPM and Debian packages) integrated utilities like <b>py_compilefiles</b> (often as macros or scripts) to automate the bytecode compilation step during software build processes, ensuring efficient deployment of Python applications.


title: SEE ALSO
content:
<b>python(1)</b>, <b>python -m compileall</b> (the underlying module), <b>dh_python(1)</b> (Debian/Ubuntu Python packaging helper), <b>rpm(8)</b> (RPM package manager)


title: PARAMETERS
content:
<b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message for the <b>pyats</b> command or a specific subcommand.<br><br><b>-v, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the current version of the <b>pyats</b> framework and its components.<br><br><b>--debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose debug output, useful for troubleshooting issues.<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases the verbosity of the output, providing more detailed information during execution.<br><br><b>run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes a specified test script. Requires a test script path and often a testbed file. Example: <i>pyats run my_script.py --testbed my_testbed.yaml</i><br><br><b>learn</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Collects operational state information (e.g., routing tables, interface status) from devices defined in a testbed. Example: <i>pyats learn bgp --testbed my_testbed.yaml</i><br><br><b>diff</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Compares two sets of collected device data (e.g., from two <i>learn</i> operations) to identify differences. Example: <i>pyats diff first_run.json second_run.json</i><br><br><b>clean</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs initial device cleanup and configuration loading, often used to reset devices to a known state before testing. Example: <i>pyats clean my_clean_script.py --testbed my_testbed.yaml</i><br><br><b>config</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manages <b>pyats</b> framework configuration, allowing users to set or get global settings. Example: <i>pyats config set proxy http://proxy.example.com</i><br><br><b>docs</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens the official <b>pyats</b> online documentation in a web browser.<br><br><b>log</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides utilities for viewing and analyzing <b>pyats</b> execution logs.<br><br>


title: DESCRIPTION
content:
The <i>pyATS</i> command-line interface (CLI) provides an entry point to <b>Cisco's Python Automated Test System</b>, a powerful and extensible framework for automating testing and operations of network devices and services. <br><br>At its core, pyATS leverages an <b>Abstract Everything Concept (AEC)</b>, abstracting device interaction complexities and allowing tests to be written against logical device capabilities rather than specific implementations. It comes integrated with <b>Genie</b>, a rich library offering parsers, learn capabilities, and device operations for various Cisco operating systems like IOS XE, NX-OS, and IOS XR. <br><br>pyATS enables engineers to define network topologies using a centralized <i>testbed</i> file, create robust test cases, execute them against live or simulated devices, and generate comprehensive reports. It's designed to streamline functional and regression testing, validate network configurations, and facilitate continuous integration and deployment (CI/CD) pipelines in a network environment, significantly reducing manual effort and improving test coverage.


title: CAVEATS
content:
<b>pyATS</b> primarily targets automation and testing of Cisco network devices, although its extensible architecture allows for integration with other vendors or systems. It requires a Python environment and is typically installed via <i>pip</i>. Users should be aware of the learning curve associated with its comprehensive feature set, especially when utilizing advanced concepts like the Abstract Everything Concept (AEC) and custom extensions. Proper testbed definition and environment setup are crucial for effective use.


title: KEY COMPONENTS
content:
<b>pyATS</b> is built upon several key components:<br><br><b>Testbed</b>: A YAML or Python file that describes the network topology, including devices, links, and credentials, serving as the central inventory for test operations.<br><br><b>Genie</b>: An open-source, highly extensive library built on top of pyATS, providing parsers, learn capabilities, and device operation APIs for various Cisco operating systems. It allows abstracting device output into structured Python objects.<br><br><b>Abstract Everything Concept (AEC)</b>: A core design philosophy of pyATS that promotes writing reusable tests independent of specific device implementations by abstracting away low-level device interactions.


title: INSTALLATION
content:
<b>pyATS</b> is a Python package and is typically installed using <i>pip</i>. It is highly recommended to install it within a Python virtual environment to manage dependencies effectively and avoid conflicts with other Python projects. <br><br>Example: <br><i>pip install pyats pyats.contrib</i> (for basic pyATS and common contributions including Genie)<br><br>Specific versions of Python are often recommended or required, so checking the official documentation is advised.


title: HISTORY
content:
Developed internally by Cisco engineers to standardize and scale network device testing, <b>pyATS</b> has evolved into a robust, enterprise-grade test automation solution. It was later made available to the broader community and Cisco customers through DevNet, Cisco's developer program. Its development has focused on abstraction, reusability, and integration with modern CI/CD practices, incorporating contributions from internal teams and feedback from its growing user base. The integration of <i>Genie</i> has significantly expanded its capabilities for parsing and interacting with Cisco network operating systems.


title: PARAMETERS
content:
<b><b>--testbed-file</b> <i>&lt;file&gt;</i>, <b>-t</b> <i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the YAML testbed file to load into the shell. This file defines network devices, their types, credentials, and connection details.<br><br><b><b>--script-file</b> <i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Loads an external Python script into the shell's namespace at startup. This allows functions, classes, and variables defined in the script to be directly accessible and used interactively.<br><br><b><b>--no-connect</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents the shell from automatically connecting to devices defined in the loaded testbed upon startup. Connections must then be initiated manually within the shell, for example, by calling <i>device.connect()</i>.<br><br><b><b>--log-level</b> <i>&lt;level&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the logging verbosity level for pyATS operations within the shell. Common levels include <i>DEBUG</i>, <i>INFO</i>, <i>WARNING</i>, <i>ERROR</i>, and <i>CRITICAL</i>.<br><br><b><b>--console-log</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables logging output directly to the console during interactive sessions, providing real-time feedback on pyATS actions.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a comprehensive help message for the <b>pyats-shell</b> command and exits.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the current pyATS shell version information and exits.<br><br>


title: DESCRIPTION
content:
The <b>pyats-shell</b> command provides an interactive Python shell environment specifically designed for the Cisco pyATS (Python Automation Test System) framework. It is extensively used for network device automation, testing, and debugging. When launched, it can automatically load specified testbed configurations, making testbed objects, device instances, and pyATS APIs readily available for interactive manipulation. This enables engineers to directly interact with network devices, execute pyATS functions (like connecting, learning, executing commands, configuring), and debug test scripts in a live environment. It's an indispensable tool for developing, verifying, and troubleshooting pyATS-based network automation solutions.


title: CAVEATS
content:
The <b>pyats-shell</b> command is part of the pyATS framework and requires a working pyATS installation. It is specifically tailored for network automation and interaction with devices managed by pyATS, and is not a general-purpose Linux shell. Its effectiveness heavily relies on having correctly configured testbed files and network access to the devices.<br>Proficiency in Python and familiarity with pyATS API concepts are often necessary for effective use.


title: INTERACTIVE USAGE
content:
Once inside the <b>pyats-shell</b>, users can directly access loaded testbed objects (e.g., <i>testbed.devices['my_device']</i>) and call methods on them. For instance, <i>device.connect()</i> to establish a connection, <i>device.learn('os')</i> to gather operating system information, or <i>device.execute('show version')</i> to run CLI commands. This interactive capability makes it a powerful tool for rapid prototyping, troubleshooting, and ad-hoc device interaction.


title: IMPORTANCE OF TESTBED FILES
content:
A well-structured testbed file (typically a YAML file) is fundamental for leveraging the full power of <b>pyats-shell</b>. It defines the network topology, including device names, types, operating systems, connection protocols, credentials, and other essential details. Without a properly configured testbed, the shell's ability to interact with network devices is severely limited, as it lacks the necessary information to establish connections or identify targets.


title: HISTORY
content:
The pyATS (Python Automation Test System) framework, including the <b>pyats-shell</b> component, was initially developed by Cisco for internal use to automate testing and validation of network devices and software. Recognizing its broad utility, Cisco later open-sourced pyATS, making it available to the wider network automation community. The <b>pyats-shell</b> was conceived to provide an intuitive, interactive environment, allowing engineers to rapidly prototype, debug, and execute pyATS functionalities against live networks, significantly streamlining the development and testing workflow for network automation engineers.


title: PARAMETERS
content:
<b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message for the command and exits, providing information on its usage and available options.<br><br><b><b>--json</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the version information in a structured JSON format. This is particularly useful for scripting, parsing the output programmatically, or integrating into automated reporting systems.<br><br><b><b>-f</b>, <b>--full</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides a comprehensive and detailed breakdown of all installed pyATS components and their respective versions. This includes core packages like <i>aetest</i>, <i>genie</i>, <i>unicon</i>, and other dependencies, offering a complete overview of the pyATS ecosystem setup.<br><br>


title: DESCRIPTION
content:
<i>pyats-version</i> is a fundamental utility command within the Cisco pyATS framework, a powerful and extensible Python-based solution for automated network device testing and verification. The primary purpose of this command is to quickly and accurately retrieve the installed version of the pyATS core package and, optionally, its associated sub-packages and dependencies. <br><br> In complex network automation environments, knowing the exact software versions is critical for troubleshooting, ensuring compatibility between test scripts and the framework, and verifying the correct setup of a development or test environment. This command provides a straightforward way for developers, QA engineers, and network automation specialists to confirm their pyATS installation details. <br><br> It helps in identifying whether an outdated version is in use, or if specific components required for certain test functionalities are present and at the expected version. The output can be tailored to be human-readable or machine-parseable (JSON), making it versatile for both interactive use and integration into larger automation workflows or CI/CD pipelines.


title: CAVEATS
content:
This command requires the Cisco pyATS framework to be installed in your Python environment. The exact details provided by the <i>--full</i> option may vary slightly depending on your specific pyATS installation (e.g., installed via pip, from source, or specific distribution). Ensure your Python environment is correctly activated if using virtual environments.


title: USAGE EXAMPLES
content:
To display the basic pyATS version: <br> <i>pyats-version</i> <br><br> To get the full version details of all components: <br> <i>pyats-version --full</i> <br><br> To output the version information in JSON format: <br> <i>pyats-version --json</i>


title: HISTORY
content:
The <i>pyats-version</i> command has been an integral part of the pyATS framework since its early development. Initially conceived as an internal Cisco tool, pyATS was later open-sourced, and the version command remained a core utility for users to quickly ascertain their framework's status. Its functionality has largely remained consistent, with enhancements like the JSON output option being added to cater to modern automation and scripting needs.


title: PARAMETERS
content:
<b>-p<i>&lt;python_version&gt;</i>, --interpreter=<i>&lt;python_version&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the Python interpreter version(s) to use (e.g., <i>python3.9</i>, <i>python3</i>, <i>python2</i>). Can be specified multiple times.<br><br><b>-s<i>&lt;buildsystem&gt;</i>, --buildsystem=<i>&lt;buildsystem&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the use of a specific build system (e.g., <i>distutils</i>, <i>setuptools</i>, <i>poetry</i>, <i>flit</i>, <i>pyproject</i>) instead of auto-detection.<br><br><b>--clean</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform a clean operation on the source directory before building. This is often implicit with <i>dh_auto_clean</i>.<br><br><b>--dir-path=<i>&lt;directory&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the source directory containing the Python project to be built. Defaults to the current directory.<br><br><b>--dest-dir=<i>&lt;directory&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Define the destination directory where built files should be installed. This is typically the package's installation root (e.g., <i>debian/&lt;package&gt;/usr/lib/python3/dist-packages</i>).<br><br><b>--debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose debug output, showing detailed steps and commands executed by <i>pybuild</i>.<br><br><b>--no-guessing</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable automatic build system detection, requiring the build system to be explicitly specified with <i>--buildsystem</i>.<br><br><b>--exclude=<i>&lt;interpreter&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exclude specific Python interpreters from the build process. Can be specified multiple times.<br><br><b>--test-arg=<i>&lt;argument&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pass additional arguments directly to the test command when the <i>test</i> command is invoked.<br><br><b>--parallel</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allow building in parallel. This option is passed to the underlying build system if it supports parallel builds.<br><br>


title: DESCRIPTION
content:
<i>pybuild</i> is a powerful debhelper tool designed to streamline the creation of Debian Python packages. It effectively abstracts away the complexities of managing multiple Python versions (such as Python 2 and Python 3) and diverse Python build systems (including <i>distutils</i>, <i>setuptools</i>, <i>poetry</i>, and <i>flit</i>). <i>pybuild</i> intelligently detects the appropriate build system and orchestrates a standard sequence of operations (configure, build, install) for each Python interpreter supported by the package.<br><br>This significantly simplifies <i>debian/rules</i> files for maintainers, ensuring consistency and adherence to Debian policy for Python applications and libraries. It also handles essential tasks like byte-compilation and the management of .pth files, integrating seamlessly into the <i>dh</i> sequence.


title: CAVEATS
content:
<i>pybuild</i> requires a standard Python project layout with a detectable build system file (e.g., <i>setup.py</i>, <i>pyproject.toml</i>). While it simplifies packaging, highly unconventional build processes may still require custom <i>debian/rules</i> logic.<br><br>Incorrectly configured <i>debian/control</i> files (e.g., missing <i>Build-Depends</i> on <i>dh-python</i> or <i>python3-all</i>) can lead to build failures. Its default behavior is to build all detected Python versions unless explicitly excluded, which might not always be desired for minimal builds.


title: SUPPORTED COMMANDS
content:
<i>pybuild</i> supports several standard build commands that correspond to phases of a build process: <i>configure</i>, <i>build</i>, <i>install</i>, <i>test</i>, and <i>clean</i>. These commands can be invoked explicitly or implicitly by debhelper sequences (e.g., <i>dh_auto_configure</i> will call <i>pybuild configure</i>).


title: AUTOMATIC DETECTION
content:
One of <i>pybuild</i>'s key features is its ability to automatically detect the build system of a Python project by examining files like <i>setup.py</i>, <i>pyproject.toml</i> (for <i>poetry</i>, <i>flit</i>, or standard <i>pyproject</i> builds), or other indicators. This reduces configuration effort for maintainers.


title: INTEGRATION WITH DH
content:
<i>pybuild</i> is designed to work seamlessly within the <i>dh</i> (debhelper) sequence. Commands like <i>dh_auto_configure</i>, <i>dh_auto_build</i>, <i>dh_auto_install</i>, <i>dh_auto_test</i>, and <i>dh_auto_clean</i> will automatically invoke <i>pybuild</i> with the appropriate command when a Python package is detected, simplifying <i>debian/rules</i> to a minimal structure.


title: HISTORY
content:
<i>pybuild</i> was developed to modernize and simplify Python package building within the Debian ecosystem, addressing the challenges posed by the Python 2 to Python 3 transition and the emergence of various Python build tools. Introduced as part of the <i>dh-python</i> package, it aimed to provide a unified and policy-compliant approach, reducing the need for complex, hand-written <i>debian/rules</i> files.<br><br>It evolved to support new build systems like Poetry and Flit, adapting to the dynamic landscape of Python development practices and becoming a cornerstone for Python packaging in Debian.


title: PARAMETERS
content:
<b><I>subcommand</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The specific action to perform. <I>pycentral</I> operates using various subcommands, each executing a distinct task related to Python module management within a Debian package context. Common subcommands include <I>compile</I>, <I>install</I>, <I>register</I>, <I>unregister</I>, and <I>clean</I>.<br><br><b>compile</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs <I>pycentral</I> to byte-compile Python source files (<I>.py</I>) into bytecode files (<I>.pyc</I> and <I>.pyo</I>) within a specified path or package context, improving module load times.<br><br><b>install <I>module</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used during package installation to process and register a Python module or package with the system. This often involves byte-compilation and updating internal module registries.<br><br><b>register <I>module</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Registers a specific Python module with the system's central registry, making it discoverable by the Python interpreter and other applications. This is typically part of the package installation process.<br><br><b>unregister <I>module</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Unregisters a Python module from the system's central registry. This subcommand is primarily used during package removal to clean up module registrations.<br><br><b>clean</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes byte-compiled files (<I>.pyc</I>, <I>.pyo</I>) and other temporary data generated by <I>pycentral</I>, often used in the package clean-up phase.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information for the <I>pycentral</I> utility.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows a help message, detailing the command's usage and listing available subcommands and their basic functions.<br><br>


title: DESCRIPTION
content:
<I>pycentral</I> was a utility included in the <I>python-central</I> Debian package, primarily used in the Debian/Ubuntu packaging ecosystem. Its main purpose was to assist maintainers in handling Python modules during package installation and removal. It provided functionalities for byte-compiling Python source files (<I>.py</I> to <I>.pyc</I> and <I>.pyo</I>), registering installed modules with the system, and managing dependencies. While not a user-facing command for everyday system administration, <I>pycentral</I> played a crucial role in ensuring that Python packages were correctly integrated into the system, making their modules discoverable by the Python interpreter.<br><br>Over time, its functionality has largely been superseded by newer, more robust tools like <I>dh_python2</I> and <I>dh_python3</I> (part of <I>debhelper</I>), which streamline Python package building and comply with modern Python packaging standards, including PEP 394 and PEP 397 for Python 2 and 3 compatibility. As a result, <I>pycentral</I> is now considered deprecated and is rarely used in modern Debian/Ubuntu packages. Its design aimed to centralize Python module management, hence the "central" in its name.


title: CAVEATS
content:
The <I>pycentral</I> utility is considered <I>deprecated</I> and is rarely used in modern Debian/Ubuntu packaging. Its functionalities have been superseded by newer tools like <I>dh_python2</I> and <I>dh_python3</I> from the <I>debhelper</I> suite. Using <I>pycentral</I> in new projects or attempting to manage Python environments directly with it is not recommended, as it can lead to conflicts with standard Python packaging practices (e.g., <I>pip</I>, <I>virtualenv</I>) and may not be compatible with newer Python versions or distribution layouts. It was specifically designed for the Debian packaging system's needs, not for general Python development workflows.


title: ROLE IN DEBIAN/UBUNTU PACKAGING
content:
<I>pycentral</I> was designed exclusively for the Debian/Ubuntu packaging system. It was typically invoked by <I>debian/rules</I> build scripts to perform actions like byte-compiling Python source files and registering module paths with a central registry that the system's Python interpreter could use. It was not intended for direct use by end-users for managing their Python environments or installing Python packages outside the distribution's package manager (<I>apt</I>/<I>dpkg</I>).


title: BYTE-COMPILATION
content:
One of the primary functions of <I>pycentral</I> was to handle the byte-compilation of Python source files. When Python code is executed, it is first compiled into bytecode, which is then run by the Python Virtual Machine. <I>pycentral</I> automated the creation of <I>.pyc</I> (compiled bytecode) and <I>.pyo</I> (optimized bytecode) files during package installation, which could potentially speed up subsequent module imports by avoiding recompilation on each run.


title: HISTORY
content:
<I>pycentral</I> was introduced as part of the <I>python-central</I> package in the Debian GNU/Linux distribution. Its development aimed to provide a standardized, centralized mechanism for Debian packages to manage Python modules, including byte-compilation and registration, ensuring consistency across the system. It was a key component for Python package maintainers during the Debian Etch, Lenny, and Squeeze eras.<br><br>However, with the evolution of Python packaging standards (like PEP 394 for Python 2/3 compatibility) and the introduction of more flexible and robust build tools within the <I>debhelper</I> framework (specifically <I>dh_python2</I> and <I>dh_python3</I>), <I>pycentral</I>'s approach became less suitable for modern packaging needs. Consequently, its use has been actively discouraged and largely replaced since Debian 7 (Wheezy) and Ubuntu 12.04 (Precise Pangolin), making it a historical artifact in the Debian packaging system rather than a current tool.


title: PARAMETERS
content:
<b>-V, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the version number and exit.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Turn on verbose messages, listing each processed file and directory.<br><br><b>-d, --dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform a dry run without actual file removal, useful for testing.<br><br><b>-p, --path</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Walk through all directories in <i>sys.path</i> and remove byte-compiled files. This also enables <i>-f</i> by default.<br><br><b>-i, --interactive</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ask for confirmation before removing files.<br><br><b>-k, --keep-cache-dir</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not remove <i>__pycache__</i> directories. This option implies <i>-X __pycache__</i>.<br><br><b>-r, --recursive</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Recursively walk the directories given on the command line. This is the default if no directories are provided.<br><br><b>-q, --quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Turn off all messages, overriding verbose output.<br><br><b>-f, --force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force removal of all byte-compiled files, even if not writable (useful for root).<br><br><b>-X, --exclude=PATTERN</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exclude files or directories matching <i>PATTERN</i> from consideration. This option can be used multiple times.<br><br><b>dir_or_file ...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more directories or files to process. If no arguments are given, <b>pyclean</b> will recursively walk the current directory.<br><br>


title: DESCRIPTION
content:
<b>pyclean</b> is a utility designed to clean up Python source trees by removing byte-compiled <i>.pyc</i> and <i>.pyo</i> files. For Python 3.2 and newer versions, it also cleans up <i>__pycache__</i> directories, which store bytecode files in a structured manner. These generated files are typically created when Python scripts are executed and serve to speed up subsequent executions by avoiding recompilation. While beneficial for performance, they can clutter development directories, especially across different Python versions or when changing code frequently. <b>pyclean</b> helps maintain a clean source tree, making it easier to manage code, distribute projects without unnecessary compiled artifacts, and avoid potential issues caused by stale bytecode. It can operate on specified directories or recursively clean the current directory by default, providing options for verbose output, dry runs, interactive deletion, and exclusion patterns. This command is particularly useful in development environments, build systems, or packaging processes where temporary build artifacts need to be cleared efficiently.


title: CAVEATS
content:
<b>pyclean</b> can remove files that are not strictly necessary for running Python applications but are useful for performance.<br>Using the <i>--force</i> option can remove files even if they are not writable, which should be used with caution, especially when running as root.<br>Care should be taken when using <i>--path</i> as it affects all directories in the Python <i>sys.path</i>, potentially cleaning system-wide or site-packages directories if not careful.


title: HISTORY
content:
The <b>pyclean</b> utility is primarily associated with Debian-based Linux distributions, developed by Thomas Viehmann. It was greatly inspired by the earlier `pycentral` utility, which also dealt with managing Python bytecode files. Its development focuses on providing a convenient and integrated way to clean up Python environments within the Debian ecosystem, adapting to changes in Python's bytecode caching mechanisms (e.g., the introduction of <i>__pycache__</i> directories in Python 3.2).


title: PARAMETERS
content:
<b>--first</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show only the first occurrence of each error.<br><br><b>--show-source</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the source code line for each error.<br><br><b>--statistics</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print count of errors and warnings.<br><br><b>--count</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the total number of errors and warnings.<br><br><b>--max-line-length <n></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the maximum allowed line length (default 79).<br><br><b>--ignore <errors></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exclude specific error codes (e.g., E501, W292).<br><br><b>--select <errors></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Select specific error codes to report.<br><br><b>--exclude <patterns></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exclude files or directories matching patterns.<br><br><b>--diff</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Report errors only on changed lines in a diff.<br><br><b>--config <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a custom path to a configuration file.<br><br><b>--format <format></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the error output format (e.g., default, pylint).<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show program's version number and exit.<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print status messages and more detailed output.<br><br>


title: DESCRIPTION
content:
<I>pycodestyle</I> is a command-line tool used to check Python code against the PEP 8 style guide. It analyzes source files for common stylistic and programmatic errors, ensuring consistency and readability across projects. Originally known as <I>pep8</I>, it was renamed to avoid confusion with the PEP 8 document itself. Its primary purpose is to enforce a standardized coding style, making code easier to read, understand, and maintain for developers. It can be integrated into development workflows, CI/CD pipelines, or run manually during development. It helps identify issues like incorrect indentation, trailing whitespace, naming conventions, and line length violations.


title: CAVEATS
content:
<I>pycodestyle</I> focuses strictly on PEP 8 style and may not catch all logical or semantic errors in code. Its strictness can sometimes lead to numerous warnings, which might require careful configuration using ignore lists or project-specific settings. It can also produce false positives for certain complex code structures. Effective use often involves integration with configuration files like <I>setup.cfg</I> or <I>pycodestyle.ini</I> to tailor its behavior to specific project needs.


title: CONFIGURATION FILES
content:
<I>pycodestyle</I> supports configuration via standard Python project files such as <I>setup.cfg</I>, <I>tox.ini</I>, or a dedicated <I>pycodestyle.ini</I> file. These files allow users to define default options like <B>max-line-length</B>, <B>ignore</B> codes, or <B>exclude</B> paths, enabling consistent style checks across a project without repetitive command-line arguments.


title: EXIT STATUS
content:
The command exits with a status of 0 if no errors or warnings are found in the checked files. A non-zero exit status (typically 1) indicates that one or more issues were detected. This behavior makes <I>pycodestyle</I> suitable for use in automated scripts and CI/CD pipelines to enforce coding standards.


title: HISTORY
content:
The tool was originally developed by Florent Aide and was known as <I>pep8.py</I> or simply <I>pep8</I>. It was created to provide a command-line utility for checking Python code against the PEP 8 style guide, which defines conventions for Python code layout. The project was later renamed to <I>pycodestyle</I> in 2016-2017 to clarify that it is an implementation of the PEP 8 checks, not the PEP 8 document itself, and to avoid naming conflicts, especially as PEP 8 is a living document.


title: SEE ALSO
content:
flake8(1): A wrapper for pycodestyle, pyflakes, and McCabe complexity checks., pylint(1): A comprehensive static code analyzer for Python., black(1): An uncompromising Python code formatter., isort(1): A Python utility to sort imports alphabetically and automatically separate into sections.


title: PARAMETERS
content:
<b><i>-O</i>, <i>--optimize</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Compile with optimization level 1. Generates <i>.pyc</i> files without docstrings.<br><br><b><i>-OO</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Compile with optimization level 2. Generates <i>.pyc</i> files without docstrings and assertions.<br><br><b><i>-V</i>, <i>--version</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show program's version number and exit.<br><br><b><i>-f</i>, <i>--force</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force recompilation of all files, even if timestamps are current.<br><br><b><i>-p</i>, <i>--package</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the package name (used by Debian packaging tools).<br><br><b><i>-r</i>, <i>--remove</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remove obsolete bytecode files (e.g., from old Python versions or uninstalled source).<br><br><b><i>-X</i>, <i>--exclude</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exclude files or directories matching the given pattern.<br><br><b><i>-s</i>, <i>--single-version-externally-managed</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;For specific Python package management setups (usually related to <i>distutils</i> or <i>setuptools</i>).<br><br><b><i>-v</i>, <i>--verbose</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increase verbosity of output.<br><br><b><i>--</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Separator indicating the end of options; subsequent arguments are treated as paths.<br><br><b><i>path ...</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more paths to directories or specific Python source files to compile. If omitted, it may default to common system Python paths.<br><br>


title: DESCRIPTION
content:
<i>pycompile</i> is a utility used to byte-compile Python source files (<i>.py</i>) into bytecode files (<i>.pyc</i>, or <i>.pyo</i> for optimized versions). This process improves the startup time of Python applications and reduces the need for source code distribution.<br><br>It primarily works by locating Python source files within specified paths and invoking the appropriate Python interpreter with its built-in compilation modules (like <i>py_compile</i> or <i>compileall</i>). While <i>pycompile</i> can be run manually, its most common use case is within Debian-based packaging systems, particularly by maintainer scripts like <i>dh_python3</i> or <i>dh_python2</i>. It ensures that system-wide Python installations or distributed packages include pre-compiled bytecode, optimizing performance and adherence to system standards. It handles different Python versions and manages the creation and removal of bytecode files, including those in <i>__pycache__</i> directories for Python 3.


title: CAVEATS
content:
<i>pycompile</i> is primarily a utility within the Debian/Ubuntu ecosystem for managing Python bytecode during package installation and removal. It may not be available or function identically on other Linux distributions. Users should ensure they have write permissions in the directories where bytecode files are to be created or removed. Misuse can lead to unnecessary recompilations or removal of valid bytecode.


title: PYTHON BYTECODE AND PERFORMANCE
content:
Python bytecode (<i>.pyc</i> files) is an intermediate, platform-independent representation of Python source code. When a <i>.py</i> file is first imported, Python compiles it into bytecode and caches it. Subsequent imports skip the compilation step, leading to faster startup times. <i>pycompile</i> automates this process for system-wide or packaged Python code, ensuring that the performance benefits are realized without manual intervention. The <i>-O</i> and <i>-OO</i> flags allow for further optimization by removing docstrings and assertions, reducing the size of bytecode files, which can be beneficial in resource-constrained environments.


title: __PYCACHE__ DIRECTORIES
content:
For Python 3, bytecode files are typically stored in a subdirectory named <i>__pycache__</i> located within the package directory. For example, <i>module.py</i> will have its bytecode stored as <i>__pycache__/module.cpython-3x.pyc</i>. This structure helps keep the main package directory clean and supports multiple Python versions by including version-specific tags in the bytecode filename. <i>pycompile</i> correctly manages these <i>__pycache__</i> directories, including their creation, update, and removal.


title: HISTORY
content:
<i>pycompile</i> emerged as a crucial component of Debian's Python packaging infrastructure. Its development aimed to standardize the byte-compilation of Python modules across system installations, ensuring efficient execution and proper dependency management. It evolved significantly with the transition from Python 2 to Python 3, adapting to changes like the introduction of the <i>__pycache__</i> directory for Python 3 bytecode and handling multiple Python versions concurrently on a single system.


title: SYNOPSIS
content:
<b>pydoc</b> [<i>options</i>] [<i>name</i>]<br><b>pydoc</b> -k <i>keyword</i><br><b>pydoc</b> -p <i>port</i><br><b>pydoc</b> -g<br><b>pydoc</b> -w <i>name</i>


title: PARAMETERS
content:
<b><i>name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the name of a module, function, class, method, or topic for which to display documentation. If omitted, <i>pydoc</i> launches an interactive help session.<br><br><b><b>-k</b> <i>keyword</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Searches the documentation for a specified <i>keyword</i>, listing modules that contain the keyword in their summary lines.<br><br><b><b>-p</b> <i>port</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts an HTTP server on the specified <i>port</i>, allowing you to browse documentation using a web browser. Typically used with <b>-b</b> or <b>-n</b>.<br><br><b><b>-g</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Launches a graphical user interface (GUI) browser for documentation, requiring the Tkinter module to be installed.<br><br><b><b>-w</b> <i>name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the HTML documentation for the specified <i>name</i> to a file in the current directory, typically named '<i>name</i>.html'.<br><br><b><b>-n</b> <i>hostname</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the <i>hostname</i> for the HTTP server when used with <b>-p</b>. This allows for binding the server to a specific network interface.<br><br><b><b>-b</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts an HTTP server (implies <b>-p</b> and <b>-n</b>) and automatically opens a web browser to the server's documentation page. Uses the default web browser configured on your system.<br><br>


title: DESCRIPTION
content:
<i>pydoc</i> is a command-line utility and Python module that automatically generates and displays documentation from Python modules, functions, classes, and keywords. It acts as an invaluable tool for developers seeking quick access to reference materials without leaving the terminal. <i>pydoc</i> can present <i>help()</i>-style output directly in your console, launch an HTTP server to browse documentation through a web browser, or even write module documentation to an HTML file for offline viewing. By leveraging Python's introspection capabilities and docstrings, <i>pydoc</i> provides dynamic and up-to-date information on installed Python components. It's a standard part of the Python distribution, offering a convenient way to understand how various Python elements work.


title: CAVEATS
content:
The <b>-g</b> option requires Python's Tkinter module to be installed, which might not be present in minimal Python installations. The <b>-b</b> option relies on a default web browser being correctly configured and accessible in your environment. <i>pydoc</i> documents installed Python modules; it cannot directly document arbitrary <i>.py</i> files unless they are discoverable via <i>PYTHONPATH</i> or the current working directory. The quality and completeness of documentation depend entirely on the docstrings written by module developers.


title: ENVIRONMENT VARIABLES
content:
Several environment variables can influence <i>pydoc</i>'s behavior:<br><b>PAGER</b>: Specifies the program to use for displaying documentation (e.g., <i>less</i>, <i>more</i>). If not set, <i>pydoc</i> attempts to use <i>less</i> or <i>more</i>.<br><b>BROWSER</b>: Specifies the web browser to use for the <b>-b</b> option. If not set, <i>pydoc</i> tries to find a suitable browser.<br><b>PYTHONDOCS</b>: Specifies the path to the Python library documentation (e.g., <i>.../pythonX.Y/Doc/</i>).<br><b>PYTHONPATH</b>: Influences where <i>pydoc</i> searches for modules, similar to how Python itself finds modules.


title: EXAMPLES OF USAGE
content:
To display documentation for the 'os' module:<br><i>pydoc os</i><br><br>To search for modules containing 'datetime':<br><i>pydoc -k datetime</i><br><br>To start an HTTP server on port 8000:<br><i>pydoc -p 8000</i><br><br>To write HTML documentation for the 'json' module to a file:<br><i>pydoc -w json</i>


title: HISTORY
content:
<i>pydoc</i> has been a standard and integral part of the Python distribution since at least Python 2.2, if not earlier. Its inception aimed to provide developers with a convenient and consistent way to access documentation for Python modules, classes, functions, and topics directly from the command line or via a web interface, mirroring the functionality of the <i>help()</i> built-in function within the Python interpreter. It leverages Python's powerful introspection capabilities to dynamically generate documentation from docstrings, making it a continuously relevant tool as libraries evolve.


title: SYNOPSIS
content:
<b>pydoc2.7</b> [<i>options</i>] [<i>name</i>]<br><b>pydoc2.7</b> -k <i>keyword</i><br><b>pydoc2.7</b> -p <i>port</i><br><b>pydoc2.7</b> -w <i>name</i>


title: PARAMETERS
content:
<b>-k <i>keyword</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Searches for topics matching the provided <i>keyword</i> across all accessible Python modules and documentation.<br><br><b>-p <i>port</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts an HTTP server on the specified <i>port</i>, allowing access to documentation through a web browser.<br><br><b>-w <i>name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the documentation for the specified <i>name</i> (module, class, function) to an HTML file in the current directory.<br><br><b>-g</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Launches a graphical help browser using Tkinter (if available), providing an interactive GUI for navigating documentation.<br><br><b><i>name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the name of the module, function, class, or keyword for which documentation is to be displayed.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the help message and exits.<br><br><b>-V, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the program's version number and exits.<br><br>


title: DESCRIPTION
content:
pydoc2.7 is a utility included with the Python 2.7 distribution that automatically generates and displays documentation from Python modules, classes, functions, and keywords. It allows developers to quickly access help and documentation for Python objects directly from the command line, an HTTP server, or by generating static HTML files. This tool parses Python source code, extracts <i>docstrings</i>, and presents them in a readable format. It's particularly useful for quickly understanding the functionality of built-in modules or custom libraries without needing an internet connection, especially for older Python 2.7 projects.


title: CAVEATS
content:
<b>Python 2.7 Specific:</b> This command is strictly for Python 2.7 environments and will not work with Python 3.x installations. Python 2.7 reached its end-of-life (EOL) in 2020, meaning `pydoc2.7` should primarily be used for legacy projects.<br><b>Dependencies:</b> The `<i>-g</i>` option requires the Tkinter library to be installed and correctly configured with your Python 2.7 environment.<br><b>`PYTHONPATH` Reliance:</b> For `pydoc2.7` to find non-standard modules, they must be discoverable via the `PYTHONPATH` environment variable or be located in the standard Python site-packages directories.


title: MODES OF OPERATION
content:
pydoc2.7 offers several ways to consume documentation: directly on the console, through a local HTTP server accessible via a web browser, by generating static HTML files, or via a graphical user interface (if Tkinter is available).


title: RELIANCE ON DOCSTRINGS
content:
The effectiveness of pydoc2.7 heavily depends on well-written <i>docstrings</i> within Python code. It automatically extracts and formats these strings, making well-documented code easily discoverable and understandable.


title: HISTORY
content:
`pydoc` has been a fundamental utility within the standard Python distribution since the early days of Python 2.x, designed to provide developers with immediate, offline access to documentation. The specific `pydoc2.7` executable emerged on systems where multiple Python versions (e.g., Python 2.7 and Python 3.x) coexist, ensuring that the correct `pydoc` version is invoked for Python 2.7 modules. Its importance peaked during the Python 2.x era, serving as a primary tool for understanding library functions and module structures. With Python 2.7's end-of-life in 2020, its usage has largely shifted towards maintaining legacy systems, while modern Python development primarily uses `pydoc` (for Python 3) or more advanced documentation tools like Sphinx.


title: SYNOPSIS
content:
<b>pydoc3.4</b> [<i>options</i>] <i>name</i><br><b>pydoc3.4</b> -k <i>keyword</i><br><b>pydoc3.4</b> -p [<i>port</i>]<br><b>pydoc3.4</b> -b<br><b>pydoc3.4</b> -g<br><b>pydoc3.4</b> -w <i>name</i>


title: PARAMETERS
content:
<b><i>name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of a Python module, function, class, method, or keyword for which to display documentation. This is a positional argument.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the help message for <i>pydoc3.4</i> and exit.<br><br><b><b>-b</b>, <b>--browser</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Start an HTML browser (requiring Tkinter) to view the module documentation. If Tkinter is not installed or available for Python 3.4, this option will fail.<br><br><b><b>-g</b>, <b>--gui</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Launch the Tkinter-based GUI help browser. Like <b>-b</b>, this option requires the Tkinter module to be installed and accessible for Python 3.4.<br><br><b><b>-k</b> <i>keyword</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Search for a given <i>keyword</i> within the documentation summary lines of all available modules and objects. This is useful for finding relevant functionality.<br><br><b><b>-p</b> [<i>port</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Start an HTTP server on the specified <i>port</i> (default is 7469) to serve documentation. If no port is provided, <i>pydoc3.4</i> will attempt to use a random available port. You can then access the documentation through a web browser.<br><br><b><b>-w</b> <i>name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Write the HTML documentation for the specified <i>name</i> (module or object) to a file named <i>name</i>.html in the current working directory.<br><br>


title: DESCRIPTION
content:
<i>pydoc3.4</i> is a command-line utility for interactive access to Python's built-in documentation. It leverages the introspection capabilities of Python to extract docstrings from modules, classes, functions, and methods, presenting them in a readable format. This utility can display documentation directly in the terminal using a pager, launch a graphical help browser (if Tkinter is available), start an HTTP server to browse documentation via a web browser, or write documentation to an HTML file. The <i>pydoc3.4</i> command specifically invokes the <i>pydoc</i> utility associated with a Python 3.4 installation on the system. It's an invaluable tool for developers to quickly understand the functionality and usage of Python code without leaving the command line or requiring an internet connection.


title: CAVEATS
content:
The functionality of <i>pydoc3.4</i> is directly tied to the presence and configuration of a Python 3.4 installation on your system. Specifically, the <b>-b</b> and <b>-g</b> options for graphical browsing will not work if the Tkinter module is not properly installed and linked to your Python 3.4 environment. Additionally, the quality and completeness of the documentation generated by <i>pydoc3.4</i> are entirely dependent on the docstrings present within the Python code itself.


title: INTERACTIVE MODE
content:
When <i>pydoc3.4</i> is executed without any command-line arguments (e.g., simply <b>pydoc3.4</b>), it enters an interactive, text-based help system. In this mode, users can type the names of modules, functions, classes, or other Python objects, and <i>pydoc3.4</i> will display their respective documentation, much like using the <b>help()</b> function directly within the Python interactive interpreter.


title: COMPREHENSIVE SEARCH
content:
The <b>-k</b> (keyword) option provides a highly efficient method for searching through the documentation of all installed Python modules. It performs a keyword match against the summary lines (typically the first line of docstrings) of all available modules and their contents, enabling users to quickly discover relevant code components or functionalities without prior knowledge of their exact names or locations.


title: HISTORY
content:
The <i>pydoc</i> utility has been a fundamental component of Python's standard library since Python 2.x, designed to provide developers with convenient, built-in access to documentation. Its introduction streamlined the process of retrieving information from Python's powerful introspection capabilities and docstrings. The <i>pydoc3.4</i> command specifically denotes the invocation of this utility under a Python 3.4 environment, showcasing its consistent role and availability across various Python versions as a core documentation tool.


title: PARAMETERS
content:
<b>--version, -v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show program's version number and exit.<br><br><b>--help, -h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show help message and exit.<br><br><b>--quiet, -q</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress file names in output, print only error codes.<br><br><b>--select=CODES, -s CODES</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify specific error codes to report.<br><br><b>--ignore=CODES, -i CODES</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify specific error codes to ignore.<br><br><b>--add-select=CODES</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add error codes to report to existing selections.<br><br><b>--add-ignore=CODES</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add error codes to ignore to existing ignores.<br><br><b>--convention=NAME</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Choose a docstring convention (e.g., <i>pep257</i>, <i>numpy</i>).<br><br><b>--config=PATH</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an alternative configuration file path.<br><br><b>--count</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the total number of errors found.<br><br><b>--explain=CODE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show a detailed explanation for an error code.<br><br><b>--show-source</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the source code line for each error.<br><br><b>--match=PATTERN</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Check files whose base names match the pattern (default: <i>*.py</i>).<br><br><b>--match-dir=PATTERN</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Check directories whose base names match the pattern (default: <i>.*</i>).<br><br><b>--exclude=PATTERN</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exclude files or directories matching the pattern.<br><br><b>--ignore-decorators=PATTERN</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ignore functions/methods decorated by a matching pattern.<br><br><b>PATHS...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more files or directories to check. If omitted, checks the current directory.<br><br>


title: DESCRIPTION
content:
<i>pydocstyle</i> is a static analysis tool for checking Python code against PEP 257, the Python Docstring Conventions. It helps developers ensure their docstrings adhere to a consistent style and structure, improving code readability and maintainability. The tool scans Python files and reports violations such as missing docstrings, incorrect formatting, or non-standard content. While it primarily focuses on PEP 257, it also supports conventions like NumPy-style docstrings. By integrating <i>pydocstyle</i> into development workflows, teams can automate the enforcement of docstring standards, making documentation more reliable and easier to understand.


title: CAVEATS
content:
<i>pydocstyle</i> strictly enforces PEP 257 by default, which may not align perfectly with all project docstring styles. Users often need to configure it with specific <i>select</i> or <i>ignore</i> codes to fit their needs. It only checks docstring conventions and does not perform general Python code style or syntax checks. Large codebases might require fine-tuning of configuration to avoid excessive noise.


title: CONFIGURATION FILES
content:
<i>pydocstyle</i> can be configured via <i>pyproject.toml</i> (recommended), <i>setup.cfg</i>, <i>.pydocstylerc</i>, or <i>.pydocstylerc.ini</i> files. These files allow users to define default options like ignored error codes, selected conventions, and file/directory patterns.


title: EXIT CODES
content:
The command returns a non-zero exit code if any docstring style violations are found, making it suitable for integration into CI/CD pipelines. An exit code of 0 indicates no errors.


title: HISTORY
content:
<i>pydocstyle</i> was originally developed as <i>pep257</i>. It was later renamed to <i>pydocstyle</i> to avoid confusion with PEP 257 itself and to better reflect its broader capabilities beyond just the PEP 257 standard, such as support for NumPy docstring conventions. The renaming aimed to signify its evolution into a more flexible and comprehensive docstring linter for Python.


title: PARAMETERS
content:
<b><b>install</b> <<i>version</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Installs a specific Python version (e.g., <i>3.9.7</i>).<br><br><b><b>uninstall</b> <<i>version</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uninstalls a previously installed Python version.<br><br><b><b>global</b> <<i>version</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the global Python version to be used by default across all shells.<br><br><b><b>local</b> <<i>version</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a project-specific Python version, usually by creating a <i>.python-version</i> file in the current directory.<br><br><b><b>shell</b> <<i>version</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a session-specific Python version, active only for the current shell session.<br><br><b><b>versions</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all installed Python versions and indicates the currently active one.<br><br><b><b>which</b> <<i>command</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the full path to an executable (e.g., <i>python</i>, <i>pip</i>) managed by <b>pyenv</b>.<br><br><b><b>rehash</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Rebuilds <b>pyenv</b> shims to ensure that newly installed executables are found.<br><br><b><b>virtualenv</b> <<i>python_version</i>> <<i>env_name</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a virtual environment using a specific Python version (requires <b>pyenv-virtualenv</b> plugin).<br><br><b><b>activate</b> <<i>env_name</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Activates a <b>pyenv</b> managed virtual environment (requires <b>pyenv-virtualenv</b> plugin).<br><br><b><b>deactivate</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deactivates an active <b>pyenv</b> managed virtual environment.<br><br><b><b>update</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Updates <b>pyenv</b> and its plugins (requires <b>pyenv-update</b> plugin).<br><br><b><b>help</b> [<i>command</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays helpful information about <b>pyenv</b> or a specific subcommand.<br><br>


title: DESCRIPTION
content:
<b>pyenv</b> is a simple, yet powerful command-line tool that allows you to manage multiple Python versions on a single machine. It enables seamless switching between different Python interpreters (e.g., Python 2.7, 3.8, 3.9) for various projects without interfering with your system Python or other applications.<br><br>Unlike other version managers, <b>pyenv</b> operates by modifying your PATH environment variable and utilizing a concept called "shims," rather than relying on <b>sudo</b> or directly altering system files. This design ensures that <b>pyenv</b> works on a per-user basis, providing an isolated and consistent environment for development. It also integrates well with <b>virtualenv</b> and <b>conda</b> through plugins, extending its utility to manage project-specific dependencies. Its primary benefit lies in preventing dependency conflicts, facilitating testing across different Python versions, and maintaining a clean development setup for Python applications.


title: CAVEATS
content:
<ul><li><b>pyenv</b> manages Python <i>versions</i>, not Python packages. For package management, you still need <b>pip</b> or <b>conda</b>.</li><li>Requires specific PATH setup and shell initialization scripts (e.g., <i>~/.bashrc</i>, <i>~/.zshrc</i>) to function correctly.</li><li>Python versions installed by <b>pyenv</b> are built from source, which might require development tools and libraries to be present on your system.</li><li>Does not manage system-wide Python installations or packages that rely on them.</li></ul>


title: INSTALLATION & SETUP
content:
To use <b>pyenv</b>, it typically needs to be cloned from its GitHub repository, added to your shell's PATH, and then initialized in your shell's configuration file (e.g., <i>.bashrc</i>, <i>.zshrc</i>). This setup ensures that <b>pyenv</b>'s <i>shims</i> directory is prepended to your PATH, allowing it to intercept <b>python</b> and <b>pip</b> commands.


title: HOW IT WORKS (SHIMS)
content:
<b>pyenv</b> does not alter your system Python. Instead, it works by placing <i>shims</i> (small executable files) in your PATH that intercept calls to <b>python</b>, <b>pip</b>, and other Python-related executables. When you run <b>python</b>, <b>pyenv</b>'s shim takes over, determines which Python version is active (based on <b>global</b>, <b>local</b>, or <b>shell</b> settings), and then transparently redirects the call to the correct Python interpreter installed by <b>pyenv</b>. The <b>pyenv rehash</b> command is crucial as it rebuilds these shims after new Python versions or packages with executables are installed.


title: PLUGIN ECOSYSTEM
content:
<b>pyenv</b>'s functionality can be greatly extended through its plugin system. Key plugins include <b>pyenv-virtualenv</b> for seamless integration with Python virtual environments, <b>pyenv-update</b> for easy updates of <b>pyenv</b> itself, and <b>pyenv-doctor</b> for checking build dependencies. These plugins are usually installed alongside <b>pyenv</b> or separately from their respective GitHub repositories.


title: HISTORY
content:
<b>pyenv</b> was created by Yamashita, inspired by <b>rvm</b> (Ruby Version Manager) and <b>nvm</b> (Node Version Manager). It filled a significant gap in the Python ecosystem for managing multiple interpreters in a user-friendly and non-invasive way. Its initial releases focused on the core functionality of installing and switching Python versions.<br><br>Over time, its modular design allowed for a rich plugin ecosystem, notably <b>pyenv-virtualenv</b> (for virtual environment management) and <b>pyenv-update</b> (for easier self-updates), which have become essential components of the <b>pyenv</b> experience. It has gained widespread adoption in the Python community due to its reliability and flexibility.


title: SYNOPSIS
content:
<b>pyenv virtualenv</b> [<b>-f</b>|<b>--force</b>] [<b>-p</b>|<b>--prompt</b> <i>&lt;prompt&gt;</i>] [<b>--system-site-packages</b>] <i>&lt;python_version&gt; &lt;environment_name&gt;</i><br><b>pyenv activate</b> <i>&lt;environment_name&gt;</i><br><b>pyenv deactivate</b><br><b>pyenv virtualenvs</b><br><b>pyenv virtualenv-delete</b> <i>&lt;environment_name&gt;</i>


title: PARAMETERS
content:
<b><b>&lt;python_version&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The <i>pyenv</i>-installed Python version to base the new virtual environment on (e.g., <code>3.9.10</code>, <code>3.8.5</code>).<br><br><b><b>&lt;environment_name&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique name to assign to the new virtual environment. This name is used for activation and deletion.<br><br><b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the creation of the virtual environment, overwriting an existing one with the same name if it already exists.<br><br><b><b>-p</b>, <b>--prompt</b> <i>&lt;prompt&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a custom prefix for the shell prompt when the virtual environment is activated.<br><br><b><b>--system-site-packages</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Gives the new virtual environment access to the global <code>site-packages</code> directory of the base Python installation.<br><br>


title: DESCRIPTION
content:
<i>pyenv-virtualenv</i> is a <i>pyenv</i> plugin that provides robust integration with <i>virtualenv</i> and <i>conda</i>, streamlining the management of Python virtual environments. It extends <i>pyenv</i>'s core functionality, allowing users to effortlessly create, activate, deactivate, and list isolated Python environments directly via <i>pyenv</i> commands. This eliminates the need to manually invoke <i>virtualenv</i> or <i>conda</i> commands, simplifying dependency management for different projects. By integrating with <i>pyenv</i>'s shim mechanism, <i>pyenv-virtualenv</i> ensures that when an environment is activated, the shell's <code>PATH</code> is correctly adjusted to prioritize the environment's binaries. This makes it an indispensable tool for developers who rely on <i>pyenv</i> for managing multiple Python versions and require isolated, project-specific dependencies.


title: CAVEATS
content:
For <i>pyenv-virtualenv</i> to function correctly, <i>pyenv</i> must be properly installed and initialized in your shell. Crucially, you must include <code>eval "$(pyenv init -)"</code> and <code>eval "$(pyenv virtualenv-init -)"</code> in your shell's configuration file (e.g., <code>.bashrc</code>, <code>.zshrc</code>) to enable the necessary shell functions for activation and deactivation. Without proper shell integration, environment switching will not work as expected.


title: CORE WORKFLOW
content:
The typical workflow with <i>pyenv-virtualenv</i> involves three main steps:<br>1. <b>Create:</b> Use <code>pyenv virtualenv <i>&lt;python_version&gt; &lt;environment_name&gt;</i></code> to establish a new isolated environment.<br>2. <b>Activate:</b> Use <code>pyenv activate <i>&lt;environment_name&gt;</i></code> to switch into the desired environment, making its Python and installed packages available.<br>3. <b>Deactivate:</b> Use <code>pyenv deactivate</code> to exit the current virtual environment, returning to the global or <i>pyenv</i>-selected Python version. This structured approach simplifies managing dependencies across multiple projects.


title: LISTING ENVIRONMENTS
content:
To view all currently available virtual environments managed by <i>pyenv-virtualenv</i>, you can use the command <code>pyenv virtualenvs</code>. This provides a clear overview of your created environments, including the Python version they are based on.


title: HISTORY
content:
<i>pyenv-virtualenv</i> emerged as a natural extension for <i>pyenv</i>, addressing the growing need for seamless integration between Python version management and virtual environment isolation. Prior to its development, developers often had to manage <i>pyenv</i> and <i>virtualenv</i> workflows separately, leading to potential inconsistencies. This plugin bridged that gap, providing a unified interface for creating and managing project-specific Python environments. Its release significantly enhanced <i>pyenv</i>'s utility, making it a more comprehensive tool for Python development by automating and simplifying what were previously manual and error-prone steps.


title: PARAMETERS
content:
<b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the help message and exit.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show program's version number and exit.<br><br><b><b>-j</b> <i>N</i>, <b>--jobs</b>=<i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run <b>pyflakes</b> in parallel using <i>N</i> jobs. Set to 0 to use the number of CPU cores.<br><br><b><b>--exclude</b>=<i>patterns</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Comma-separated list of file/directory patterns to exclude from checking. Supports standard Unix shell glob matching.<br><br><b><b>--builtins</b>=<i>names</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Comma-separated list of names that are globally assumed to be defined (e.g., by your framework).<br><br><b><b>--disable-msg</b>=<i>codes</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Comma-separated list of error codes to disable (e.g., F401 for unused imports). Each code starts with 'F'.<br><br><b><b>--enable-msg</b>=<i>codes</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Comma-separated list of error codes to enable (overrides <b>--disable-msg</b> for these codes). Useful for specific scenarios.<br><br><b><b>--diff</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only check files that have uncommitted changes in the current Git repository.<br><br><b><b>--include-dir</b>=<i>directories</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Comma-separated list of directories to include for checking, in addition to explicitly provided paths. Useful when using <b>--diff</b>.<br><br>


title: DESCRIPTION
content:
<b>pyflakes</b> is a simple and fast static analysis tool for Python programs. Unlike more comprehensive linters such as <i>Pylint</i>, <b>pyflakes</b> focuses exclusively on detecting programming errors like unused imports, undefined names, and unassigned variables, rather than enforcing style conventions (PEP 8) or code complexity metrics. It works by parsing Python source code into an Abstract Syntax Tree (AST) and then performing a quick traversal to identify common logical errors without executing the code. This approach makes <b>pyflakes</b> exceptionally fast and produces very few false positives, making it an excellent first line of defense for catching basic but crucial mistakes in Python codebases. It is often used as a core component within other larger linting frameworks, most notably <i>Flake8</i>.


title: CAVEATS
content:
<b>pyflakes</b> focuses solely on detecting errors and does <i>not</i> enforce code style (e.g., PEP 8). For style checking, tools like <i>pycodestyle</i> or <i>black</i> are needed. It also does not perform type checking; for that, consider tools like <i>mypy</i>. While generally accurate, in highly dynamic Python codebases (e.g., heavy use of `setattr`/`getattr` or runtime code generation), <b>pyflakes</b> might occasionally produce false positives due to its static analysis nature.


title: ERROR CODES
content:
<b>pyflakes</b> reports errors using specific codes, typically prefixed with 'F' (e.g., <i>F401</i> for unused imports, <i>F821</i> for undefined names). These codes allow users to selectively enable or disable certain checks using the <b>--disable-msg</b> or <b>--enable-msg</b> options, providing fine-grained control over the analysis output.


title: INTEGRATION WITH FLAKE8
content:
While <b>pyflakes</b> can be run as a standalone command, it is most commonly used as a plugin for <i>Flake8</i>. <i>Flake8</i> acts as a wrapper that runs <b>pyflakes</b>, <i>pycodestyle</i> (formerly <i>pep8</i>), and <i>McCabe</i> (a complexity checker) together, providing a more holistic linting solution. This integration simplifies the command-line usage and allows developers to manage all their code quality checks from a single tool.


title: HISTORY
content:
<b>pyflakes</b> originated from the Divmod projects, specifically as a component of their <i>Nevow</i> web framework, developed around 2007. Its primary goal was to provide a very fast and lightweight static analysis tool to catch common programming errors without the overhead of more complex linters. It was designed to be easily integrated into development workflows and continuous integration systems due to its speed and low false-positive rate. Over time, it gained significant traction and became a standalone project, widely adopted within the Python community. Its design philosophy of focusing solely on errors (and not style) made it an ideal base for more comprehensive linting tools, leading to its popular integration into <i>Flake8</i>, which combines <b>pyflakes</b> with <i>pycodestyle</i> (for PEP 8 style checking) and a cyclomatic complexity checker.


title: PARAMETERS
content:
<b><b>-o</b> <I>FILE</I>, <b>--output=</b><I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Write output to the specified <I>.pot</I> file instead of standard output.<br><br><b><b>-D</b> <I>DIR</I>, <b>--directory=</b><I>DIR</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add <I>DIR</I> to the module search path for input files.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print names of files being processed to standard error.<br><br><b><b>-n</b>, <b>--no-default-keywords</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not use default keywords (e.g., <I>_</I>, <I>gettext</I>) for string extraction.<br><br><b><b>-k</b> <I>WORD</I>, <b>--keyword=</b><I>WORD</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a keyword to look for in addition to or instead of default ones. Can be used multiple times.<br><br><b><b>-E</b> <I>ENCODING</I>, <b>--encoding=</b><I>ENCODING</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the encoding of the input source files.<br><br><b><b>--copyright-holder=</b><I>STRING</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the copyright holder in the generated <I>.pot</I> file header.<br><br><b><b>--msgid-bugs-address=</b><I>EMAIL@ADDRESS</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the email address for bug reports in the <I>.pot</I> file header.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show a help message and exit.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the program's version number and exit.<br><br>


title: DESCRIPTION
content:
The <I>pygettext2.7</I> command is a utility designed to extract localizable strings from Python 2.7 source code files. It scans Python scripts for calls to internationalization functions (such as <I>_()</I> or <I>gettext()</I>) and generates a <I>.pot</I> (Portable Object Template) file. This template file serves as the basis for creating <I>.po</I> (Portable Object) files, which contain the original strings and their translations into various languages. While essential for building multilingual applications in its time, it's specific to Python 2.7 and is now considered deprecated in favor of Python 3's <I>pygettext</I> or more comprehensive tools like <I>xgettext</I> from GNU gettext.


title: CAVEATS
content:
This utility is specifically designed for Python 2.7 source code, which is now End-of-Life (EOL) and no longer officially supported. Using it for Python 3 projects is not recommended and may lead to unexpected behavior or incomplete string extraction. Modern Python development should use the built-in <I>pygettext</I> from Python 3, or more advanced tools like <I>xgettext</I> (from GNU gettext) or third-party internationalization libraries such as Babel.


title: OUTPUT FORMAT
content:
The command generates a <I>.pot</I> (Portable Object Template) file, which is a plain text file containing all extracted translatable strings along with their source locations and any associated comments. This file serves as the master template for creating language-specific <I>.po</I> files.


title: INTERNATIONALIZATION WORKFLOW
content:
Typically, <I>pygettext2.7</I> is the first step in the internationalization process: <br>1. Run <I>pygettext2.7</I> to create a <I>.pot</I> file. <br>2. Use <I>msginit</I> to create language-specific <I>.po</I> files from the <I>.pot</I> file. <br>3. Translators edit the <I>.po</I> files. <br>4. Use <I>msgfmt</I> to compile <I>.po</I> files into binary <I>.mo</I> files for use by applications.


title: HISTORY
content:
The <I>pygettext</I> utility, including its Python 2.7 specific variant, originated as part of Python's standard library to facilitate internationalization (i18n) for Python applications. It provides a Python-native way to integrate with the GNU gettext internationalization system. The <I>pygettext2.7</I> variant specifically refers to the version bundled with or intended for use with Python 2.7 environments. Its development paralleled the lifecycle of Python 2.x, providing a crucial tool for developers building localized applications during that era. With the deprecation and end-of-life of Python 2.7, its usage has declined, being superseded by Python 3's <I>pygettext</I> and other more feature-rich alternatives.


title: PARAMETERS
content:
<b><b>-o</b> <I>FILE</I>, <b>--output</b>=<I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the output file name for the POT (Portable Object Template) file. The default is <i>messages.pot</i>.<br><br><b><b>-D</b> <I>DIR</I>, <b>--default-domain</b>=<I>DIR</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the output directory for the POT file. Often used to organize translation files by domain.<br><br><b><b>-k</b> <I>WORD</I>, <b>--keyword</b>=<I>WORD</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify keywords to look for to identify translatable strings. Default is '<i>_</i>'. Can be specified multiple times for different keywords (e.g., <i>-k gettext -k ngettext</i>).<br><br><b><b>-x</b> <I>FILE</I>, <b>--exclude-file</b>=<I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exclude files listed in the specified <i>FILE</i> from being parsed.<br><br><b><b>-X</b> <I>DIR</I>, <b>--exclude-dir</b>=<I>DIR</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exclude directories matching the specified <i>DIR</i> pattern from being parsed.<br><br><b><b>-L</b> <I>LANG</I>, <b>--language</b>=<I>LANG</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the programming language of the input files, typically '<i>python</i>'.<br><br><b><b>-a</b>, <b>--extract-all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Extract all strings from the source code, not just those explicitly marked for translation.<br><br><b><b>-n</b>, <b>--no-location</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not write the <i>#: filename:lineno</i> reference lines in the POT file.<br><br><b><b>-c</b> <I>COMMENTS</I>, <b>--add-comments</b>=<I>COMMENTS</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add translator comments from code, typically using a specific prefix like <i>TRANSLATORS:</i>.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output, providing more information during the extraction process.<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>pygettext3.4</i> is a specialized Python script, typically found within a Python 3.4 environment, designed for internationalization (i18n) workflows. Its primary function is to parse Python source code files and identify all strings that have been marked for translation, commonly by wrapping them in functions like <code>_()</code> or <code>gettext()</code>. Upon execution, it generates a <b>.pot</b> (Portable Object Template) file. This template contains all the extracted strings along with their corresponding source file and line number references. The <b>.pot</b> file then serves as a standardized base for translators to create language-specific <b>.po</b> (Portable Object) files, which are subsequently compiled into binary <b>.mo</b> (Machine Object) files used by applications at runtime for displaying localized content. <i>pygettext3.4</i> is an indispensable tool in the Python i18n ecosystem, streamlining the process of preparing applications for global audiences.


title: CAVEATS
content:
The name <i>pygettext3.4</i> explicitly ties this utility to Python 3.4. While it functions similarly to generic <i>pygettext</i>, its use with code written for significantly newer Python versions might lead to syntax parsing errors or incomplete string extraction due to language feature changes. It strictly relies on strings being explicitly marked for translation; unmarked strings will not be extracted. For complex or large-scale projects, more comprehensive internationalization libraries like <i>Babel</i> might offer more robust features and better integration with other development tools.


title: INTERNATIONALIZATION WORKFLOW
content:
<i>pygettext3.4</i> plays a crucial role in the typical software internationalization (i18n) workflow:<br>1. <b>Code Development:</b> Developers write Python code, marking translatable strings (e.g., <code>_("Hello")</code>).<br>2. <b>String Extraction:</b> <i>pygettext3.4</i> is run on the source files, generating a <b>.pot</b> (Portable Object Template) file containing all marked strings.<br>3. <b>Translation:</b> Translators use the <b>.pot</b> file as a template to create language-specific <b>.po</b> (Portable Object) files (e.g., <i>es.po</i> for Spanish).<br>4. <b>Compilation:</b> The <i>.po</i> files are compiled into binary <b>.mo</b> (Machine Object) files using <i>msgfmt</i>.<br>5. <b>Runtime Localization:</b> The Python application, using the <i>gettext</i> module, loads the appropriate <i>.mo</i> file at runtime to display translated messages based on the user's locale.


title: COMPARISON WITH XGETTEXT
content:
While <i>xgettext</i> (part of GNU <i>gettext</i> utilities) is a powerful, general-purpose tool capable of extracting strings from various programming languages, <i>pygettext</i> (and thus <i>pygettext3.4</i>) is specifically tailored for Python. This specialization often allows for better parsing and handling of Python-specific syntax, leading to more accurate string extraction from Python source files compared to configuring <i>xgettext</i> for Python, although <i>xgettext</i> is still highly capable when properly configured.


title: HISTORY
content:
The <i>pygettext.py</i> script is an integral part of Python's standard library <i>gettext</i> module, providing a Python-specific solution for string extraction, complementing the broader GNU <i>gettext</i> toolkit. The existence of <i>pygettext3.4</i> specifically indicates its distribution with Python 3.4, a common practice to ensure that utility scripts are compatible with the Python interpreter version they ship with. The underlying <i>gettext</i> framework itself has a rich history, originating from the GNU project in the late 1980s as a powerful and widely adopted standard for internationalization of software.


title: PARAMETERS
content:
<b><b>-l</b> <i>&lt;lexer&gt;</i>, <b>--lexer=</b><i>&lt;lexer&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly define the language or lexer to use for syntax highlighting (e.g., <i>python</i>, <i>javascript</i>, <i>xml</i>).<br><br><b><b>-F</b> <i>&lt;formatter&gt;</i>, <b>--formatter=</b><i>&lt;formatter&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Choose the output format (e.g., <i>html</i>, <i>terminal</i>, <i>latex</i>, <i>rtf</i>, <i>svg</i>). The default is typically <i>terminal</i> or <i>html</i> if output is redirected.<br><br><b><b>-s</b> <i>&lt;style&gt;</i>, <b>--style=</b><i>&lt;style&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Apply a specific highlighting style or theme (e.g., <i>default</i>, <i>monokai</i>, <i>solarized-light</i>). Use <b>-L styles</b> to see available options.<br><br><b><b>-o</b> <i>&lt;outfile&gt;</i>, <b>--outfile=</b><i>&lt;outfile&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Write the highlighted output to the specified file instead of standard output.<br><br><b><b>-O</b> <i>&lt;options&gt;</i>, <b>--options=</b><i>&lt;options&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pass comma-separated options directly to the lexer or formatter (e.g., <i>linenos=True,cssclass=source</i>).<br><br><b><b>-L</b> <i>&lt;type&gt;</i>, <b>--list-options=</b><i>&lt;type&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;List available lexers, formatters, styles, or filters. <i>&lt;type&gt;</i> can be <i>lexers</i>, <i>formatters</i>, <i>styles</i>, or <i>filters</i>.<br><br><b><b>--detect-lexer</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempt to automatically detect the lexer based on the file content or its extension. This is useful when the language is unknown.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print extra information to standard error, useful for debugging or understanding processing steps.<br><br><b><b>-V</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the program's version number and exit.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show a help message describing command-line options and exit.<br><br><b><b>-f</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Read filenames from standard input, one filename per line, instead of from command-line arguments. Useful for batch processing.<br><br>


title: DESCRIPTION
content:
Pygmentize is the command-line utility provided by the Pygments project, a versatile syntax highlighting library written in Python. It supports an extensive array of programming languages, markup formats, and configuration files, offering highly customizable output formats such as HTML, LaTeX, RTF, and ANSI escape codes for terminal display. The <b>pygmentize</b> command allows users to apply this powerful highlighting capability directly from the terminal. It reads input from specified files or standard input, processes it according to the chosen lexer (language detector) and formatter (output style), and then prints the highlighted content to standard output. This makes it ideal for integrating syntax highlighting into scripts, documentation generation, or for quick terminal viewing of code with enhanced readability. Its flexibility in handling diverse input types and generating various output formats makes it an indispensable tool for developers and content creators.


title: CAVEATS
content:
<i>Lexer Detection Accuracy</i>: While <b>pygmentize</b> offers automatic lexer detection, it may not always be perfect, especially for ambiguous file types or very short code snippets. Explicitly specifying the lexer with <b>-l</b> is often more reliable.<br><br><i>Terminal Output Limitations</i>: When using terminal formatters, the display quality depends heavily on the terminal emulator's support for ANSI escape codes and its color capabilities. Some styles might not render well or might be unreadable in certain terminal environments.<br><br><i>Dependencies</i>: <b>pygmentize</b> is a Python-based tool and requires the Pygments library to be installed in your Python environment. Its functionality is directly tied to the capabilities and versions of the installed Pygments package.


title: LISTING AVAILABLE OPTIONS
content:
To see the full list of supported lexers, formatters, styles, or filters, use the <b>-L</b> or <b>--list-options</b> flag followed by the type (e.g., <b>pygmentize -L lexers</b>, <b>pygmentize -L styles</b>). This is crucial for discovering what's available for your highlighting needs.


title: COMMON USAGE PATTERNS
content:
Here are a few examples of how <b>pygmentize</b> can be used:<br><br><i>Highlighting a file to HTML</i>:<br><b>pygmentize -l python -F html -o output.html myfile.py</b><br><br><i>Highlighting standard input to terminal with a specific style</i>:<br><b>cat myfile.js | pygmentize -l javascript -F terminal256 -s monokai</b><br><br><i>Using automatic lexer detection for a file</i>:<br><b>pygmentize --detect-lexer -F terminal myfile.rb</b>


title: HISTORY
content:
Pygments was created by Georg Brandl in 2006. It quickly gained popularity as a robust and extensible syntax highlighting library. <b>pygmentize</b> is the command-line interface provided as part of the Pygments distribution, allowing users to leverage its powerful features outside of a programmatic context. Its development has been continuous, adapting to new languages and evolving output formats, maintaining its status as a widely used tool in the Python ecosystem and beyond. Its widespread adoption is due to its accuracy, extensive language support, and flexibility in output formats.


title: SYNOPSIS
content:
pygmentize [<b>-l <I>lexer</I></b>] [<b>-f <I>formatter</I></b>] [<b>-o <I>outfile</I></b>] [<b>-s <I>style</I></b>] [<b><I>options</I></b>] [<b><I>file</I> ...</b>]


title: PARAMETERS
content:
<b><b>-l <I>lexer</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the language lexer to use (e.g., <I>python</I>, <I>html</I>, <I>css</I>). If not specified, <I>pygmentize</I> tries to guess based on filename or content.<br><br><b><b>-f <I>formatter</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output formatter (e.g., <I>html</I>, <I>rtf</I>, <I>terminal</I>). The default is often <I>html</I> if an output file is specified, or <I>terminal</I> if outputting to console.<br><br><b><b>-o <I>outfile</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the highlighted output to the specified <I>outfile</I> instead of standard output (stdout).<br><br><b><b>-s <I>style</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the highlighting style to use for the output (e.g., <I>default</I>, <I>colorful</I>, <I>monokai</I>, <I>nord</I>). Run <I>pygmentize -L styles</I> to see available styles.<br><br><b><b>-P <I>key=value</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Passes specific options to the selected lexer or formatter. For example, <I>-P linenos=True</I> for line numbers in HTML output, or <I>-P full=True</I> to generate a complete HTML document.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the program's version number and exits.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a comprehensive help message with all available options and exits.<br><br>


title: DESCRIPTION
content:
While the exact "pyhtmlizer" command is not a standard Linux utility and might refer to a specific, less common script, this analysis describes <I>pygmentize</I>. <I>pygmentize</I> is the versatile command-line utility provided by the <I>Pygments</I> project, a powerful generic syntax highlighter written in Python.<br>It converts source code from various programming and markup languages into a wide array of output formats, including <b>HTML</b>, RTF, LaTeX, ANSI escape sequences for terminals, and plain text.<br>Its primary function is to apply sophisticated syntax highlighting, making code more readable and visually appealing. This tool is widely used for displaying code examples on websites, in technical documentation, and for interactive terminal sessions, leveraging Pygments' extensive collection of lexers and formatters to accurately parse and beautify code.<br>It supports hundreds of languages and numerous output styles, providing flexibility for diverse use cases.


title: CAVEATS
content:
<I>pygmentize</I> requires the Python interpreter and the <I>Pygments</I> library to be installed on the system (typically via `pip install pygments`).<br>It is not a default command in most standard Linux distributions and must be explicitly installed.<br>Performance may vary with very large input files.


title: SUPPORTED LEXERS AND FORMATTERS
content:
<I>Pygments</I> supports hundreds of programming languages, markup languages, and configuration file formats through its extensive collection of lexers (parsers).<br>Similarly, it offers a wide variety of formatters to convert highlighted code into different output types beyond HTML, including RTF for word processors, LaTeX for academic documents, and various terminal formats for command-line display.<br>The specific lists of supported lexers and formatters can be viewed by running <I>pygmentize -L lexers</I> and <I>pygmentize -L formatters</I> respectively.


title: CUSTOM STYLES AND EXTENSIBILITY
content:
Users can select from numerous built-in highlighting styles using the <b>-s</b> option. Additionally, <I>Pygments</I> is highly extensible, allowing developers to create custom lexers, formatters, and styles to suit specific needs or integrate with other applications.<br>This flexibility makes it a powerful tool for tailored code presentation and integration into larger workflows.


title: HISTORY
content:
The <I>Pygments</I> project, including its command-line utility <I>pygmentize</I>, was first released in 2006. It quickly gained popularity as a robust and extensible syntax highlighter written entirely in Python, making it cross-platform compatible.<br>Over the years, it has continuously evolved, adding support for new languages, formatters, and styles, establishing itself as a standard tool for code formatting and presentation in various contexts, from web development to documentation generation.


title: PARAMETERS
content:
<b><i>&lt;inventory&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the hosts to operate on. This can be a Python file defining hosts, a directory containing hosts, a simple text file, or a direct host string (e.g., '<i>myhost.com</i>').<br><br><b><i>&lt;OPERATION_ARGS&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Arguments defining the operations to run, typically a Python deploy script (e.g., '<i>deploy.py</i>').<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show <i>pyinfra</i>'s version number and exit.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show this help message and exit.<br><br><b><b>--user</b> <i>&lt;user&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connect to remote hosts as this user (for SSH connections).<br><br><b><b>--port</b> <i>&lt;port&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connect to remote hosts on this port (for SSH connections, default: 22).<br><br><b><b>--key</b> <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to an SSH private key file for authentication.<br><br><b><b>--password</b> <i>&lt;pass&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;SSH password for authentication. Not recommended for production due to security implications.<br><br><b><b>--sudo</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Execute operations using '<i>sudo</i>' on remote hosts.<br><br><b><b>--sudo-user</b> <i>&lt;user&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Execute '<i>sudo</i>' operations as this user (requires <b>--sudo</b>).<br><br><b><b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable debug logging output for detailed information.<br><br><b><b>--dry</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform a 'dry run', showing what operations would be executed without making any changes.<br><br><b><b>--limit</b> <i>&lt;hosts&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limit operations to a subset of hosts specified in the inventory (e.g., '<i>host1,host2</i>' or '<i>@group_name</i>').<br><br><b><b>--parallel</b> <i>&lt;num&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Number of parallel connections to use when executing operations (default: 10).<br><br><b><b>--operations-directory</b> <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a directory containing custom <i>pyinfra</i> operations.<br><br><b><b>--chdir</b> <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Change the working directory before executing the deployment script.<br><br>


title: DESCRIPTION
content:
<i>pyinfra</i> is a powerful, agentless infrastructure automation tool written in Python. It allows users to define infrastructure state and operations using pure Python code, making it highly flexible and extensible. Unlike many other configuration management tools that rely on DSLs or YAML, <i>pyinfra</i> leverages the full power of Python, enabling complex logic and integrations. It connects to target hosts via SSH, Docker, or local connections, and executes operations to achieve the desired state, such as installing packages, configuring files, running commands, and managing services. <i>pyinfra</i> aims for simplicity, speed, and a Pythonic user experience, making it suitable for tasks ranging from small ad-hoc scripts to large-scale deployments across many servers.


title: CAVEATS
content:
While <i>pyinfra</i> offers powerful Pythonic control, its community and ecosystem are smaller compared to more established tools like Ansible or SaltStack.<br>Users need a basic understanding of Python to write and understand <i>pyinfra</i> operations, as it does not rely on a declarative YAML or DSL syntax for operations.<br>For very large or complex environments, careful structuring of Python code is essential to maintain readability and manageability.


title: AGENTLESS ARCHITECTURE
content:
<i>pyinfra</i> operates on an agentless model, meaning it does not require any special software or agents to be installed on the target servers. It primarily uses SSH for remote execution, offering a secure and widely adopted method for managing infrastructure. It also supports local execution and Docker container connections, providing flexibility for various environments.


title: PYTHON AS CODE
content:
One of <i>pyinfra</i>'s distinguishing features is its use of pure Python for defining operations and deployments. This provides users with the full power of a general-purpose programming language, allowing for complex conditional logic, loops, custom data structures, and seamless integration with other Python libraries, significantly enhancing its capabilities beyond typical declarative configuration files.


title: EXTENSIBILITY AND CUSTOMIZATION
content:
<i>pyinfra</i> is designed to be highly extensible. Users can easily create and share custom operations ('<i>ops</i>') and '<i>facts</i>' (system information gathering functions) using standard Python modules. This allows for tailored automation solutions that can adapt to unique infrastructure requirements and integrate with specific tools or APIs not covered by the built-in operations.


title: HISTORY
content:
<i>pyinfra</i> was created by Nick Dickens and first released in 2018. It emerged as an effort to build a simpler, faster, and more Pythonic alternative to existing configuration management tools. The project has seen continuous development, focusing on performance, ease of use, and a strong emphasis on leveraging native Python capabilities for defining infrastructure state, rather than domain-specific languages or YAML-based configurations. It has steadily grown in popularity within the Python community for its unique approach to infrastructure automation.


title: SYNOPSIS
content:
<b>pylint</b> [<i>options</i>] <i><module_or_package_or_file></i> ...<br>Example: <b>pylint</b> <i>my_script.py</i><br>Example: <b>pylint</b> <i>my_package</i>


title: PARAMETERS
content:
<b><b>--rcfile=</b><i><file></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative configuration file instead of the default <i>.pylintrc</i> or <i>pyproject.toml</i>.<br><br><b><b>--output-format=</b><i><format></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the output format, such as <i>text</i>, <i>json</i>, or <i>parseable</i>.<br><br><b><b>--disable=</b><i><msg_id></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables a specific message ID (e.g., <i>C0301</i>) or an entire category of messages (e.g., <i>C</i> for convention).<br><br><b><b>--enable=</b><i><msg_id></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables a specific message ID or category that might be disabled by default or in the configuration.<br><br><b><b>--score=</b><i><y_or_n></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls whether the overall code quality score is displayed after analysis (default: <i>y</i>).<br><br><b><b>--reports=</b><i><y_or_n></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls whether the historical reports are displayed at the end of the run (deprecated in favor of other output formats).<br><br><b><b>--init-hook=</b><i><python_code></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Python code executed once before the analysis begins, useful for setting up paths or environments.<br><br>


title: DESCRIPTION
content:
<b>pylint</b> is a highly configurable static code analysis tool for Python. It checks for programming errors, helps enforce a coding standard, sniffs for bad code smells, and offers suggestions on how to improve code quality.<br><br>It analyzes Python source code and reports on issues such as syntax errors, style violations (e.g., PEP 8), potential bugs (e.g., unused variables, unreachable code), and complexity. By automating code review, <b>pylint</b> assists developers in writing cleaner, more maintainable, and bug-free Python code, making it an essential tool in CI/CD pipelines and development workflows. It assigns a score to the analyzed code, providing a quantitative measure of its quality.


title: CAVEATS
content:
<ul><li><b>Opinionated Defaults:</b> <b>pylint</b> often enforces strict coding standards (e.g., PEP 8), which may require significant configuration to align with specific team styles.</li><li><b>False Positives:</b> Like many static analysis tools, it can occasionally produce false positives, leading to noise that needs to be filtered or addressed.</li><li><b>Performance:</b> For very large codebases, <b>pylint</b> can be relatively slow, though performance has improved in recent versions.</li><li><b>Configuration Complexity:</b> Its extensive configurability can be daunting for new users, requiring time to master the <i>.pylintrc</i> file.</li></ul>


title: CONFIGURATION
content:
<b>pylint</b> is highly configurable via a <i>.pylintrc</i> file or a <i>pyproject.toml</i> file in the project root or user's home directory. This allows users to enable/disable specific checks, set thresholds, and define project-specific coding standards tailored to their needs.


title: MESSAGE IDS
content:
<b>pylint</b> categorizes its messages with specific IDs:<br><ul><li><b>C</b>: Convention (style recommendations)</li><li><b>R</b>: Refactor (suggestions for code improvement)</li><li><b>W</b>: Warning (potential problems, not necessarily bugs)</li><li><b>E</b>: Error (likely bugs or serious problems)</li><li><b>F</b>: Fatal (errors that prevent <b>pylint</b> from running, e.g., parsing errors)</ul>Understanding these IDs is crucial for effective configuration and issue resolution.


title: INTEGRATION
content:
It's commonly integrated into development environments (IDEs like VS Code, PyCharm), pre-commit hooks (using tools like <i>pre-commit</i>), and CI/CD pipelines to automate code quality checks, ensuring consistent code quality across development teams.


title: HISTORY
content:
<b>pylint</b> was initially developed by Logilab (hence its historical dependency on <i>logilab.astng</i>) and first released in 2003, making it one of the earliest and most comprehensive static analysis tools for Python. Over the years, it has evolved significantly, incorporating new features, improving performance, and adapting to changes in Python versions and coding standards. Its maintenance was later taken over by the Python Code Quality Authority (PyCQA), ensuring its continued development and community support. It remains a widely used tool for ensuring code quality in Python projects.


title: PARAMETERS
content:
<b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br><b>-V, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the <i>PyPy</i> version number and exit.<br><br><b>-c <i>command</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Execute the Python <i>command</i> string.<br><br><b>-m <i>module</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run the Python <i>module</i> as a script.<br><br><b>-i</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enter interactive mode after executing script or command.<br><br><b>-S</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Don't import the <i>site</i> module on startup.<br><br><b>-E</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ignore all <i>PYTHON*</i> environment variables.<br><br><b>-O</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optimize generated bytecode, e.g., by removing <i>assert</i> statements.<br><br><b>-B</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Don't write <i>.pyc</i> files on import.<br><br><b>-u</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force stdout, stdin, and stderr to be unbuffered binary.<br><br><b>-R <i>jit-option</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>PyPy</i> specific. Controls the <i>JIT</i> compiler. Use <i>-R help</i> for options like <i>off</i>, <i>verbose</i>, <i>trace</i>, allowing fine-tuning of performance.<br><br><b>-X <i>arg</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set implementation-specific options for <i>PyPy</i>.<br><br>


title: DESCRIPTION
content:
<i>PyPy</i> is an alternative, high-performance implementation of the Python programming language, renowned for its <b>Just-In-Time (JIT)</b> compiler. Unlike <i>CPython</i>, the standard interpreter, <i>PyPy</i> translates Python code into machine code during execution, leading to significant speedups for many applications.<br><br>It is written in <i>RPython</i>, a restricted dialect of Python, allowing for self-optimization. <i>PyPy</i> aims for strong compatibility with <i>CPython</i> while focusing on speed, efficiency, and advanced features like transactional memory. It provides a robust platform for running Python applications faster, particularly CPU-bound tasks.


title: CAVEATS
content:
<i>PyPy</i> offers significant speedups but has some caveats:<br>1. <b>CPython C Extension Compatibility</b>: While improving (via <i>CFFI/CPyExt</i>), not all <i>CPython C</i> extensions are fully compatible or performant without adaptation.<br>2. <b>Startup Time</b>: Initial startup can be slightly slower due to <i>JIT</i> warm-up, though this is offset by long-running process performance.<br>3. <b>Memory Usage</b>: May consume more memory initially due to <i>JIT</i> compiler structures.<br>4. <b>Garbage Collection</b>: Uses a different garbage collector, which behaves differently from <i>CPython's</i> reference counting.


title: JIT COMPILER
content:
<i>PyPy's</i> defining feature is its <b>Just-In-Time</b> compiler. It dynamically analyzes frequently executed code (hot spots) during runtime, compiling it into highly optimized machine code. This eliminates the overhead of interpretation, leading to substantial performance improvements for CPU-bound applications.


title: RPYTHON
content:
The <b>RPython</b> (Restricted Python) toolchain is a static analysis and translation framework. <i>PyPy</i> itself is written in <i>RPython</i>, which allows it to be translated into various lower-level languages like C, and crucially, enables the automatic generation of an optimizing <i>JIT</i> compiler tailored for the interpreter.


title: CFFI
content:
<b>CFFI</b> stands for Foreign Function Interface for C. <i>CFFI</i> is <i>PyPy's</i> recommended way to interact with C libraries, offering a robust and performant alternative to <i>CPython's</i> C API, allowing Python code to call C functions and manage C data structures directly.


title: HISTORY
content:
Initiated in 2003 as a research project, <i>PyPy</i> aimed to build a Python interpreter using <i>RPython</i>, a restricted subset of Python. The core idea was to enable advanced optimizations, especially <b>Just-In-Time (JIT)</b> compilation. The first self-hosting version was achieved in 2007, and it gained significant attention for its impressive speed gains. <i>PyPy</i> has since evolved, continuously improving compatibility with <i>CPython</i> and supporting newer Python language versions, maintaining its position as a leading alternative Python implementation.


title: SYNOPSIS
content:
pyrit <command> [options]<br><br>pyrit is a multi-command tool where <i>command</i> can be one of many sub-commands, each with its own specific options and arguments. Common commands include:<br><br><i>Database Management:</i> <b>import_passwords</b>, <b>import_essid</b>, <b>list_essids</b>, <b>list_passwords</b>, <b>purge_db</b>, <b>reset_db</b><br><i>Attack/Cracking:</i> <b>attack_db</b>, <b>eval</b><br><i>Capture/Conversion:</i> <b>deauth</b>, <b>convert_raw_to_cap</b><br><i>Utility:</i> <b>benchmark</b>, <b>test</b>, <b>get_wlan_info</b>


title: PARAMETERS
content:
<b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the help message for the general command or a specific sub-command.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the Pyrit version information.<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases the verbosity of the output.<br><br><b>--all-cores</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Utilizes all available CPU cores for computations.<br><br><b>--gpu <index></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the GPU device to use by its index (e.g., --gpu 0).<br><br><b>--opencl-device <index></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects a specific OpenCL device by index for computation.<br><br><b>-i <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an input file, often a capture file (e.g., .cap, .pcap).<br><br><b>-o <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an output file for results or converted data.<br><br><b>--essid <ESSID></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the Extended Service Set Identifier (network name) to target.<br><br><b>--password <password></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides a specific password to test or for pre-computation.<br><br><b>--input <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Alias for -i, specifies the input file.<br><br><b>--output <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Alias for -o, specifies the output file.<br><br><b>--pmk-file <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a file containing pre-computed PMKs to use.<br><br><b>--file <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generic file path argument used by various commands.<br><br><b>--daemon</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs Pyrit as a daemon process for remote control.<br><br>


title: DESCRIPTION
content:
Pyrit is a powerful, highly optimized Python-based tool designed for auditing and cracking WPA/WPA2-PSK encrypted wireless networks. Its primary strength lies in its ability to leverage the computational power of modern GPUs (via NVIDIA CUDA or OpenCL) to significantly accelerate the process of pre-computing Pairwise Master Keys (PMKs) and performing dictionary attacks against captured WPA/WPA2 handshakes.<br><br>Unlike simple dictionary attacks, Pyrit can store a vast database of pre-computed PMKs for known SSIDs and passphrases, drastically reducing the time required to crack subsequent handshakes for the same SSID-passphrase combination. It supports various database backends like PostgreSQL or SQLite for efficient storage and retrieval of SSIDs, captured handshakes, and pre-computed PMK tables.<br><br>While Pyrit is particularly effective for brute-force and dictionary attacks against WPA/WPA2-PSK, it also offers functionalities for capturing 802.11 traffic, managing databases, and benchmarking system performance. It aims to provide an efficient and scalable solution for Wi-Fi security auditing and passphrase recovery.


title: CAVEATS
content:
<b>Hardware Dependency:</b> Pyrit heavily relies on GPU acceleration for optimal performance. Without a compatible NVIDIA (CUDA) or AMD (OpenCL) GPU, its cracking speed can be significantly slower, often making it less efficient than CPU-only alternatives for some tasks.<br><br><b>Dependencies:</b> Setting up Pyrit can be complex due to its dependencies on various libraries, including those for GPU computation (CUDA Toolkit, OpenCL SDK), database connectors (e.g., psycopg2 for PostgreSQL), and specific Python versions.<br><br><b>Ethical Use:</b> Pyrit is a powerful tool. It should only be used for legitimate security auditing of networks for which you have explicit permission, or for recovering your own forgotten passphrases. Unauthorized use is illegal and unethical.<br><br><b>Development Status:</b> Active development on Pyrit has slowed down considerably in recent years, with hashcat often being the preferred tool for WPA/WPA2 cracking due to its continued development and broader hardware support.


title: DATABASE INTEGRATION
content:
Pyrit leverages a database (typically PostgreSQL or SQLite) to efficiently manage and store crucial information. This includes SSIDs, the actual captured 802.11 handshakes, and most importantly, vast tables of pre-computed Pairwise Master Keys (PMKs). Storing these PMKs allows Pyrit to avoid re-calculating them for every attack, significantly speeding up subsequent cracking attempts against the same SSID-passphrase combinations.


title: GPU ACCELERATION
content:
The core strength of Pyrit lies in its highly optimized use of GPU acceleration. It supports both NVIDIA CUDA and OpenCL frameworks, enabling it to offload intensive PMK calculations to graphics cards. This parallel processing capability allows Pyrit to achieve cracking speeds orders of magnitude faster than traditional CPU-bound methods, making it exceptionally efficient for large-scale dictionary attacks and brute-force attempts.


title: HISTORY
content:
Pyrit was developed by Lukas Lueg, emerging as a significant tool in the realm of WPA/WPA2-PSK cracking. Its inception was driven by the desire to leverage the immense parallel processing capabilities of GPUs to accelerate the computationally intensive process of pre-computing PMKs and performing dictionary attacks. It quickly gained popularity for its superior performance compared to CPU-only alternatives available at the time. Pyrit distinguished itself by introducing the concept of storing pre-computed PMKs in a database, allowing for rapid re-cracking of handshakes from known SSIDs and passphrases without redundant calculations. While still functional, its active development has somewhat tapered off, with other tools like hashcat now leading the charge in GPU-accelerated cracking.


title: PARAMETERS
content:
<b><b>install</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Installs the Python package defined by a `setup.py` script into the Python 3.4 environment. Supports options like <b>--user</b>, <b>--prefix</b>, etc.<br><br><b><b>build</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Builds the distribution files for the Python package (e.g., `.egg`, `.whl`) using Python 3.4. Options may include <b>--build-base</b>.<br><br><b><b>sdist</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a source distribution (tarball or zip file) of the Python package using Python 3.4.<br><br><b><b>bdist_wheel</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a Wheel distribution (`.whl` file) of the Python package, which is a modern standard for binary package distribution, using Python 3.4.<br><br><b><b>test</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If configured in the `setup.py` script, runs the defined test suite for the package using Python 3.4.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the `pysetup3.4` command itself or for a specific sub-command (e.g., `pysetup3.4 install --help`).<br><br><b><b>--user</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Common option for 'install')</i> Installs the package into the user's site-packages directory, preventing system-wide changes.<br><br><b><b>--prefix=<i>PATH</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Common option for 'install')</i> Specifies an alternative installation root directory for the package.<br><br>


title: DESCRIPTION
content:
The `pysetup3.4` command is <b>not a standard, universally available Linux utility</b>. Instead, it is highly probable that it represents a custom script, alias, or symlink designed to facilitate package management or setup operations specifically for the Python 3.4 interpreter. Its purpose would typically involve acting as a convenient wrapper around standard Python tools like `setup.py` or potentially `pip`, ensuring that operations are performed using the Python 3.4 environment, rather than a system's default or another Python version.<br><br>Users might encounter or create such a command in legacy environments, specific project setups, or build systems where maintaining compatibility with Python 3.4 is crucial. It streamlines tasks such as installing Python packages, building distributions, or running tests within a specific Python 3.4 context, abstracting away the explicit path to the `python3.4` executable or the complex `pip` invocations for that version.


title: CAVEATS
content:
The `pysetup3.4` command is <b>not a standard Linux command</b>. Its existence and behavior are entirely dependent on a specific system's configuration, which might involve a custom alias, a symlink, or a shell script. Therefore, its exact functionality, available options, and prerequisites can vary significantly between environments. Furthermore, Python 3.4 is an <i>end-of-life</i> (EOL) version, meaning it no longer receives official support or security updates. Relying on `pysetup3.4` often implies working with legacy systems or applications, which may pose security risks or compatibility challenges with modern libraries and operating systems.


title: CUSTOM SCRIPT NATURE
content:
It is crucial to understand that `pysetup3.4` is almost certainly a custom shell script, alias, or symlink created by a system administrator or project developer. It is not part of a standard Linux distribution or Python installation. To understand its precise functionality and available options, one would need to inspect its source code or definition on the specific system where it is used.


title: LEGACY PYTHON VERSION
content:
Python 3.4 is an outdated and unsupported version of Python. While `pysetup3.4` might be necessary for maintaining legacy applications, new development should always target actively supported Python versions (e.g., Python 3.8+), utilizing modern packaging tools like `pip` and virtual environments (`venv`).


title: HISTORY
content:
The command `pysetup3.4` likely emerged during the period when Python 3.4 was a current or widely used version (released March 2014, end-of-life March 2019). Prior to the widespread adoption and standardization of `pip` for all Python package management, and especially for older Python versions, it was common to invoke `setup.py` directly (e.g., `python3.4 setup.py install`). Commands like `pysetup3.4` would have been created to simplify this process, providing a consistent entry point for managing packages within a specific Python 3.4 environment, particularly in build scripts or development workflows for legacy applications.


title: SYNOPSIS
content:
<b>pystun3</b> [<b>-h</b>] [<b>-H</b> <i>HOST</i>] [<b>-P</b> <i>PORT</i>] [<b>-i</b> <i>INTERVAL</i>] [<b>-d</b> <i>DURATION</i>] [<b>-v</b>]


title: PARAMETERS
content:
<b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the help message and exits, providing comprehensive information about the command-line options and usage.<br><br><b><b>-H</b> <i>HOST</i>, <b>--host</b> <i>HOST</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the hostname or IP address of the STUN server to query. If omitted, it defaults to <i>stun.l.google.com</i>.<br><br><b><b>-P</b> <i>PORT</i>, <b>--port</b> <i>PORT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the port number of the STUN server. The standard STUN port is <i>19302</i>, which is used by default if no port is specified.<br><br><b><b>-i</b> <i>INTERVAL</i>, <b>--interval</b> <i>INTERVAL</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the interval in seconds between successive queries when the command is run for a specific duration. The default interval is <i>1</i> second.<br><br><b><b>-d</b> <i>DURATION</i>, <b>--duration</b> <i>DURATION</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Determines the total time in seconds for which <i><b>pystun3</b></i> should query the STUN server. A value of <i>0</i> indicates that the command should run once and then exit. The default value is <i>0</i>.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, providing more detailed information about the STUN query process, including sent requests and received responses.<br><br>


title: DESCRIPTION
content:
<i><b>pystun3</b></i> is a command-line tool and Python library designed for interacting with STUN (Session Traversal Utilities for NAT) servers. Its primary function is to help users determine their public IP address and the specific type of NAT (Network Address Translator) they are behind. This capability is crucial for establishing direct peer-to-peer connections in various real-time communication applications such as VoIP (Voice over IP) and WebRTC, especially when clients are located behind different or complex NAT configurations.<br><br>The tool operates by sending STUN binding requests to a designated STUN server and then meticulously analyzing the responses to deduce the network's topology and the client's accessible IP information. It is highly valuable for network diagnostics, testing firewall configurations, and ensuring robust connectivity for applications that necessitate direct peer-to-peer communication across diverse network environments.


title: CAVEATS
content:
<i><b>pystun3</b></i>'s functionality is dependent on the availability and proper operation of the external STUN servers it queries. Network environments with strict firewalls or specific security policies may block STUN traffic, which could prevent the tool from accurately determining NAT information. While it can identify common NAT types (e.g., Full Cone, Restricted Cone, Port Restricted Cone, Symmetric NAT), it may not provide exhaustive details for highly complex or non-standard network configurations.


title: HISTORY
content:
The <i><b>pystun</b></i> project, the precursor to <i><b>pystun3</b></i>, emerged as an open-source Python implementation of a STUN client. <i><b>pystun3</b></i> specifically denotes its compatibility and development target for Python 3 environments, distinguishing it from earlier Python 2-based versions. It was created to address the need for a lightweight and easily scriptable STUN client, particularly for developers working on applications involving VoIP, WebRTC, and other peer-to-peer communication protocols that necessitate NAT traversal capabilities. Its ongoing development focuses on maintaining a simple, functional, and reliable STUN binding request mechanism.


title: SYNOPSIS
content:
<b>python</b> [<i>options</i>] [<i>-c command</i> | <i>-m module</i> | <i>script</i>] [<i>args...</i>]


title: PARAMETERS
content:
<b><i>script</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the Python script file to execute. Subsequent arguments are passed to the script.<br><br><b><b>-c</b> <i>command</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes the Python <i>command</i> (a string) as a single statement. Useful for quick one-liners.<br><br><b><b>-m</b> <i>module</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs the specified Python library <i>module</i> as a script. This is equivalent to locating the module file and running it directly.<br><br><b><b>-i</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Inspect interactively after running <i>script</i> or <i>-c command</i> or <i>-m module</i>. Also forces prompts even if stdin does not appear to be a terminal.<br><br><b><b>-O</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optimize generated bytecode (removes assert statements and __debug__ checks).<br><br><b><b>-OO</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remove docstrings in addition to optimizations from <b>-O</b>.<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Verbose mode (trace import statements as they are executed).<br><br><b><b>-q</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Quiet mode (don't print the Python version and copyright banner on interactive startup).<br><br><b><b>-s</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Don't add the user site directory to sys.path.<br><br><b><b>-E</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ignore all PYTHON* environment variables (e.g., PYTHONPATH, PYTHONHOME).<br><br><b><b>-S</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable the import of the <i>site</i> module on startup. Useful for environments where site-specific paths or modules are not desired.<br><br><b><b>-B</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Don't write .pyc files on import of source modules. Bytecode is cached in memory only.<br><br><b><b>-W</b> <i>arg</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Warning control. Specifies how to handle warnings. E.g., 'ignore', 'default', 'error', 'always', 'module', 'once'.<br><br><b><b>-X</b> <i>opt</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set implementation-specific option. E.g., 'faulthandler', 'utf8', 'dev'.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the Python version number and exit.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print a usage help message and exit.<br><br>


title: DESCRIPTION
content:
The <b>python</b> command on Linux systems serves as the primary interpreter for the Python programming language. It allows users to execute Python scripts, run Python modules directly, or enter an interactive Python shell for immediate code execution and testing.<br><br>When invoked without arguments, it typically launches the interactive interpreter, providing a convenient environment for experimenting with Python code. With arguments, it can execute a specified Python script file (`.py`), run a Python module as a script using the <i>-m</i> option, or execute a single line of Python code using the <i>-c</i> option. The command is fundamental for developing, testing, and deploying Python applications and utilities across various Linux distributions. It is widely used for web development, data analysis, automation, system administration, and scientific computing.


title: CAVEATS
content:
On many Linux systems, the default <b>python</b> command often symlinks to Python 2 (e.g., <i>/usr/bin/python</i> -> <i>/usr/bin/python2</i>) for backward compatibility, while <b>python3</b> points to Python 3. It's crucial to specify <b>python3</b> explicitly for modern applications to avoid compatibility issues. Using virtual environments (created via <i>python3 -m venv</i> or <i>virtualenv</i>) is highly recommended to manage project dependencies and avoid conflicts with system-wide Python installations.


title: ENVIRONMENT VARIABLES
content:
The behavior of the <b>python</b> command can be influenced by several environment variables:<br><i><b>PYTHONPATH</b></i>: A colon-separated list of directories added to the default module search path.<br><i><b>PYTHONSTARTUP</b></i>: Path to an initialization file executed when the interactive interpreter starts.<br><i><b>PYTHONCASEOK</b></i>: (Windows only) Ignores case in 'import' statements.<br><i><b>PYTHONIOENCODING</b></i>: Forces the encoding for stdin/stdout/stderr.


title: SHEBANG LINE
content:
For making Python scripts executable directly, the 'shebang' line is crucial. It specifies the interpreter to use for the script. For example: <br><i>#!/usr/bin/env python3</i><br>This tells the kernel to execute the script using the <b>python3</b> interpreter found in the system's PATH. Ensure the script has executable permissions (<i>chmod +x script.py</i>).


title: HISTORY
content:
Python was created by Guido van Rossum in the late 1980s, with its first release in 1991. The <b>python</b> command became the standard way to invoke the interpreter on Unix-like systems. A significant evolution occurred with the release of Python 3.0 in 2008, which introduced backward-incompatible changes. This led to a period where both Python 2 and Python 3 interpreters co-existed, often accessible via `python` (for version 2) and `python3` commands, respectively. As of 2020, Python 2 is officially deprecated, and Python 3 is the current and actively developed version, making `python3` the preferred command for new projects.


title: PARAMETERS
content:
<b><I>directory</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the directory where the virtual environment will be created. If the directory does not exist, it will be created.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br><b>--clear</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Delete the contents of the environment directory if it already exists, then recreate the environment.<br><br><b>--symlinks</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Default on Unix) Try to use symlinks rather than copying files into the virtual environment.<br><br><b>--copies</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Default on Windows) Try to use copies rather than symlinks when creating the virtual environment.<br><br><b>--without-pip</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skip installing <i>pip</i> into the virtual environment. <i>pip</i> is usually installed by default to manage packages.<br><br><b>--system-site-packages</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Give the virtual environment access to the system site-packages directory. By default, environments are isolated from system packages.<br><br>


title: DESCRIPTION
content:
<i>pyvenv-3.4</i> is a command-line utility used to create isolated Python 3.4 environments. It allows users to manage project-specific dependencies without interfering with the system-wide Python installation. When executed, <i>pyvenv-3.4</i> sets up a new directory containing a copy or symlinks to the Python 3.4 executable, its standard library, and typically an isolated site-packages directory where project-specific packages can be installed.<br><br>This specific command is an alias or direct link to the <i>pyvenv</i> utility as shipped with Python version 3.4. It was introduced in Python 3.3 as part of the built-in <i>venv</i> module, aiming to provide a lightweight and official alternative to the popular third-party <i>virtualenv</i> tool. While functional for its intended version, the standalone <i>pyvenv</i> command was deprecated in Python 3.6 in favor of using <i>python -m venv</i> directly. This latter approach is now the standard and recommended way to create virtual environments, as it explicitly ties the environment creation to the invoked Python interpreter.


title: CAVEATS
content:
<b>Deprecation</b>: The <i>pyvenv</i> command (and thus <i>pyvenv-3.4</i>) was deprecated in Python 3.6 and completely removed in Python 3.8. It is strongly recommended to use <i>python3.4 -m venv</i> or simply <i>python -m venv</i> with the appropriate Python version if you need a Python 3.4 environment.<br><br><b>Version Specificity</b>: This command is hard-coded for Python 3.4. It will not work with other Python versions.<br><br><b>Pip Installation</b>: While <i>pip</i> is usually installed by default with <i>venv</i>, older Python 3.4 installations might require the <i>ensurepip</i> module to be run if <i>pip</i> is missing.


title: USAGE EXAMPLE
content:
To create a new virtual environment named <i>my_env</i> in the current directory using Python 3.4:<br><code><I>pyvenv-3.4 my_env</I></code><br><br>To activate the newly created environment:<br>On Linux/macOS:<br><code><I>source my_env/bin/activate</I></code><br>On Windows (Command Prompt):<br><code><I>my_env\Scripts\activate.bat</I></code><br><br>After activation, commands like <i>python</i> and <i>pip</i> will refer to the versions and installations within <i>my_env</i>, keeping your project's dependencies isolated.


title: HISTORY
content:
The concept of isolated virtual environments gained significant traction in the Python community with the popular third-party <i>virtualenv</i> tool. Python 3.3 introduced the <i>venv</i> module as a built-in solution, providing <i>pyvenv</i> as its command-line entry point. <i>pyvenv-3.4</i> would have been the specific executable or link tied to Python 3.4's <i>venv</i> module.<br><br>This standalone <i>pyvenv</i> command, however, sometimes caused confusion regarding which Python interpreter it would use if multiple versions were installed. To clarify this and simplify usage, the Python core developers decided to deprecate the standalone <i>pyvenv</i> command in Python 3.6, encouraging users to invoke the <i>venv</i> module directly via <i>python -m venv</i>. This change ensured that the virtual environment was created by the specific <i>python</i> interpreter invoked, removing ambiguity.


title: PARAMETERS
content:
<b><b>-r</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints only the default Python runtime version (e.g., "python3").<br><br><b><b>-s</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Formats output in a style suitable for shell scripts, often space-separated versions.<br><br><b><b>-i</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays versions along with their installation paths or additional installation details.<br><br><b><b>-d</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides detailed information for each version, potentially including architecture.<br><br><b><b>-V</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the version information for the <I>pyversions</I> command itself.<br><br><b><b>-h, --help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message and exits.<br><br>


title: DESCRIPTION
content:
<I>pyversions</I> is a utility designed for Debian-based systems to display a list of Python versions installed and managed through the <I>python-minimal</I> package and the <I>update-alternatives</I> system.<br><br>It provides a quick way to ascertain which Python interpreters are available for use in scripting and development. This command helps users and package maintainers understand the Python environment setup, especially relevant in systems where multiple major Python versions (like Python 2 and Python 3) coexist.<br><br>It is particularly useful for identifying the default Python runtime and other available versions, aiding in proper script execution and dependency management.


title: CAVEATS
content:
This command is primarily available and relevant on Debian-based Linux distributions (e.g., Ubuntu). It relies on the <I>update-alternatives</I> system and the <I>python-minimal</I> package for its functionality. It may not be present or behave similarly on other Linux distributions or operating systems.


