# CommandSection

title: DESCRIPTION
content:
<i>hciconfig</i> is a command-line utility used to configure Bluetooth High-Level Interface (HCI) devices on Linux systems. It allows administrators to manage various aspects of Bluetooth adapters, including bringing them up or down, changing local device addresses, setting scan modes (inquiry and page scan), enabling or disabling authentication and encryption, and managing device class settings. It provides direct control over the HCI layer, making it invaluable for advanced Bluetooth configurations, scripting automated tasks, and debugging Bluetooth connectivity issues. While newer tools like <i>bluetoothctl</i> offer more user-friendly interaction for common tasks, <i>hciconfig</i> remains a powerful tool for low-level device management and detailed status retrieval.


title: CAVEATS
content:
Many <i>hciconfig</i> commands that modify device parameters require root privileges (or execution via <i>sudo</i>).<br><br>While powerful, <i>hciconfig</i> operates at a low-level HCI interface and might not be the most straightforward tool for common user tasks. For general Bluetooth management and pairing, <i>bluetoothctl</i> is often preferred due to its interactive and user-friendly interface.<br><br>Some modern Bluetooth features or device-specific settings might not be fully controllable via <i>hciconfig</i>, depending on the kernel and BlueZ version.


title: PERMISSIONS
content:
To modify the settings of a Bluetooth device using <i>hciconfig</i>, you must have root privileges. Running commands like <b>hciconfig hci0 up</b> will require <i>sudo</i>. However, checking the status of devices (e.g., <b>hciconfig</b> or <b>hciconfig -a</b>) typically does not require elevated privileges.


title: DEVICE NAMING CONVENTION
content:
Bluetooth devices on Linux are typically named <i>hci0</i>, <i>hci1</i>, and so forth, similar to network interfaces (<i>eth0</i>, <i>wlan0</i>). The first detected Bluetooth adapter is usually <i>hci0</i>. You can see a list of available devices by simply running <b>hciconfig</b> without any arguments.


title: HISTORY
content:
<i>hciconfig</i> has been a fundamental part of the BlueZ Bluetooth protocol stack for Linux since its early development. It was one of the primary tools for system administrators to interact with and configure Bluetooth hardware before more advanced and user-friendly interfaces like <i>bluetoothctl</i> became prevalent. Its design reflects a direct interface to the HCI (Host Controller Interface) layer, providing fine-grained control over Bluetooth adapters. Although its direct usage by end-users has decreased in favor of higher-level tools, it remains crucial for scripting, debugging, and managing low-level Bluetooth device properties on Linux.


title: PARAMETERS
content:
<b>-i, --index=<N></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the <b>device index</b> for the emulated controller (default: 0).<br><br><b>-c, --class=<CLASS></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the <b>Class of Device</b> (CoD) for the emulated controller, typically a 24-bit hexadecimal value (default: 0x000000).<br><br><b>-s, --speed=<SPEED></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the <b>baud rate</b> for the serial port communication used by the emulator. Relevant when not using a pseudo-terminal.<br><br><b>-p, --pty</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs <i>hciemu</i> to use a <b>pseudo-terminal</b> (pty) for communication. When enabled, the path to the pseudo-terminal device (e.g., <i>/dev/pts/X</i>) is printed to standard output, which can then be used by the Bluetooth daemon (<i>bluetoothd</i>) or other applications as the serial port connection to the emulated device. This is the most common and flexible way to use <i>hciemu</i>.<br><br><b>-P, --pidfile=<FILE></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the <b>process ID</b> (PID) of the <i>hciemu</i> instance to the specified <i>FILE</i>.<br><br><b>-u, --uuids=<UUIDS></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a comma-separated list of <b>supported service UUIDs</b> that the emulated device should advertise. These are typically 16-bit UUIDs.<br><br><b>-n, --nodisc</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents the emulator from disconnecting upon the client closing its connection. This keeps the emulated device active.<br><br><b>-S, --sniff=<FILE></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Dumps all <b>HCI traffic</b> (commands, events, ACL data, SCO data) to the specified <i>FILE</i> for later analysis or debugging.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a <b>help message</b> and exits.<br><br><b>-v, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the <b>version information</b> of <i>hciemu</i> and exits.<br><br>


title: DESCRIPTION
content:
<i>hciemu</i> is a utility from the <b>BlueZ</b> project designed to emulate a Bluetooth Host Controller Interface (HCI) device. This tool is primarily used for <b>development and testing</b> purposes, allowing Bluetooth host stacks (like the Linux kernel's Bluetooth stack or the <i>bluetoothd</i> daemon) to interact with a virtual Bluetooth controller without requiring physical Bluetooth hardware. It simulates the low-level HCI protocol communication, often via a pseudo-terminal (pty) or a specified serial device. This enables developers to test various Bluetooth functionalities, discover protocol issues, and debug applications in a controlled and reproducible environment, making it an invaluable asset for Bluetooth software engineers.


title: CAVEATS
content:
<i>hciemu</i> requires appropriate permissions, often <b>root privileges</b> or the <b>CAP_NET_ADMIN</b> capability, to create and manage virtual network interfaces and pseudo-terminals. <br>It is primarily a <b>development tool</b> and not intended for general user use or production environments. Misuse can lead to conflicts with actual Bluetooth hardware or system instability if not properly isolated. The emulation fidelity depends on the version and may not perfectly replicate all real-world hardware behaviors or quirks.


title: TYPICAL USAGE WITH PSEUDO-TERMINALS
content:
The most common way to use <i>hciemu</i> is with the <b>--pty</b> option. This creates a pseudo-terminal, and its path (e.g., <i>/dev/pts/3</i>) is printed to standard output. This path can then be passed to the <i>bluetoothd</i> daemon (e.g., <i>bluetoothd -E -C -p /dev/pts/3</i>) or other applications to connect to the emulated device. This allows for isolated testing environments where the emulated device can be started and stopped without affecting other Bluetooth interfaces.


title: DEBUGGING AND TESTING
content:
<i>hciemu</i> is invaluable for debugging Bluetooth applications and protocol interactions. By using the <b>--sniff</b> option, developers can capture all HCI commands, events, and data packets exchanged between the host and the emulated controller. This captured data can then be analyzed with tools like Wireshark (which understands HCI logging formats) to identify protocol errors or unexpected behavior.


title: HISTORY
content:
<i>hciemu</i> is an integral part of the <b>BlueZ</b> project, the official Linux Bluetooth protocol stack. BlueZ development began in the early 2000s, with <i>hciemu</i> being developed alongside the core stack to facilitate robust testing and debugging. Its primary purpose has always been to provide a controlled, software-based environment for testing kernel modules, drivers, and user-space applications related to Bluetooth without the need for diverse or specific physical hardware. This has been crucial for continuous integration and automated testing of the BlueZ stack over the years.


title: SYNOPSIS
content:
<B>hcitool</B> [<i>--help</i>] [<i>--version</i>]<br><B>hcitool</B> [<i><I>options</I></i>] <I>command</I> [<i><I>command_options</I></i>]


title: PARAMETERS
content:
<b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Displays the help message and exits.</I><br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Displays the version information and exits.</I><br><br><b>dev</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Displays information about local Bluetooth devices (HCIs).</I><br><br><b>inq</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Performs a Bluetooth inquiry to discover nearby classic Bluetooth devices.</I><br><br><b>scan</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Scans for and lists visible classic Bluetooth devices along with their names.</I><br><br><b>cc <bdaddr></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Creates a classic Bluetooth connection to the specified device address (BD_ADDR).</I><br><br><b>dc <bdaddr></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Disconnects an existing classic Bluetooth connection from the specified device address.</I><br><br><b>cmd <ogf> <ocf> [parameters...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Sends an arbitrary HCI command to the controller. OGF (Opcode Group Field) and OCF (Opcode Command Field) define the command. Parameters are optional and specific to the command's requirements.</I><br><br><b>lecc <bdaddr> [type]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Creates a Bluetooth Low Energy (LE) connection to the specified device address. Type specifies the address type (public or random).</I><br><br><b>ledc <handle></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Disconnects an existing Bluetooth Low Energy (LE) connection using its connection handle.</I><br><br><b>lescan [type]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Starts or stops an LE scan. Optionally specifies the scan type (active or passive).</I><br><br>


title: DESCRIPTION
content:
<I>hcitool</I> is a command-line utility that provides a way to interact with Bluetooth Host Controller Interface (HCI) devices. It is part of the <I>BlueZ</I> Bluetooth protocol stack for Linux. This tool allows users to perform various low-level Bluetooth operations, such as querying local Bluetooth devices, scanning for remote devices, establishing and terminating connections, and sending raw HCI commands. <I>hcitool</I> is particularly useful for diagnostics, debugging, and advanced configuration of Bluetooth hardware and connections, providing more granular control than higher-level tools.<br><br>While modern Linux distributions often recommend <I>bluetoothctl</I> for general Bluetooth management due to its more user-friendly interface, <I>hcitool</I> remains indispensable for specific tasks requiring direct interaction with the HCI layer, especially for Bluetooth Low Energy (LE) operations and sending custom commands.


title: CAVEATS
content:
<I>hcitool</I> typically requires <B>root privileges</B> (e.g., using <B>sudo</B>) to perform most of its operations, especially those that modify device configuration or establish connections.<br><br>Many of its functionalities, particularly for general Bluetooth management, have been largely superseded by the more user-friendly <I>bluetoothctl</I> command-line tool, which is part of the modern <I>BlueZ</I> suite. While <I>hcitool</I> offers granular control at the HCI layer, it may not support all the latest Bluetooth profiles or features as comprehensively as higher-level tools or daemon services.


title: RAW HCI COMMAND EXECUTION
content:
<I>The <B>cmd</B> subcommand in <I>hcitool</I> is exceptionally powerful, allowing users to send arbitrary HCI commands directly to the Bluetooth controller. This requires a deep understanding of the Bluetooth HCI specification (Bluetooth Core Specification), including Opcode Group Fields (OGF) and Opcode Command Fields (OCF), and the specific parameters required for each command. It's primarily used for advanced debugging, testing, and custom controller interactions.</I>


title: BLUETOOTH LOW ENERGY (LE) OPERATIONS
content:
<I>hcitool</I> provides a suite of commands prefixed with "<B>le</B>" (e.g., <B>lescan</B>, <B>lecc</B>) specifically for interacting with Bluetooth Low Energy devices. These commands are essential for developers and testers working with LE-enabled hardware and applications, offering granular control over LE scanning, advertising, and connection parameters.


title: HISTORY
content:
<I>hcitool</I> has been a fundamental part of the <I>BlueZ</I> Bluetooth stack for Linux since its early days. It emerged as one of the primary command-line tools for direct interaction with Bluetooth Host Controller Interface devices. Before the advent of more abstract and user-friendly tools like <I>bluetoothctl</I>, <I>hcitool</I> (along with <I>hciconfig</I>) was the go-to utility for Bluetooth device management, diagnostics, and development. Its longevity attests to its utility in providing low-level access, even as high-level management shifted to other tools. While its direct interactive use for everyday tasks has diminished, it remains crucial for scripting, automated testing, and deep-dive troubleshooting at the HCI layer.


title: SEE ALSO
content:
bluetoothctl(1) - <I>Modern interactive Bluetooth control utility.</I>, hciconfig(8) - <I>Configures Bluetooth HCI devices.</I>, rfkill(8) - <I>Enables or disables wireless devices.</I>, sdptool(1) - <I>Manages Bluetooth Service Discovery Protocol (SDP) records.</I>


title: PARAMETERS
content:
<b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays usage information and exits.<br><br><b><b>-i</b> <i>&lt;hci_dev&gt;</i>, <b>--device</b> <i>&lt;hci_dev&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the HCI device to trace, such as <i>hci0</i>. If not specified, <i>hci0</i> is often used by default.<br><br><b><b>-r</b> <i>&lt;file&gt;</i>, <b>--read</b> <i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads HCI data from a <i>hcidump</i> format file instead of capturing live traffic from a device.<br><br><b><b>-t</b>, <b>--timestamp</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a timestamp for each captured HCI packet, indicating when it was received.<br><br><b><b>-x</b>, <b>--hex</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the raw hexadecimal data of each HCI packet in addition to the decoded information.<br><br><b><b>-V</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the <i>hcitrace</i> version information and exits.<br><br>


title: DESCRIPTION
content:
<i>hcitrace</i> is a powerful Linux command-line utility designed to capture and display Bluetooth HCI (Host Controller Interface) traffic. It acts as a sniffer for the communication between the host (e.g., Linux kernel or user applications) and the Bluetooth controller hardware.<br><br>This tool is invaluable for debugging Bluetooth connectivity issues, analyzing protocol behavior, and aiding in the development of Bluetooth applications. It provides a real-time stream of HCI commands (from host to controller) and HCI events (from controller to host), often including detailed decoding of these packets. Users can specify a particular HCI device to monitor, display timestamps for events, and optionally view the raw hexadecimal data for deep analysis. While it can operate in live capture mode, it also supports reading previously recorded data from files generated by <i>hcidump</i>, making it versatile for both immediate diagnostics and post-mortem analysis of Bluetooth communication failures. Its primary strength lies in providing a granular view of the Bluetooth stack's interaction with the underlying hardware, essential for understanding low-level protocol exchanges.


title: CAVEATS
content:
<i>hcitrace</i> requires <b>root privileges</b> (or equivalent capabilities) to capture live HCI traffic directly from a Bluetooth device. Without these elevated permissions, it will typically fail to open the necessary device interfaces. The output can be extremely verbose, especially on busy Bluetooth systems, potentially overwhelming the terminal with data. While <i>hcitrace</i> decodes many standard HCI commands and events, its ability to decode proprietary or very new Bluetooth features might be limited. Furthermore, it only shows traffic that passes through the HCI layer, meaning some kernel-level optimizations or driver-specific interactions might not be visible.


title: OUTPUT FORMAT
content:
The typical output of <i>hcitrace</i> includes a timestamp (if <b>-t</b> is used), an indicator of packet direction (e.g., <b>&gt;</b> for host-to-controller commands, <b>&lt;</b> for controller-to-host events), the general packet type (e.g., <i>HCI Command</i>, <i>HCI Event</i>), a human-readable decoded description of the command or event, and optionally, the raw hexadecimal data (if <b>-x</b> is used). This comprehensive output enables detailed analysis of the Bluetooth communication flow, aiding in pinpointing protocol-level issues.


title: PERMISSIONS
content:
For <i>hcitrace</i> to capture live HCI traffic directly from a Bluetooth device, it requires <b>root privileges</b>. This is due to the nature of accessing raw network interfaces and packet sockets, which are typically restricted for security reasons. Attempting to run <i>hcitrace</i> in live capture mode without sufficient permissions will usually result in an error indicating an inability to open the device. However, when using the <b>-r</b> option to read from a pre-recorded <i>hcidump</i> file, elevated privileges are not necessary, as the data is accessed from a standard file.


title: HISTORY
content:
<i>hcitrace</i> is an integral part of the BlueZ project, which serves as the official Linux Bluetooth protocol stack. BlueZ has been a cornerstone of Bluetooth support on Linux since its inception in the early 2000s. <i>hcitrace</i>, alongside utilities like <i>hcidump</i> and <i>hcitool</i>, were among the initial suite of tools developed to enable detailed interaction and debugging of the Bluetooth stack. While the ecosystem has evolved with newer, more user-friendly tools like <i>btmon</i> and <i>bluetoothctl</i>, <i>hcitrace</i> retains its niche as a reliable utility for low-level, raw HCI packet inspection. Its core functionality for tracing and displaying HCI communications has remained largely consistent, making it a valuable resource for developers and network engineers involved in deep Bluetooth analysis.


title: PARAMETERS
content:
<b><i>GLOBAL-OPTIONS</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Options that apply to the <b>hcloud</b> command itself, regardless of the subcommand. These are typically placed immediately after <b>hcloud</b>.<br><br><b><b>--token</b> <i>&lt;TOKEN&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly specifies the Hetzner Cloud API token for authentication. This overrides tokens from configuration files or environment variables.<br><br><b><b>--output</b> <i>&lt;FORMAT&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the output format for the command's results. Common formats include <b>columns</b> (default, human-readable table), <b>json</b>, and <b>yaml</b>. Useful for scripting and programmatic parsing.<br><br><b><b>--no-headers</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses column headers when using the <b>columns</b> output format, resulting in raw data only.<br><br><b><b>--api-url</b> <i>&lt;URL&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a custom API endpoint URL, typically used for testing or specific regional endpoints if applicable.<br><br><b><b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose debug output, showing detailed information about API requests and responses, useful for troubleshooting.<br><br><b><b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases verbosity of output, providing more detailed information about command execution and progress.<br><br><b><b>--help</b>, <b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the specified command or subcommand, detailing available options and usage examples.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the current version of the <b>hcloud</b> CLI tool.<br><br><b><i>COMMAND</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Refers to a top-level resource or service within Hetzner Cloud that you wish to interact with, such as <b>server</b>, <b>volume</b>, <b>network</b>, <b>firewall</b>, <b>load-balancer</b>, <b>ssh-key</b>, <b>image</b>, etc. Each command has its own set of subcommands and flags.<br><br><b><i>SUBCOMMAND</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Refers to a specific action to be performed on the designated <i>COMMAND</i> (resource). Examples include <b>list</b> (to view resources), <b>create</b> (to provision a new resource), <b>delete</b> (to remove a resource), <b>update</b> (to modify resource properties), <b>attach</b>, <b>detach</b>, <b>poweron</b>, <b>rebuild</b>, etc.<br><br><b><i>FLAGS</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Options specific to a <i>COMMAND</i> or <i>SUBCOMMAND</i>, used to specify parameters for an action. Common examples include <b>--name</b> <i>&lt;RESOURCE_NAME&gt;</i>, <b>--type</b> <i>&lt;RESOURCE_TYPE&gt;</i>, <b>--id</b> <i>&lt;RESOURCE_ID&gt;</i>, <b>--location</b> <i>&lt;DATACENTER&gt;</i>, <b>--image</b> <i>&lt;IMAGE_NAME_OR_ID&gt;</i>, <b>--label</b> <i>&lt;KEY=VALUE&gt;</i>, and <b>--protection</b> <i>&lt;enable|disable&gt;</i>.<br><br>


title: DESCRIPTION
content:
The <b>hcloud</b> command-line interface (CLI) is the official tool for interacting with the Hetzner Cloud API. It provides a powerful and flexible way to manage all your Hetzner Cloud resources directly from your terminal, without needing to access the web interface. Users can provision, configure, and monitor servers, networks, volumes, firewalls, load balancers, and more. It is particularly useful for scripting, automation, and integrating Hetzner Cloud operations into CI/CD pipelines, enabling infrastructure as code practices. The CLI supports various output formats, including human-readable tables, JSON, and YAML, making it easy to parse and integrate its output with other tools.


title: CAVEATS
content:
Authentication with the Hetzner Cloud API requires a valid API token. This token should be kept secure and can be provided via a configuration file (<b>~/.config/hcloud/cli.toml</b>), an environment variable (<b>HCLOUD_TOKEN</b>), or directly using the <b>--token</b> flag. <br>Users should be mindful of Hetzner Cloud's API rate limits, as excessive requests in a short period can lead to temporary blocking of requests. <br>Commands that delete resources are irreversible; extreme caution is advised, especially when integrating deletion tasks into automated scripts. <br>Many commands operate on resource IDs (e.g., server ID, volume ID), which typically need to be retrieved first using a <b>list</b> subcommand.


title: CONFIGURATION & AUTHENTICATION
content:
The <b>hcloud</b> CLI can be configured through a TOML file located at <b>~/.config/hcloud/cli.toml</b> (or <b>$XDG_CONFIG_HOME/hcloud/cli.toml</b>). This file is typically used to store the default API token and other global settings. The API token can also be passed via the <b>HCLOUD_TOKEN</b> environment variable or directly using the <b>--token</b> global flag. The precedence for API token lookup is: <b>--token</b> flag > <b>HCLOUD_TOKEN</b> environment variable > configuration file.


title: AUTOMATION & SCRIPTING
content:
Given its command-line nature and robust support for structured output formats like JSON and YAML, <b>hcloud</b> is an exceptional tool for automating cloud infrastructure management. It can be seamlessly integrated into shell scripts, CI/CD pipelines, and configuration management tools (like Ansible or Terraform via their respective Hetzner Cloud providers). This capability facilitates programmatic control over cloud resources, enabling infrastructure as code practices, repeatable deployments, and dynamic scaling operations.


title: HISTORY
content:
The <b>hcloud</b> CLI tool was developed by Hetzner Online GmbH as the official command-line interface for their Hetzner Cloud platform. Written in Go, it leverages the Hetzner Cloud API to provide a comprehensive management tool. Since its initial release (around 2017-2018), it has been actively maintained and continuously updated to support new Hetzner Cloud features, resources, and API versions, reflecting the platform's ongoing development and expansion.


title: SYNOPSIS
content:
<b>hd</b> [<i>OPTIONS</i>] [<i>FILE</i>...]<br><br><i>Note: The <b>hd</b> command is commonly an alias for <b>hexdump -C</b>. Therefore, its options are typically those supported by <b>hexdump</b> when used with the canonical output format.</i>


title: PARAMETERS
content:
<b><i>FILE</i>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more input files to be dumped. If no <i>FILE</i> is specified, <b>hd</b> reads from standard input.<br><br><b>-n <i>count</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Interpret only <i>count</i> bytes of input.<br><br><b>-s <i>offset</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skip <i>offset</i> bytes from the beginning of the input before dumping.<br><br><b>-v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display all input data. By default, <b>hd</b> (via <b>hexdump</b>) replaces lines of identical input with an asterisk ('*') to conserve space. The <b>-v</b> option forces all data to be displayed.<br><br>


title: DESCRIPTION
content:
<b>hd</b> is a utility used to display the contents of files or standard input in a canonical hexadecimal and ASCII format. It is most commonly implemented as a symbolic link or an alias to the <b>hexdump -C</b> command, which is part of the <b>util-linux</b> package. This command is invaluable for inspecting binary data, debugging compiled programs, analyzing network packet captures, or examining disk images.<br><br>The output of <b>hd</b> presents data in three main columns: an offset from the beginning of the input, the hexadecimal representation of the bytes (typically 16 bytes per line), and the corresponding ASCII characters for those bytes. Non-printable ASCII characters are usually represented by a dot ('.'). <b>hd</b> provides a quick and clear way to visualize the raw byte structure of any file, making it an essential tool for developers, security analysts, and system administrators working with low-level data.


title: CAVEATS
content:
<b>hd</b> is generally a convenience alias for <b>hexdump -C</b> and not a standalone utility with its own independent development or complex options. Its availability and exact behavior can depend on the system's <b>util-linux</b> version or shell configurations. For very large files, the output can be extensive. Always use with caution, especially when piping to other commands.


title: <I>OUTPUT FORMAT EXPLAINED</I>
content:
The output of <b>hd</b> typically consists of three parts per line:<br>1. <i>Offset</i>: The byte offset from the beginning of the input, usually in hexadecimal.<br>2. <i>Hexadecimal Bytes</i>: 16 bytes of input data displayed in hexadecimal pairs, often grouped into two blocks of 8 bytes.<br>3. <i>ASCII Representation</i>: The ASCII characters corresponding to the 16 bytes. Non-printable characters are represented by a dot ('.').


title: <I>COMMON USE CASES</I>
content:
<b>hd</b> is highly useful for:<br> - <i>Debugging</i>: Understanding the raw structure of binary files, executables, or core dumps.<br> - <i>Forensics</i>: Inspecting disk images, memory dumps, or network packet captures for specific byte sequences or artifacts.<br> - <i>Reverse Engineering</i>: Analyzing compiled programs to understand their internal data structures or code sections.<br> - <i>File Header Inspection</i>: Quickly viewing the initial bytes of a file to identify its format based on magic numbers.


title: HISTORY
content:
The functionality provided by <b>hd</b> (canonical hex dumping) originates from the <b>hexdump</b> utility, which has been a part of Unix-like systems for decades. <b>hexdump</b> itself is maintained as part of the <b>util-linux</b> project, a collection of essential Linux system utilities. The specific <b>hd</b> command is a common and convenient alias or symbolic link to <b>hexdump -C</b>, allowing users to quickly access this canonical output format without typing the full option.


title: PARAMETERS
content:
<b>-d, --daemon</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs <i>hddtemp</i> as a background daemon, continuously monitoring specified devices.<br><br><b>-w, --webserver</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts an HTTP web server, allowing temperature data to be viewed via a web browser. Implies --daemon.<br><br><b>-p <port>, --port=<port></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the TCP port number for the daemon or web server (default is 7634).<br><br><b>-l <address>, --listen=<address></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the IP address to listen on for daemon/web server connections (default is all interfaces).<br><br><b>-n, --numeric</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays temperature in numeric form only, without the unit (e.g., '35' instead of '35°C').<br><br><b>-q, --quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses headers and other non-temperature output, useful for scripting.<br><br><b>-u <C|F>, --unit=<C|F></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the temperature unit: 'C' for Celsius (default) or 'F' for Fahrenheit.<br><br><b>-f <config_file>, --file=<config_file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative configuration file.<br><br><b>-s, --status</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the status of specified devices (e.g., if S.M.A.R.T. is supported and enabled).<br><br><b>-v, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the <i>hddtemp</i> version information.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows a help message and exits.<br><br>


title: DESCRIPTION
content:
<i>hddtemp</i> is a command-line utility for Linux and Unix-like operating systems that reports the temperature of S.M.A.R.T. (Self-Monitoring, Analysis and Reporting Technology) enabled hard drives. It reads the temperature attribute directly from the drive's S.M.A.R.T. data, providing real-time information about its operational temperature. This is crucial for proactive system maintenance, as excessive heat can lead to premature drive failure and data loss.<br><br><i>hddtemp</i> can be run in a single-shot mode to display the temperature of specified devices, or it can operate as a daemon, continuously monitoring temperatures and making this data available over a network port (HTTP or raw data) for logging, graphing applications, or other monitoring tools. It primarily supports various ATA/SATA hard drives and requires S.M.A.R.T. support to be enabled in the drive's firmware and, potentially, the system's BIOS.


title: CAVEATS
content:
<i>hddtemp</i> relies on S.M.A.R.T. functionality, which must be enabled in the hard drive's firmware and potentially the system's BIOS/UEFI settings.<br><br>Not all hard drives, particularly older models or some specific vendors/interfaces (like some RAID controllers or NVMe SSDs), fully support reporting temperature via S.M.A.R.T. attributes that <i>hddtemp</i> can read. For NVMe devices, <i>nvme-cli</i> is typically used.<br><br>Running <i>hddtemp</i> often requires root privileges or appropriate kernel capabilities (<i>CAP_SYS_RAWIO</i>) to access raw S.M.A.R.T. data from the hard drive.<br><br>If running as a daemon, ensure proper firewall rules are in place if exposing the port to the network.


title: DAEMON MODE BENEFITS
content:
When run as a daemon (<i>-d</i> or <i>-w</i>), <i>hddtemp</i> can continuously monitor drive temperatures in the background. This is invaluable for long-term health monitoring, allowing administrators to collect historical data for trending, set up alerts for high temperatures, or integrate with graphing solutions like RRDtool or Prometheus for performance and health visualization. It avoids the overhead of spawning a new process for each temperature check.


title: S.M.A.R.T. DEPENDENCE
content:
<i>hddtemp</i> specifically leverages the S.M.A.R.T. interface of hard drives. If a drive does not support S.M.A.R.T., or if S.M.A.R.T. is disabled, <i>hddtemp</i> will be unable to retrieve temperature information. Users might need to consult their drive's documentation or the system's BIOS settings to ensure S.M.A.R.T. is active. This dependency means it's not a universal temperature sensor for all storage types.


title: HISTORY
content:
<i>hddtemp</i> was originally written by Stuart M. Henderson and has been maintained by various contributors over the years. It has become a standard utility in many Linux distributions, providing a simple yet effective way to monitor hard drive temperatures, which is critical for preventing data loss and ensuring the longevity of storage devices. Its development has focused on supporting a wide range of ATA/SATA controllers and drives, adapting to evolving hardware standards.


title: PARAMETERS
content:
<b><b>-a</b> <i>&lt;sectors&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Get or set the sector count for filesystem read-ahead.<br><br><b><b>-A</b> <i>&lt;0/1&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable or enable the drive's built-in read-lookahead feature (cache).<br><br><b><b>-B</b> <i>&lt;level&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the Advanced Power Management (APM) level for the drive (1-254, 255 disables).<br><br><b><b>-c</b> <i>&lt;0/1/3&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Get or set the 32-bit I/O support flag. (Mostly deprecated/ignored on modern systems).<br><br><b><b>-C</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Check the drive's current power mode status (e.g., active, idle, standby).<br><br><b><b>-d</b> <i>&lt;0/1&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable or enable using DMA (Direct Memory Access). (Usually enabled by default and managed by kernel).<br><br><b><b>-f</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Flush the buffer cache for the specified device.<br><br><b><b>-g</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display drive geometry (cylinders, heads, sectors) and size.<br><br><b><b>-i</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display basic identification info from the drive.<br><br><b><b>-I</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display detailed identification info, including SMART data and supported features.<br><br><b><b>-m</b> <i>&lt;sectors&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Get or set the multiple sector I/O count (the number of sectors per I/O interrupt).<br><br><b><b>-M</b> <i>&lt;level&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the Automatic Acoustic Management (AAM) level for the drive.<br><br><b><b>-q</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress most messages during operations (quiet mode).<br><br><b><b>-S</b> <i>&lt;timeout&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the standby (spindown) timeout for the drive in units of 5 seconds (0=off, 241-251=special).<br><br><b><b>-t</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform device read timings (direct disk reads, bypassing the OS buffer cache).<br><br><b><b>-T</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform cache read timings (reads from the OS buffer cache).<br><br><b><b>-u</b> <i>&lt;0/1&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Get or set the interrupt-unmask flag (can improve responsiveness but might cause issues).<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display all settings for the specified drive in a verbose format.<br><br><b><b>-w</b> <i>&lt;0/1&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Get or set the drive's write-caching feature.<br><br><b><b>-W</b> <i>&lt;0/1&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable or enable the drive's write-caching feature.<br><br><b><b>-y</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the drive immediately into standby mode.<br><br><b><b>-Y</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the drive immediately into sleep mode.<br><br><b><b>-z</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Tell the kernel to re-read the partition table for the specified device.<br><br><b><b>-Z</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable write-caching for <i>all</i> ATA devices. <b>USE WITH EXTREME CAUTION!</b><br><br>


title: DESCRIPTION
content:
<b>hdparm</b> is a command-line utility used for manipulating various hardware parameters of ATA/SATA hard disk drives. It allows users to query settings, optimize performance, manage power consumption, and control security features directly at the device level.<br><br>Common uses include testing disk read speeds (cached and uncached), enabling or disabling write caching, adjusting Advanced Power Management (APM) levels, and setting standby timeouts. Because <b>hdparm</b> interacts directly with the device driver, it requires root privileges to execute most operations. While highly effective for fine-tuning, misuse can potentially lead to data loss or system instability, especially when modifying write-caching or security parameters. On modern systems, some of its performance-tuning options might be less critical or even deprecated compared to its historical importance, but it remains a valuable tool for diagnostics and power management.


title: CAVEATS
content:
<b>hdparm</b> requires root privileges to operate. Incorrect usage, particularly with options that modify write-caching (<b>-W</b>) or security features, can lead to significant performance degradation, data corruption, or render the drive inaccessible. Many of the older performance-tuning options (e.g., <b>-c</b>, <b>-d</b>, PIO modes) are less relevant or ignored by modern Linux kernels and hardware, as the kernel typically manages these optimally. Always exercise caution and consult the man page when modifying drive parameters.


title: PERFORMANCE DIAGNOSTICS
content:
The command <b>hdparm -tT <i>/dev/sdX</i></b> is commonly used for quick performance tests. <b>-T</b> measures cached reads (from the OS buffer), while <b>-t</b> measures direct device reads (from the physical disk), providing insight into both buffer and disk performance.


title: POWER MANAGEMENT
content:
Options such as <b>-S</b> (standby timeout), <b>-y</b> (force standby), <b>-Y</b> (force sleep), and <b>-B</b> (Advanced Power Management) are critical for managing drive power consumption and noise, particularly in laptops or energy-efficient systems.


title: ATA SECURITY FEATURES
content:
<b>hdparm</b> can interact with ATA security features built into drives. Options like <b>--security-freeze-lock</b> and <b>--user-master</b> (with <b>--pass</b>) allow for setting user/master passwords, locking, and securely erasing drives (via <b>security-erase</b> commands). These features provide hardware-level data protection and secure erasure capabilities.


title: HISTORY
content:
<b>hdparm</b> has been a fundamental utility in the Linux ecosystem since its early days, primarily developed to optimize performance and manage power for IDE/ATA hard drives. In the era of PIO (Programmed Input/Output) versus DMA (Direct Memory Access), <b>hdparm</b> was crucial for enabling faster DMA transfers. While its role in raw performance tuning has diminished with the advent of SATA and NVMe drives and more sophisticated kernel I/O schedulers, it remains indispensable for fine-tuning power management, accessing low-level device information, and managing ATA security features. Its evolution mirrors the advancements in storage technology within Linux.


title: PARAMETERS
content:
<b><b>-n</b> <I>NUM</I>, <b>--lines=</b><I>NUM</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output the first <I>NUM</I> lines instead of the default 10. If <I>NUM</I> is prefixed with a hyphen (e.g., <b>-n -20</b>), it outputs all but the last <I>NUM</I> lines (a GNU extension).<br><br><b><b>-c</b> <I>NUM</I>, <b>--bytes=</b><I>NUM</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output the first <I>NUM</I> bytes of each file. If <I>NUM</I> is prefixed with a hyphen (e.g., <b>-c -500</b>), it outputs all but the last <I>NUM</I> bytes (a GNU extension).<br><br><b><b>-q</b>, <b>--quiet</b>, <b>--silent</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Never print headers giving file names. This is useful when processing multiple files and only their combined content is desired, suppressing the default headers.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Always print headers giving file names. This is useful when processing a single file and a header is desired for clarity, even if it's not strictly necessary.<br><br><b><b>-z</b>, <b>--zero-terminated</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Line delimiter is NUL, not newline. This option is primarily used when piping output to commands like <b>xargs -0</b> to handle file names containing unusual characters or newlines.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output version information and exit.<br><br>


title: DESCRIPTION
content:
The <b>head</b> command is a fundamental Linux and Unix utility used to display the beginning of text files or piped input to standard output. By default, it outputs the first 10 lines of each specified file. When multiple files are provided, <b>head</b> conveniently prefixes each output block with a header indicating the file name.<br><br>Users can easily customize the number of lines or bytes to be displayed, making <b>head</b> incredibly useful for quickly previewing the content of large files, examining log files, or checking configuration files without needing to open the entire file. It is often employed in conjunction with other commands via pipes, serving as an initial filter to narrow down data for further processing. <b>head</b> is the conceptual inverse of the <b>tail</b> command, which displays the end of files.


title: CAVEATS
content:
When specifying a negative count (e.g., <b>-n -NUM</b> or <b>-c -NUM</b>), this functionality is a GNU Coreutils extension and may not be available on all Unix-like systems, which typically only support positive counts for <b>head</b>. Scripts relying on such features might lack portability. Additionally, outputting binary files directly to a terminal can result in garbled output or modify terminal settings, so caution is advised.


title: STANDARD VS. GNU EXTENSIONS
content:
It's important to note that while the basic functionality of <b>head</b> (displaying the first <I>N</I> lines or bytes) is POSIX standard, certain options like specifying negative line/byte counts (e.g., <b>-n -20</b>) and the <b>-z</b> option are GNU Coreutils extensions. This means scripts relying on these specific features might not be portable to non-GNU Unix systems.


title: PIPING AND FILTERING
content:
<b>head</b> is frequently used in shell pipelines to quickly inspect the output of other commands. For example, <code><I>long_command</I> | <b>head -n 5</b></code> will show only the first five lines of <code><I>long_command</I></code>'s output, making it an excellent tool for initial data exploration and debugging or to limit the amount of data processed by subsequent commands.


title: HISTORY
content:
The <b>head</b> command is a venerable utility, having been a standard component of Unix-like operating systems since their early versions. Its fundamental purpose—displaying the beginning of files—has remained consistent throughout its evolution. As part of the GNU Coreutils package, the GNU version of <b>head</b> has introduced several enhancements, such as the ability to specify negative line/byte counts (to exclude the end of a file) and the <b>--zero-terminated</b> option, expanding its utility beyond the POSIX standard specification.


title: PARAMETERS
content:
<b><i>-h</i>, <i>--help</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display help information for the command.<br><br><b><i>-v</i>, <i>--version</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the version of <i>helix</i>.<br><br><b><i>-c</i> <i><FILE></i>, <i>--config</i> <i><FILE></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an alternative configuration file path.<br><br><b><i>-s</i> <i><FILE></i>, <i>--session</i> <i><FILE></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a session file to load or save to.<br><br><b><i>-g</i> <i><DIR></i>, <i>--grammar</i> <i><DIR></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an additional directory for Tree-sitter grammars.<br><br><b><i>-t</i>, <i>--tutor</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Start the built-in interactive tutorial to learn basic commands.<br><br><b><i>--health</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run a health check to diagnose LSP and Tree-sitter configurations.<br><br><b><i>--diff</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Open files in diff mode to compare them side-by-side.<br><br><b><i>--merge</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Open files in merge mode to resolve conflicts.<br><br><b><i>--log</i> <i><FILE></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a file to write debug logs to.<br><br><b><i>--log-level</i> <i><LEVEL></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the verbosity level for logging (e.g., info, debug, trace).<br><br><b><i>--read-only</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Open files in read-only mode, preventing accidental modifications.<br><br><b><i>--no-auto-indent</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable automatic indentation.<br><br>


title: DESCRIPTION
content:
<i>helix</i> is a modern, modal terminal-based text editor, designed for efficiency and an enhanced coding experience. Inspired by editors like <i>Neovim</i> and <i>Kakoune</i>, it adopts a "select first, then operate" paradigm, which contrasts with traditional "operate first, then select" editors. Key features include built-in support for Language Server Protocol (LSP) for intelligent code completion, diagnostics, and navigation, and Tree-sitter for robust syntax highlighting and structural editing. <br><br><i>helix</i> aims for a zero-configuration experience for common programming languages, leveraging its deep LSP and Tree-sitter integration. It supports multiple selections natively, allowing powerful, simultaneous edits across different parts of a file. Its modal editing approach means different keyboard commands are active depending on the current mode (e.g., normal, insert, select), which can lead to very fast text manipulation once mastered. It's an excellent choice for developers seeking an IDE-like experience directly within their terminal.


title: CAVEATS
content:
<i>helix</i> is a terminal-based editor and requires a compatible terminal emulator (e.g., <i>Alacritty</i>, <i>Kitty</i>, <i>WezTerm</i>) for optimal display and keybinding support. Its modal editing paradigm has a learning curve for users accustomed to traditional text editors, though the built-in tutorial helps mitigate this. It is still under active development, so features and behavior may evolve. Unlike traditional Unix utilities, it's not typically pre-installed on most Linux distributions and needs to be installed separately.


title: MODES OF OPERATION
content:
<i>helix</i> operates in different modes: <b>Normal</b> for navigation and command execution; <b>Insert</b> for typing text; <b>Select</b> for selecting text and applying commands to the selection; and <b>Goto</b>, <b>Match</b>, <b>Search</b>, <b>Picker</b> modes for specific actions. Understanding these modes is fundamental to efficient use.


title: CONFIGURATION AND CUSTOMIZATION
content:
While <i>helix</i> aims for zero-config, it is highly customizable through a <i>TOML</i> configuration file (typically <i>~/.config/helix/config.toml</i>). Users can adjust keybindings, theme colors, editor behavior, and LSP settings to suit their preferences.


title: HISTORY
content:
<i>helix</i> emerged in late 2020 as a fresh take on terminal text editing, aiming to combine the efficiency of modal editors like <i>Vim</i> with modern features like Language Server Protocol (LSP) and Tree-sitter integration directly into its core, rather than relying on plugins. Its development prioritizes a 'zero-config' approach for common development tasks, reducing the setup burden often associated with highly customizable editors. It quickly gained traction among developers looking for a fast, feature-rich, and easy-to-configure terminal editor, evolving into a robust alternative to established editors.


title: PARAMETERS
content:
<b><I>-u</I> | <I>--universe</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Changes the default greeting from 'Hello, World!' to 'Hello, Universe!'. This option allows for a broader, more generic salutation, suitable for greeting a wider audience or concept.<br><br>


title: DESCRIPTION
content:
The <b>hello</b> command is <I>not a standard Linux command</I>. It is typically used as a pedagogical example for a first program or a simple shell script, often encountered in programming tutorials and introductory computer science courses. When created, its primary function is to print a greeting message, most commonly 'Hello, World!', to the standard output. Its exact behavior and available options are entirely dependent on how it is implemented by a user or system administrator, making it a highly customizable but non-universal utility. As it is not part of any standard Linux distribution, users wishing to utilize a 'hello' command must create it themselves, usually as a shell script leveraging core commands like <b>echo</b> or <b>printf</b> to achieve its output.


title: CAVEATS
content:
The <b>hello</b> command is <I>not pre-installed</I> on Linux systems. Its existence and behavior depend entirely on a user-defined implementation. There is no standard manual page (man page) for <b>hello</b>, and its features (options, arguments) can vary widely based on how it was scripted. Users should be aware that running an unknown 'hello' command might execute arbitrary code if it's not a simple greeting script, posing a potential security risk if sourced from untrusted locations.


title: CREATING YOUR OWN <B>HELLO</B> COMMAND
content:
To create a basic <b>hello</b> command that prints 'Hello, World!' or 'Hello, Universe!', you can create a simple shell script. For example, create a file named <I>hello</I> (without any file extension) in your home directory or a custom <I>bin</I> directory (e.g., <I>~/bin</I> or <I>~/.local/bin</I>) with the following content:<br><br><I>#!/bin/bash<br><br># Check if the first argument is -u or --universe<br>if [ "$1" = "-u" ] || [ "$1" = "--universe" ]; then<br>&nbsp;&nbsp;echo "Hello, Universe!"<br>else<br>&nbsp;&nbsp;echo "Hello, World!"<br>fi</I><br><br>After saving the file, make it executable: <I>chmod +x ~/bin/hello</I><br><br>Finally, ensure the directory containing your script (e.g., <I>~/bin</I>) is in your system's <I>PATH</I> environment variable for easy execution from any directory. You can add <I>export PATH=$PATH:~/bin</I> to your shell's configuration file (e.g., <I>~/.bashrc</I> or <I>~/.zshrc</I>) for persistence.


title: PURPOSE AND CUSTOMIZATION
content:
A user-defined <b>hello</b> command is primarily used as an educational tool for basic scripting, demonstrating concepts like command arguments, conditional logic, and standard output. However, its simplicity makes it highly adaptable. It can be customized to perform a wide array of actions, provide different outputs, interact with files, or even launch other programs, showcasing the fundamental principles of creating custom command-line utilities within a Linux environment.


title: HISTORY
content:
The concept of a 'hello' program, specifically 'Hello, World!', originates from early programming examples and tutorials. It is widely considered the simplest program that can be written in almost any programming language, demonstrating basic syntax and output functionality. Brian Kernighan's 1978 book 'The C Programming Language' popularized its use. In the context of Linux, while no official 'hello' command exists, it serves as a canonical example for teaching basic shell scripting, file permissions, and the PATH environment variable, representing the 'first steps' in creating one's own command-line utilities. Its ubiquity in learning materials has made it a de facto standard for testing new environments or languages.


title: SYNOPSIS
content:
<b>helm</b> <I>COMMAND</I> [<I>ARGUMENTS...</I>] [<I>OPTIONS...</I>]<br><br>Examples:<br><b>helm install</b> <I>NAME</I> <I>CHART</I> [<I>OPTIONS</I>]<br><b>helm upgrade</b> <I>NAME</I> <I>CHART</I> [<I>OPTIONS</I>]<br><b>helm uninstall</b> <I>NAME</I> [<I>OPTIONS</I>]<br><b>helm list</b> [<I>OPTIONS</I>]<br><b>helm repo</b> <I>SUBCOMMAND</I><br><b>helm search</b> <I>SUBCOMMAND</I>


title: PARAMETERS
content:
<b>--debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show help for a command.<br><br><b>--kube-context string</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Name of the kubeconfig context to use.<br><br><b>--namespace string</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Namespace scope for this request.<br><br><b>--set stringArray</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set values on the command line (e.g., 'key=value').<br><br><b>--values stringArray</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify values in a YAML file (can specify multiple).<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the version of Helm.<br><br><b>--dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Simulate an install or upgrade without making changes.<br><br>


title: DESCRIPTION
content:
Helm is the de facto package manager for Kubernetes, simplifying the deployment and management of applications. It uses "charts," which are packages of pre-configured Kubernetes resources. These charts allow users to define, install, and upgrade even complex Kubernetes applications efficiently. Helm streamlines the software delivery lifecycle on Kubernetes by providing versioning, dependency management, and templating capabilities. It helps manage the entire lifecycle of Kubernetes applications, from initial deployment to updates, rollbacks, and deletion, promoting reusability and best practices for application packaging.


title: CAVEATS
content:
Requires a functional Kubernetes cluster and 'kubectl' configured to connect to it.<br>Creating robust Helm charts can be complex, demanding a good understanding of Kubernetes resources and templating.<br>Managing Helm releases across diverse environments needs careful CI/CD integration to avoid configuration drift.<br>Always ensure charts are sourced from trusted repositories to mitigate security risks.


title: HELM CHARTS
content:
Helm Charts are a packaging format that bundles all necessary Kubernetes resources, templates, and configuration values needed to deploy an application. They serve as a standard, reusable unit for defining, installing, and managing applications on Kubernetes, simplifying complex deployments and promoting consistency.


title: RELEASE MANAGEMENT
content:
Helm manages "releases," which represent deployed instances of a chart on a Kubernetes cluster. It tracks the state and history of each release, enabling seamless operations like upgrades to newer versions, rollbacks to previous stable states, and viewing the complete lifecycle history, providing robust application lifecycle management.


title: HISTORY
content:
Helm was initially developed by Deis (now part of Microsoft) and later contributed to the Cloud Native Computing Foundation (CNCF) in 2016. It achieved CNCF graduated project status in 2020, indicating its maturity and widespread adoption. Helm 2, which included an in-cluster component called Tiller, was widely used. Helm 3, released in 2019, significantly simplified its architecture by removing Tiller, enhancing security and ease of use, marking a major evolution in its design and operational model.


title: SYNOPSIS
content:
<b>helm install</b> [<i>NAME</i>] [<i>CHART</i>] [<i>flags</i>]<br><br>Examples:<br><i>helm install my-nginx stable/nginx-ingress</i><br><i>helm install --generate-name my-app-chart ./my-app-directory</i><br><i>helm install -f custom-values.yaml my-database oci://myregistry/charts/postgresql</i>


title: PARAMETERS
content:
<b>[<i>NAME</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name for the new release. If omitted and <i>--generate-name</i> is not used, Helm will prompt for a name. It must be unique within the namespace.<br><br><b>[<i>CHART</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The chart to install. This can be a path to a chart directory, a `.tgz` archive, a URL to a chart, or a reference to a chart in a repository (e.g., 'repo/chart-name').<br><br><b><b>--dry-run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Simulate an install. Helm will render templates and show the output without actually deploying any resources to Kubernetes.<br><br><b><b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output for debugging purposes, showing detailed information during the installation process.<br><br><b><b>--namespace</b> <i>&lt;namespace&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Target Kubernetes namespace to deploy resources into. Defaults to the current kubectl context's namespace.<br><br><b><b>--create-namespace</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If set, the target namespace will be created during the installation if it does not already exist.<br><br><b><b>--version</b> <i>&lt;version&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the exact chart version to install when using charts from a repository.<br><br><b><b>--values</b> <i>&lt;file&gt;</i>, <b>-f</b> <i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify one or more YAML files containing values to override chart defaults. Multiple files are merged in order.<br><br><b><b>--set</b> <i>&lt;key=value&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set individual values on the command line. Can be specified multiple times for multiple values (e.g., `<b>--set</b> replicaCount=3,image.tag=latest`).<br><br><b><b>--set-string</b> <i>&lt;key=value&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set string values on the command line. Ensures values are treated as strings, useful for values that might otherwise be parsed as numbers or booleans.<br><br><b><b>--generate-name</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate a random, unique name for the release if `<i>NAME</i>` is not provided. Useful for ephemeral deployments or testing.<br><br><b><b>--wait</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Wait until all Kubernetes resources associated with the release are in a ready state before marking the installation as successful.<br><br><b><b>--timeout</b> <i>&lt;duration&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The maximum time to wait for Kubernetes resources to be ready when `<b>--wait</b>` is enabled. Defaults to 5 minutes (5m0s).<br><br><b><b>--atomic</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If set, and the installation fails for any reason, the release will be automatically uninstalled to prevent partial deployments.<br><br><b><b>--skip-crds</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If set, Custom Resource Definitions (CRDs) included within the chart will not be installed or updated by Helm.<br><br><b><b>--repo</b> <i>&lt;url&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the URL of the chart repository to use. This is an alternative to `helm repo add`.<br><br>


title: DESCRIPTION
content:
The `helm install` command is fundamental for deploying applications packaged as Helm charts onto a Kubernetes cluster. A Helm chart is a collection of files that describe a related set of Kubernetes resources, representing a single application or a component of a larger one. When you execute `helm install`, Helm takes the specified chart (which can be a local path, a chart from a configured repository, or a direct URL), processes its templates with any provided custom values, and then sends the resulting Kubernetes resource definitions to the Kubernetes API server for creation. This operation creates a new "release" in Kubernetes, which Helm tracks internally. This tracking enables future lifecycle management operations such as upgrades, rollbacks, and uninstallation of the deployed application. It is the initial step in bringing an application to life using Helm's package management capabilities. Customization is a key feature, allowing users to override default chart values using various flags like `<b>--set</b>` or by providing a custom values file with `<b>-f</b>` or `<b>--values</b>`.


title: CAVEATS
content:
Successful `helm install` execution requires a properly configured Kubernetes context (typically managed via `kubectl`) with sufficient RBAC permissions in the target cluster and namespace to create and manage the necessary resources. It's crucial to thoroughly review the chart's documentation and values, especially for production environments, to understand its resource requirements and potential impact. If a release with the specified `<i>NAME</i>` already exists, `helm install` will fail unless the `<b>--replace</b>` flag is used. However, for idempotent deployments or updates, `<b>helm upgrade --install</b>` is generally preferred as it handles both initial installation and subsequent upgrades gracefully.


title: COMMON USE CASES
content:
<i>helm install</i> is extensively used for deploying a wide range of applications and services on Kubernetes, including:<br>- <b>Databases:</b> PostgreSQL, MySQL, MongoDB.<br>- <b>Message Queues:</b> RabbitMQ, Apache Kafka.<br>- <b>Web Servers/Proxies:</b> Nginx, Apache HTTP Server.<br>- <b>Monitoring Stacks:</b> Prometheus, Grafana, Loki.<br>- <b>CI/CD Tools:</b> Jenkins, GitLab Runner.<br>- <b>Custom Applications:</b> Packaging and deploying your own proprietary applications consistently.


title: IDEMPOTENT DEPLOYMENTS
content:
While `helm install` is specifically for initial deployments, for workflows that require an operation to either install a new release or update an existing one (i.e., be idempotent), it is often more robust to use the `<b>helm upgrade --install</b>` command. This command will perform an `install` if the release does not already exist, or an `upgrade` if it does, streamlining your deployment scripts and CI/CD pipelines.


title: HISTORY
content:
Helm, widely recognized as the 'package manager for Kubernetes,' was initially developed by Deis (later acquired by Microsoft) and subsequently donated to the Cloud Native Computing Foundation (CNCF). The `helm install` command has always been a core part of its functionality. A pivotal architectural shift occurred with Helm v3, which saw the removal of the Tiller server-side component that was central to Helm v2. This change simplified the deployment process and significantly enhanced the security model by allowing `helm install` (and all other Helm commands) to interact directly with the Kubernetes API server, eliminating the need for a separate privileged Tiller deployment within the cluster.


title: PARAMETERS
content:
<b><B>-d</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a short description for each <I>pattern</I>.<br><br><b><B>-m</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the information in a format similar to a manual page.<br><br><b><B>-s</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display only a short synopsis for each <I>pattern</I>.<br><br><b><B>-t</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a list of all built-in commands for which help topics are available.<br><br>


title: DESCRIPTION
content:
The <I>help</I> command is a <B>Bash shell built-in</B> used to display information about other built-in commands. Unlike external utilities like <I>man</I> or <I>info</I>, which search for system-wide manual pages or info documents, <I>help</I> provides quick, concise documentation directly from the shell's internal data. This makes it particularly useful for understanding the syntax, options, and usage of commands that are integral parts of the Bash shell itself, such as <I>cd</I>, <I>echo</I>, <I>for</I>, <I>if</I>, or <I>read</I>. It's a convenient way for users to quickly look up command specifics without leaving the terminal or consulting external resources, streamlining the learning and debugging process within the shell environment.


title: CAVEATS
content:
<I>help</I> is a <B>Bash built-in command</B>, not an executable program found in the system's PATH. This means it only provides documentation for other Bash built-ins and not for external executables (like <I>ls</I> or <I>grep</I>). For external commands, users should consult <I>man</I> pages or <I>info</I> documents. Its availability and exact behavior are specific to Bash and may differ in other shells.


title: SOURCE OF DOCUMENTATION
content:
The information displayed by <I>help</I> is <B>hardcoded or embedded</B> directly within the Bash executable itself. This allows for very fast retrieval without disk I/O, contrasting with <I>man</I> which reads files from specific directories.


title: HISTORY
content:
The <I>help</I> command was developed as an integral part of the <B>GNU Bash shell</B> to provide users with immediate, context-sensitive documentation for its internal commands. Its design reflects the need for quick reference within the interactive shell environment, eliminating the overhead of external process calls to retrieve man pages. This functionality has been a staple of Bash for many years, evolving alongside the shell to ensure that built-in commands are well-documented and easily discoverable by users directly at the command line.


title: SYNOPSIS
content:
<b>help2man</b> [OPTIONS] <i>PROGRAM_NAME</i> [<i>PROGRAM_ARGUMENTS</i>]<br><br><i>Example:</i><br><b>help2man</b> -o mytool.1 ./mytool<br>This creates <i>mytool.1</i> by running <i>./mytool</i> and parsing its default help output.


title: PARAMETERS
content:
<b>-o <I>FILE</I>, --output=<I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Write the generated man page to <I>FILE</I> instead of standard output.<br><br><b>-n <I>NAME</I>, --name=<I>NAME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Override the program name used in the man page title.<br><br><b>-s <I>SECTION</I>, --section=<I>SECTION</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the manual section number (e.g., <b>1</b> for executables, <b>3</b> for library functions). Defaults to <b>1</b>.<br><br><b>-m <I>TEXT</I>, --manual=<I>TEXT</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the text for the manual header/footer line (e.g., 'GNU Tools').<br><br><b>-p <I>TEXT</I>, --pagemargin=<I>TEXT</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the text for the page margin line.<br><br><b>-L <I>LOCALE</I>, --locale=<I>LOCALE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the locale for output message parsing.<br><br><b>-i <I>FILE</I>, --include=<I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Include content from <I>FILE</I> verbatim into the man page (e.g., for AUTHORS, BUGS sections).<br><br><b>-I <I>FILE</I>, --exclude=<I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exclude options listed in <I>FILE</I> from the generated man page.<br><br><b>--source=<I>TEXT</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the source of the man page (e.g., 'GNU Coreutils').<br><br><b>--date=<I>DATE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the date of the man page. Uses current date by default.<br><br><b>--help-option=<I>STRING</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use <I>STRING</I> instead of <i>--help</i> to get the program's help output.<br><br><b>--usage-option=<I>STRING</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use <I>STRING</I> instead of <i>--usage</i> to get the program's usage output.<br><br><b>--version-option=<I>STRING</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use <I>STRING</I> instead of <i>--version</i> to get the program's version output.<br><br><b>--no-info</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress the standard 'Report bugs to...' information.<br><br><b>--warnings</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable warning messages during parsing regarding potential issues.<br><br>


title: DESCRIPTION
content:
<b>help2man</b> is a valuable utility for automating the creation of basic manual pages from a program's standard output, typically its <i>--help</i> or <i>--usage</i> message.<br><br>It parses this output to extract key information such as the program name, synopsis, description, and command-line options. By generating man pages directly from the help text, <b>help2man</b> helps developers maintain consistency between their program's runtime help and its official documentation, reducing the effort required to keep both synchronized. It is commonly used in Makefiles during software compilation to ensure that an up-to-date man page is always available alongside the executable. While effective for simple cases, its reliance on the help message's format means that complex or non-standard help outputs might require manual intervention or produce less ideal results.


title: CAVEATS
content:
<b>help2man</b>'s effectiveness is directly tied to the consistency and clarity of the target program's <i>--help</i> output.<br><br>Programs with non-standard, very brief, or overly complex help messages may result in incomplete or poorly formatted man pages. It is not designed to replace comprehensive, hand-written man pages that provide detailed examples, usage scenarios, or intricate explanations of options beyond what's available in a typical <i>--help</i> output. It's a tool for quick generation, not deep documentation.


title: INTEGRATION INTO BUILD SYSTEMS
content:
<b>help2man</b> is most effectively utilized within software build processes, such as Makefiles. A common pattern is to include a target that runs <b>help2man</b> against the newly compiled executable. This ensures that every build automatically generates or updates the man page, keeping it current with any changes in the program's <i>--help</i> output, thus streamlining documentation maintenance.


title: CUSTOM CONTENT AND SECTIONS
content:
While <b>help2man</b> excels at parsing help messages, it also provides mechanisms to include additional, custom content. The <i>-i</i> or <i>--include</i> option allows developers to inject pre-written text files (e.g., containing AUTHORS, BUGS, COPYRIGHT, or EXAMPLES sections) directly into the generated man page. This flexibility allows for richer documentation beyond what's present in a typical <i>--help</i> output.


title: HISTORY
content:
<b>help2man</b> was first developed by Carlo Wood in 1995. Its primary motivation was to automate and simplify the process of generating man pages for GNU tools, which often follow a consistent format for their <i>--help</i> output. Over the years, it has been maintained and integrated into various open-source projects' build systems, becoming a standard utility for maintaining synchronized command-line help and manual documentation with minimal developer effort.


title: PARAMETERS
content:
<b><I>FILE</I>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more paths to man pages or directories containing man pages to be indexed. If no files are specified, it may process based on the system's <B>MANPATH</B>.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output version information and exit.<br><br>


title: DESCRIPTION
content:
<I>helpztags</I> is an internal utility, part of the <B>man-db</B> package, primarily used to build and update the index files (often referred to as <B>whatis</B> databases) for system manual pages.<br><br>These index files are crucial for the functionality of commands like <B>apropos</B> and <B>whatis</B>, enabling them to quickly search and display short descriptions from the <I>NAME</I> section of man pages. <I>helpztags</I> scans specified directories or files, extracts the synopsis from each man page's <I>NAME</I> section, and compiles this information into a searchable database.<br><br>While it can be invoked directly, it's most commonly called by scripts like <B>makewhatis</B> or as part of the system's package management processes to ensure the <B>whatis</B> database remains current after man pages are installed or updated.


title: CAVEATS
content:
Users typically do not invoke <I>helpztags</I> directly. It is an internal component of the <B>man-db</B> system and is usually called by higher-level scripts like <B>makewhatis</B>.<br><br>Manually running it incorrectly or against an incomplete set of man pages can lead to an outdated or corrupted <B>whatis</B> database, impacting the functionality of <B>apropos</B> and <B>whatis</B> commands.


title: DATABASE LOCATION
content:
The index files generated by <I>helpztags</I> are typically stored in a system-specific cache directory, such as <B>/var/cache/man/whatis</B> or similar paths, depending on the distribution and configuration of the <B>man-db</B> package. These files are not meant for direct user interaction and their format is internal to the <B>man-db</B> system.


title: HISTORY
content:
<I>helpztags</I> is an integral part of the <B>man-db</B> project, which replaced the older <B>man</B> package on many Linux distributions. The <B>man-db</B> system introduced a database-driven approach to man page management, significantly improving the performance of searches via <B>apropos</B> and <B>whatis</B> by pre-indexing man pages. <I>helpztags</I> was developed as part of this effort to efficiently create and maintain these necessary index files, ensuring that the system's documentation remains readily searchable.


title: SYNOPSIS
content:
`heroku <I>COMMAND</I> [ARGS...]`<br>`heroku help [COMMAND]`<br><br>Examples:<br>`heroku login`<br>`heroku apps:create [APP_NAME]`<br>`heroku deploy`<br>`heroku logs --tail`<br><br>The `heroku` command typically requires a subcommand to perform an action.


title: PARAMETERS
content:
<b>--app <APP_NAME></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the Heroku application to operate on.<br><br><b>-a <APP_NAME></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shorthand for --app.<br><br><b>--remote <GIT_REMOTE></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the Git remote to use for the application.<br><br><b>-r <GIT_REMOTE></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shorthand for --remote.<br><br><b>--json</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output in JSON format (where applicable), useful for scripting.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the Heroku CLI version.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display help for the Heroku CLI or a specific command.<br><br><b>-h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shorthand for --help.<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output for debugging.<br><br><b>--debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable debug output for detailed troubleshooting, including HTTP requests.<br><br>


title: DESCRIPTION
content:
The `heroku` command is the official <I>Command Line Interface</I> (CLI) for interacting with the Heroku <I>Platform-as-a-Service</I> (PaaS). It empowers developers to manage their Heroku applications directly from the terminal, providing a powerful interface to the Heroku API. <br><br>With the Heroku CLI, users can perform a wide array of tasks, including creating new applications, deploying code, scaling dynos, configuring environment variables, managing databases, and inspecting application logs. It streamlines the development workflow by integrating common development practices like Git-based deployments and providing access to live application shells. <br><br>The CLI is highly extensible through a robust plugin architecture, allowing developers to add custom commands and integrate with other services. It serves as the primary tool for deploying, monitoring, and debugging applications hosted on the Heroku cloud platform, making complex cloud operations accessible through simple command-line invocations.


title: CAVEATS
content:
The `heroku` command is not a native Linux utility but a separately installed client-side application. It requires an active internet connection and a Heroku user account for most operations, as it interacts directly with the Heroku cloud platform's API. Functionality is entirely dependent on the Heroku service availability. Command syntax and available subcommands can be extensive and context-dependent, often requiring specific subcommand knowledge.


title: SUBCOMMANDS
content:
The `heroku` command acts as a dispatcher for hundreds of subcommands, each designed for specific tasks. Examples include `heroku apps` (to manage applications), `heroku ps` (to manage dynos/processes), `heroku config` (to manage environment variables), `heroku logs` (to stream application logs), and `heroku run` (to execute one-off commands).


title: PLUGINS
content:
The Heroku CLI is highly extensible through a plugin architecture. Users can install community-developed or custom plugins using `heroku plugins:install <plugin_name>` to add new commands or extend existing functionality, allowing for deep integration with specific workflows or third-party services.


title: AUTHENTICATION
content:
To use most `heroku` commands, you must first authenticate using `heroku login`. This command opens a browser for web-based authentication or prompts for credentials directly in the terminal, securely storing your session token locally.


title: HISTORY
content:
Heroku, Inc. was founded in 2007, pioneering the <I>Platform-as-a-Service</I> (PaaS) model. The Heroku CLI has been an integral part of its offering since early on, evolving significantly over time. Initially developed in Ruby, the CLI transitioned to a modern architecture primarily written in Node.js and Go to enhance performance, cross-platform compatibility, and maintainability. This shift allowed for a more robust and faster user experience, keeping pace with the rapid expansion of the Heroku platform and its features. It remains the primary, and often preferred, method for developers to programmatically interact with their Heroku applications.


title: PARAMETERS
content:
<b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Displays a summary of command-line options and exits.</i><br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Shows the HexChat version information and exits.</i><br><br><b>--minimize</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Starts HexChat minimized to the system tray or taskbar.</i><br><br><b>--existing</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>If an instance of HexChat is already running, opens a new tab or window within that instance.</i><br><br><b>--newinstance</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Forces HexChat to start a new instance, even if one is already running.</i><br><br><b>--configdir &lt;dir&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies an alternative directory for configuration files and plugins.</i><br><br><b>--portable</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Runs HexChat in portable mode, using the application's own directory for configuration.</i><br><br><b>[URI...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>One or more IRC URIs (e.g., <code>irc://server/channel</code>) to connect to on startup.</i><br><br>


title: DESCRIPTION
content:
HexChat is a free and open-source graphical <I>IRC (Internet Relay Chat)</I> client. It was developed as a fork of XChat, aiming to continue a fully open-source development path after XChat's Windows version became proprietary.<br><br>HexChat provides a user-friendly interface for connecting to multiple IRC networks, joining channels, and engaging in real-time text communication. It supports a wide array of features including <I>SSL encryption, proxy support, DCC (Direct Client-to-Client) transfers</I>, and a robust plugin system that allows extending functionality with Python, Perl, and other languages.<br><br>Designed for both casual users and power users, it offers tabbed windows, customizable themes, logging capabilities, and spell checking, ensuring a stable and versatile IRC experience across Linux, Windows, and macOS platforms.


title: CAVEATS
content:
Configuration files and user data for HexChat are typically stored in <code>~/.config/hexchat/</code> on Linux systems.<br><br>While highly compatible, plugins written for its predecessor, XChat, may not be directly compatible with HexChat due to API changes over time.


title: <B>PLUGINS AND SCRIPTING</B>
content:
HexChat boasts a powerful plugin system, supporting scripts and extensions written in various languages, most notably Python and Perl. This allows users to extend its functionality, automate tasks, and deeply customize its behavior to suit specific needs.


title: <B>CROSS-PLATFORM AVAILABILITY</B>
content:
Although commonly associated with Linux, HexChat is truly cross-platform. It provides a consistent and familiar IRC experience across Linux, Windows, and macOS, making it a versatile choice for users on different operating systems.


title: HISTORY
content:
HexChat was created as a fork of the popular <I>XChat IRC client</I> in 2010. The fork occurred after XChat's Windows version became proprietary, leading developers to ensure continued free and open-source development across all platforms. It quickly gained popularity as a spiritual successor, maintaining XChat's core features while adding improvements, bug fixes, and cross-platform consistency for Linux, macOS, and Windows users.


title: SYNOPSIS
content:
<b>hexo</b> <i>&lt;command&gt;</i> [<i>&lt;args&gt;</i>] [<i>&lt;options&gt;</i>]<br><br>Common commands include: <b>init</b>, <b>new</b>, <b>generate</b> (<i>g</i>), <b>server</b> (<i>s</i>), <b>deploy</b> (<i>d</i>), <b>clean</b>.


title: PARAMETERS
content:
<b>init [folder]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Initializes</i> a new Hexo project in the specified <i>folder</i>. If no folder is specified, it initializes in the current directory.<br><br><b>new <layout> <title></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Creates</i> a new post, page, draft, or photo with the specified <i>layout</i> (e.g., 'post', 'page') and <i>title</i>.<br><br><b>generate / g</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Generates</i> static HTML, CSS, and JavaScript files from your Hexo source content. This prepares your site for deployment.<br><br><b>server / s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Starts</i> a local development server, allowing you to preview your blog in a web browser before deployment. Useful for real-time changes.<br><br><b>deploy / d</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Deploys</i> the generated static files to a remote server or hosting service configured in your <b>_config.yml</b> file.<br><br><b>clean</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Cleans</i> the cache file (<b>db.json</b>) and the generated public files, useful for troubleshooting or before a fresh generation.<br><br><b>version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Displays</i> the current Hexo version along with Node.js and npm versions.<br><br>


title: DESCRIPTION
content:
Hexo is an open-source, <b>Node.js-based</b> static site generator primarily designed for creating and managing blogs. It allows users to write content in <i>Markdown</i>, generate static HTML files, and deploy them easily to various hosting services.<br><br>Known for its speed and simplicity, Hexo takes plain text files (e.g., Markdown for posts, YAML for configuration) and transforms them into a complete, ready-to-deploy website. It automates common blogging tasks such as generating archives, categories, tags, and permalinks. Its extensibility through a rich ecosystem of themes and plugins makes it a popular choice for developers looking for a lightweight yet powerful blogging solution.


title: CAVEATS
content:
Hexo requires <b>Node.js</b> and <b>npm</b> (Node Package Manager) to be installed on your system. It is not a native Linux command or a pre-installed utility; it must be installed via npm (e.g., <i>npm install -g hexo-cli</i>).


title: THEMES AND PLUGINS
content:
Hexo boasts a rich ecosystem of community-contributed <b>themes</b> for customizing the look and feel, and <b>plugins</b> for extending functionality (e.g., SEO, sitemaps, analytics, deployment methods).


title: MARKDOWN SUPPORT
content:
Content creation in Hexo is primarily done using <b>Markdown</b>, making it easy and intuitive to write blog posts and pages without needing to write raw HTML.


title: HISTORY
content:
Hexo was created by <b>Tommy Chen</b> and first released around 2012-2013. It quickly gained popularity within the Node.js community for its focus on speed, simplicity, and its ability to leverage Node.js for static site generation, providing an alternative to Ruby-based generators like Jekyll.


title: PARAMETERS
content:
<b><b>-n</b>, <b>--length</b> <i>&lt;NUM&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limits the output to the first <i>NUM</i> bytes of the input file(s). This is useful for quickly inspecting the beginning of large files.<br><br><b><b>-o</b>, <b>--offset</b> <i>&lt;NUM&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts reading from <i>NUM</i> bytes into the file. This allows you to skip a specific number of bytes from the beginning and view content from a particular offset.<br><br><b><b>-s</b>, <b>--color-scheme</b> <i>&lt;SCHEME&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the color scheme for the output. Available schemes typically include '<i>dark</i>' and '<i>light</i>', optimizing readability based on your terminal background.<br><br><b><b>--no-color</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables all colored output. The bytes will be displayed in plain terminal colors, which can be useful for terminals that don't support true color or for scripting purposes.<br><br><b><b>--raw</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs only the raw hexadecimal bytes and their ASCII/UTF-8 representation, without the address column or vertical separators. This provides a more compact view.<br><br><b><b>--endianness</b> <i>&lt;ENDIANNESS&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays data with the specified endianness. Options are '<i>little</i>' or '<i>big</i>'. The default is typically '<i>big</i>-endian'.<br><br><b><b>--no-pretty</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables pretty printing, which means byte groups (e.g., 2 bytes) are not separated by spaces. This results in a more compact, continuous hex stream.<br><br>


title: DESCRIPTION
content:
<i>hexyl</i> is a powerful command-line utility for viewing and inspecting binary files in hexadecimal format. It aims to be a modern, user-friendly alternative to traditional tools like <i>hexdump</i> and <i>xxd</i>, offering enhanced readability through intelligent colorized output and an intuitive interface. <i>hexyl</i> displays bytes in hexadecimal on the left, an ASCII/UTF-8 representation on the right, and provides an offset column in the middle. Its key features include intelligent colorization to highlight different byte types (e.g., printable ASCII, non-printable, null bytes), efficient handling of large files, and a responsive experience. It's particularly useful for debugging, reverse engineering, and low-level file analysis where understanding byte-level data is crucial. Unlike simple hex dumps, <i>hexyl</i>'s visual cues help quickly identify patterns and anomalies in binary data.


title: CAVEATS
content:
<i>hexyl</i> is primarily a hex <b>viewer</b>, not an editor; it cannot modify files directly. While efficient, very large files might still lead to higher memory usage depending on internal buffering. Its rich color output requires a terminal that supports true colors for the best visual experience.


title: INTELLIGENT COLORIZATION
content:
One of <i>hexyl</i>'s most significant features is its sophisticated colorization scheme. It automatically assigns different colors to various byte types, such as printable ASCII characters, non-printable control characters, null bytes, whitespace, and invalid UTF-8 sequences. This visual distinction dramatically improves the readability of binary data and helps in quickly identifying specific data patterns or anomalies within a file.


title: PERFORMANCE AND EFFICIENCY
content:
Written in <b>Rust</b>, <i>hexyl</i> is designed with performance in mind. It handles large files efficiently, offering a responsive user experience even when dealing with gigabytes of binary data. Its optimized parsing and rendering routines ensure quick display of hex dumps without significant lag, making it suitable for professional analysis workflows.


title: HISTORY
content:
<i>hexyl</i> was created by <b>Daniel P. Schroeder</b> (<i>@sharkdp</i>), a prominent developer known for several highly-regarded command-line tools written in Rust (e.g., <i>fd</i>, <i>bat</i>). It emerged around 2018 as a modern, visually superior alternative to traditional hex viewing utilities like <i>hexdump</i> and <i>xxd</i>, addressing their often verbose and less readable output. Its development focused on providing intelligent default behaviors and a highly performant, user-friendly experience.


title: PARAMETERS
content:
<b><B>--help</B>, <B>-h</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show help message for a command or global options.<br><br><b><B>--verbose</B>, <B>-v</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output, showing more details of operations.<br><br><b><B>--quiet</B>, <B>-q</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress output, showing only critical messages.<br><br><b><B>--repository</B> <I>REPO</I>, <B>-R</B> <I>REPO</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Operate on the specified repository instead of the current working directory's repository.<br><br><b><B>--config</B> <I>SECTION.NAME=VALUE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set or override a configuration option for the current command execution.<br><br><b><B>--cwd</B> <I>DIR</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run the command as if the current working directory were <I>DIR</I>.<br><br><b><B>--noninteractive</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable interactive prompts, useful for scripting.<br><br><b><B>--version</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show Mercurial version information and exit.<br><br>


title: DESCRIPTION
content:
<I>hg</I> is the command-line interface for <B>Mercurial</B>, a powerful, distributed revision control system (DVCS). Designed for speed and scalability, Mercurial efficiently manages source code and tracks changes in projects of any size.<br>It allows developers to maintain local repositories, providing full history and enabling offline work. Key features include robust branching and merging capabilities, strong data integrity, and a user-friendly command set. It supports various development workflows, from centralized to fully distributed, and is often praised for its simplicity and clear command structure compared to other DVCS tools. Written primarily in Python, <I>hg</I> provides a reliable and flexible solution for version control, widely used in open-source and commercial projects.


title: CAVEATS
content:
Mercurial commands are numerous and context-dependent; each subcommand (e.g., <I>clone</I>, <I>commit</I>, <I>pull</I>) possesses its own set of unique options and arguments, which are not exhaustively listed here. Users should consult <B><I>hg help &lt;command&gt;</I></B> for specific command details. While generally user-friendly, understanding core distributed version control concepts is beneficial for effective use. Mercurial's strong emphasis on repository integrity means some operations might seem more restrictive compared to other DVCS tools.


title: KEY CONCEPTS & WORKFLOWS
content:
Mercurial operates on a <B>distributed</B> model, where every clone is a full repository. Common workflows include <B>cloning</B> (<I>hg clone</I>), <B>pulling</B> changes from others (<I>hg pull</I>), <B>updating</B> your working copy (<I>hg update</I>), <B>committing</B> local changes (<I>hg commit</I>), and <B>pushing</B> changes to other repositories (<I>hg push</I>). It provides powerful tools for <B>branching</B> (named branches, bookmarks) and <B>merging</B> changesets. Extensions (<I>hg help extensions</I>) significantly expand its functionality, offering features like rebase, largefiles support, and more.


title: HISTORY
content:
Mercurial was created by <B>Matt Mackall</B> in <B>2005</B>, primarily as a free and open-source alternative to BitKeeper, following changes in its licensing model that affected the Linux kernel development. Developed mainly in <B>Python</B>, with performance-critical parts in C, it quickly gained popularity as a robust and scalable distributed version control system. Its development emphasized simplicity, strong data integrity, and efficient handling of large repositories, leading to its adoption by significant projects like <B>Mozilla</B> for Firefox development and previously <B>OpenSolaris</B>. Mercurial continues to be actively maintained and used, offering a reliable choice for version control.


title: PARAMETERS
content:
<b>[FILE | DIRECTORY]...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies individual files or directories to add. If a directory is provided, all new files and subdirectories within it are added recursively.<br><br><b>--all, -A</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds all untracked files in the current repository. This option also automatically marks missing files for removal (equivalent to <b>hg rm</b>).<br><br><b>--include PATTERN, -I PATTERN</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes names matching the given pattern. Can be specified multiple times.<br><br><b>--exclude PATTERN, -X PATTERN</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Excludes names matching the given pattern. Can be specified multiple times.<br><br><b>--subrepos, -S</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Operates on untracked subrepositories, adding them to the parent repository's tracking.<br><br><b>--dry-run, -n</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays what files would be added without actually performing the operation.<br><br>


title: DESCRIPTION
content:
The <b>hg add</b> command marks one or more files or directories for inclusion in the Mercurial repository's tracking system. When new files are created within a repository, Mercurial does not automatically track them. You must explicitly tell Mercurial to start tracking these files using <b>hg add</b>. Once added, the files are staged for the next commit. This command does not modify the repository history directly; it merely prepares the files for the subsequent <b>hg commit</b> operation. It's crucial for bringing new content under version control, allowing Mercurial to monitor changes and enable future operations like branching, merging, and reverting. It's a core command for any new content.


title: CAVEATS
content:
Files are not committed immediately; a subsequent <b>hg commit</b> is required to save changes to the repository history.<br><b>hg add</b> only tracks <i>new</i> files; to track modifications to existing files, simply make changes and then <b>hg commit</b> them.<br>Using <b>--all</b> can also stage files for removal if they are tracked but missing from the working directory, which might be an unintended side effect if not carefully used.


title: ADDING MULTIPLE FILES
content:
You can add multiple files by listing them individually (e.g., <b>hg add file1.txt file2.txt</b>) or by specifying a directory (e.g., <b>hg add mydir/</b>).<br>The <b>--all</b> option is a convenient shortcut for adding all newly created files in a project without specifying each one.


title: IGNORING FILES
content:
Before using <b>hg add</b>, it's often useful to configure a <b>.hgignore</b> file. This file specifies patterns for files and directories that Mercurial should ignore, preventing them from being listed as untracked or accidentally added to the repository. Files matched by <b>.hgignore</b> are not considered by <b>hg add --all</b>.


title: HISTORY
content:
<b>hg add</b> is a fundamental command in Mercurial, a distributed version control system created by Matt Mackall in 2005 as an alternative to BitKeeper. It has been a core part of Mercurial's workflow since its inception, mirroring similar functionality found in other VCS like Git's <b>git add</b>. Its design reflects Mercurial's philosophy of explicit action for version control operations, requiring users to explicitly stage new files before committing them to the repository.


title: PARAMETERS
content:
<b><I>NAME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the branch to set for the next commit. If provided, the branch name for subsequent commits (until changed again) will be set to <I>NAME</I>. If omitted, the command displays the name of the current active branch.<br><br><b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows setting a branch name even if a branch with the same name already exists. When used with <I>NAME</I>, it bypasses warnings if the name duplicates an existing branch. It is also implied when using <I>--rev</I> to set a branch.<br><br><b><b>-C</b>, <b>--close-branch</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Marks the current branch as closed. Closed branches are still part of the repository history but are typically filtered out by default when displaying active branches, signifying that no further development is expected on them.<br><br><b><b>--rev</b> <I>REV</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Operates on a specific revision <I>REV</I>. When used to set a branch, it applies the branch name to the specified revision. This option implies <I>--force</I> if setting a new branch.<br><br>


title: DESCRIPTION
content:
The <I>hg branch</I> command is a core utility within the <I>Mercurial (hg)</I> Distributed Version Control System. It allows users to interact with named branches, which are persistent lines of development tracked within a repository. This command serves three primary purposes: showing the current active branch, setting the name of the branch for the next commit, and marking the current branch as closed. Unlike anonymous branches (which are implicit and created by multiple heads), named branches are explicitly declared and visible in the repository history, providing a way to organize different development efforts or releases.<br><br>It's crucial to note that this is a Mercurial-specific command and not a native Linux command, though it is commonly used on Linux systems with Mercurial installed.


title: CAVEATS
content:
The <I>hg branch</I> command is part of the <I>Mercurial (hg)</I> Distributed Version Control System, not a standalone Linux utility. It requires Mercurial to be installed on the system to function. When setting a new branch name, the change only takes effect for subsequent commits; it does not alter the history of previous commits. Closing a branch marks it as inactive but does not delete its history from the repository. Named branches are persistent; they are part of the repository's metadata and are propagated during pushes and pulls.


title: BRANCHING MODEL
content:
Mercurial's named branches are persistent and global to the repository. Unlike lightweight branches in some other VCS, closing a named branch prevents new commits on it but doesn't remove its history. New work typically starts on a new named branch. This model emphasizes clear, long-lived development lines.


title: BEST PRACTICES
content:
It's common practice to use a unique named branch for each significant feature or release line. Once a feature is merged or a release is finalized, the branch can be closed to signify its completion, keeping the list of active branches manageable.


title: HISTORY
content:
Mercurial, created by Matt Mackall, emerged in 2005 as a distributed version control system, primarily written in Python. It was designed as a free, open-source alternative to proprietary systems like BitKeeper. The concept of named branches, which <I>hg branch</I> manages, has been a fundamental feature of Mercurial since its early days, providing a robust way to manage parallel lines of development within a repository. This contrasts with some other VCS where branches might be more lightweight or managed differently (e.g., Git's explicit branch pointers).


title: PARAMETERS
content:
<b><b>SOURCE</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Path or URL of the repository to clone.</i><br><br><b><b>DEST</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Optional path for the new repository. If omitted, the last component of the SOURCE path/URL is used.</i><br><br><b><b>-r &lt;REVISION&gt;</b>, <b>--rev &lt;REVISION&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Clone only up to the specified revision, limiting the history copied to the new repository.</i><br><br><b><b>-U</b>, <b>--noupdate</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Do not update the working directory after cloning. Only the .hg repository data is created.</i><br><br><b><b>-u &lt;UPDATE&gt;</b>, <b>--updaterev &lt;UPDATE&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Update the working directory to the specified revision after cloning.</i><br><br><b><b>--pull</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Pull all changesets into the new repository but do not update the working directory. Similar to 'hg init' followed by 'hg pull'.</i><br><br><b><b>--uncompressed</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Store cloned data uncompressed in the new repository. This can result in larger disk usage but may offer performance benefits in some scenarios.</i><br><br><b><b>--stream</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Use the stream clone protocol if supported by the server. This can significantly speed up cloning of large repositories.</i><br><br><b><b>--insecure</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Do not verify SSL certificates when connecting to HTTPS repositories. Use with extreme caution as it bypasses security checks.</i><br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Enable verbose output, showing more details about the cloning process.</i><br><br><b><b>-q</b>, <b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Suppress output, making the command execute silently.</i><br><br>


title: DESCRIPTION
content:
The `hg clone` command creates a complete, independent copy of an existing Mercurial repository. This includes the entire history of the source repository, encompassing all changesets, branches, and tags. It is a fundamental operation in distributed version control workflows, enabling developers to obtain a local, working copy of a project to contribute to or work with independently. The newly cloned repository retains a link to its original source, facilitating subsequent `pull` and `push` operations to synchronize changes. <br><br>Cloning can be performed from various sources, including local file paths or remote URLs using protocols like HTTP, HTTPS, or SSH. By default, `hg clone` not only copies the repository data but also checks out the latest revision (tip of the default branch) into a working directory. This allows immediate interaction with the project files. Options are available to modify this behavior, such as cloning only the repository contents without updating the working directory, or specifying a particular revision to update to.


title: CAVEATS
content:
Cloning large repositories can consume significant disk space and network bandwidth, potentially taking a long time. <br>The <b>--insecure</b> option should be used with extreme caution, as it disables crucial SSL certificate verification, making your connection vulnerable to man-in-the-middle attacks. <br>Using <b>-r</b> to clone a specific revision limits the history copied into the new repository; the new repository will not contain changesets beyond that revision. To get the full history but update the working directory to an older revision, use <b>-u</b> instead.


title: DEFAULT BEHAVIOR
content:
By default, `hg clone` copies the entire history of the source repository and updates the working directory in the new repository to the tip (latest revision) of the default branch. This provides an immediately usable local copy of the project.


title: PROTOCOL SUPPORT
content:
Mercurial's `clone` command supports various protocols for source repositories, including local file paths, `http://`, `https://`, `ssh://`, and `file://`. This flexibility allows cloning from diverse network locations and local file systems.


title: REPOSITORY HOOKS
content:
Clone operations can trigger specific hooks. The source repository can execute a `pre-clone` hook before the cloning process begins, and the destination (newly created) repository can execute a `post-clone` hook after the cloning is complete. These allow for custom automation around cloning events.


title: HISTORY
content:
The `clone` command has been a foundational element of Mercurial (hg) since its inception in 2005. Developed by Matt Mackall, Mercurial, much like Git, emerged from the need for an open-source distributed version control system. The `clone` operation was critical from day one to support Mercurial's distributed architecture, allowing developers to easily create local copies of repositories. While its core functionality has remained consistent, performance enhancements, such as the introduction of stream clones, and robust protocol handling have been integrated over time to improve its efficiency and reliability.


title: PARAMETERS
content:
<b>-m <I>MESSAGE</I>, --message <I>MESSAGE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use the specified <I>MESSAGE</I> as the commit description. If this option is not provided, an editor will be opened for message entry.<br><br><b>-l <I>FILE</I>, --logfile <I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Read the commit message from the specified <I>FILE</I>.<br><br><b>-A, --addremove</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Automatically mark all unknown files as added and all missing files as removed before committing. This simplifies committing all changes.<br><br><b>-I <I>PATTERN</I>, --include <I>PATTERN</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Include only files matching the given <I>PATTERN</I>. This option can be used multiple times.<br><br><b>-X <I>PATTERN</I>, --exclude <I>PATTERN</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exclude files matching the given <I>PATTERN</I> from the commit. This option can be used multiple times.<br><br><b>-S, --subrepos</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Recurse into subrepositories and commit their changes as well. This is useful for projects with nested Mercurial repositories.<br><br><b>-U, --amend</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Amend the previous commit, meaning the current changes will modify the most recent changeset instead of creating a new one. Use with caution, especially after pushing changes to shared repositories.<br><br><b>-d <I>DATE</I>, --date <I>DATE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the date of the commit to the specified <I>DATE</I>. This is typically used for historical commits or specific workflow requirements.<br><br><b>-u <I>USER</I>, --user <I>USER</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the author of the commit to the specified <I>USER</I>. This overrides the configured user name.<br><br><b>-f, --force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the commit operation, bypassing some warnings or checks.<br><br><b>-e, --edit</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Always invoke the editor for the commit message, even if <b>--message</b> or <b>--logfile</b> is provided. Useful for reviewing or adding to a predefined message.<br><br><b>-n, --dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not commit changes, but instead show what files would be committed. Useful for verifying the commit scope.<br><br>


title: DESCRIPTION
content:
The <b>hg-commit</b> command is a fundamental operation in Mercurial, a distributed version control system. It is used to record changes from the working directory into the repository as a new <i>changeset</i>. A changeset represents a snapshot of the project at a specific point in time and contains the modifications made since the previous commit.<br><br>When executed, <b>hg-commit</b> examines the working directory for modified, added, or removed files. By default, if no specific files are provided, it commits all tracked changes. If untracked files are present, they are not committed unless explicitly added (e.g., via <b>hg add</b> or the <b>--addremove</b> option). The command typically opens a text editor for you to compose a commit message, which describes the changes being committed. This message is crucial for understanding the history of the project.


title: CAVEATS
content:
Using the <b>--amend</b> option (`-U`) modifies repository history. This should be done with extreme caution, especially if the changeset has already been shared with other developers or pushed to a public repository, as it can cause conflicts and confusion during future synchronizations.<br><br>Mercurial, like other DVCS, can store large binary files. However, committing large files repeatedly without using extensions like <i>largefiles</i> can significantly increase the repository's size and performance overhead for cloning and updating, potentially making operations slow.


title: COMMIT MESSAGES
content:
A well-crafted commit message is vital for project maintainability and collaboration. It should clearly explain <i>what</i> changes were made and <i>why</i> they were made. Mercurial's default behavior of opening an editor encourages descriptive messages. A common convention is a concise single-line summary (often under 50-72 characters) followed by a blank line and then a more detailed explanation, typically wrapped at 72-80 characters.


title: IGNORING FILES
content:
Files that should not be tracked by Mercurial (e.g., build artifacts, temporary files, personal IDE settings, sensitive configurations) can be specified in a <i>.hgignore</i> file. This file uses pattern matching to prevent these files from appearing in <b>hg status</b> output and from being accidentally committed, keeping the repository clean and focused on source code.


title: HISTORY
content:
<b>hg-commit</b> is a core command of Mercurial, a distributed revision control system that originated in 2005. Developed primarily by Matt Mackall, Mercurial was created as a fast, lightweight alternative to older, centralized version control systems, largely in response to BitKeeper's licensing changes. The <b>commit</b> command is central to its workflow, allowing users to bundle discrete changes into atomic units (changesets) that form the project's history. Its design mirrors similar commands in other DVCS like Git, emphasizing local commits before sharing with others.


title: PARAMETERS
content:
<b>DESTINATION</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the directory where the new Mercurial repository should be initialized. If omitted, the current working directory will be used. If the directory does not exist, <b>hg init</b> will attempt to create it.<br><br><b><b>--cwd</b> <I>DIR</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run as if current working directory was <I>DIR</I>. This is a global Mercurial option that affects where the command is executed.<br><br><b><b>--config</b> <I>SECTION.NAME=VALUE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set a configuration option for this command execution. This can be used to set initial repository configurations (e.g., hooks) immediately upon creation, though often not necessary for <b>init</b>.<br><br><b><b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable debug output. Provides more detailed information on the command's execution, useful for troubleshooting.<br><br><b><b>--verbose</b>, <b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output. Displays more information about what the command is doing.<br><br>


title: DESCRIPTION
content:
The <b>hg init</b> command is used to create a new, empty Mercurial repository. When executed, it sets up the necessary directory structure for Mercurial to track changes within a project. This involves creating a hidden directory named <I>.hg</I> at the specified <I>DESTINATION</I> (or in the current working directory if no <I>DESTINATION</I> is provided). The <I>.hg</I> directory is the core of the repository, containing all revision history, metadata, configuration files, and other internal data that Mercurial uses to manage the project's versions.<br><br>Running <b>hg init</b> is typically the very first step when starting a new project that you intend to manage with Mercurial. It does not add any existing files from the working directory to the repository; subsequent commands like <b>hg add</b> and <b>hg commit</b> are required for that.


title: CAVEATS
content:
Running <b>hg init</b> in a directory that is already a Mercurial repository (i.e., it already contains a <I>.hg</I> directory) will typically result in a message indicating the repository already exists and will not re-initialize or corrupt the existing repository data.<br>The command only creates the <I>.hg</I> directory; it does not automatically add any existing files from the working directory into version control. Files must be explicitly added using <b>hg add</b> and then committed with <b>hg commit</b>.<br><b>hg init</b> creates an empty repository. No branches, tags, or changesets exist until the first commit is made.


title: FIRST STEPS AFTER INITIALIZATION
content:
After running <b>hg init</b>, your project directory is now a Mercurial repository. To start tracking files, you would typically use:<br><code>hg add .</code> (to add all current files to be tracked)<br><code>hg commit -m "Initial commit"</code> (to save the first version of your files)


title: CONTENTS OF THE <I>.HG</I> DIRECTORY
content:
The <I>.hg</I> directory is crucial for Mercurial's operation. It contains:<br><I>store/</I>: The changelog, manifests, and file data (deltas).<br><I>dirstate</I>: Information about the working directory's state.<br><I>hgrc</I>: The local repository configuration file.<br><I>hooks/</I>: Directory for repository hooks.<br>And other internal files used by Mercurial.


title: HISTORY
content:
Mercurial was developed by Matt Mackall starting in April 2005, primarily as a response to the licensing changes of BitKeeper, which had been used for Linux kernel development. The <b>hg init</b> command has been a foundational part of Mercurial since its early development. Its core functionality—creating a new, empty repository—has remained remarkably consistent throughout Mercurial's history, reflecting its role as the essential starting point for any new project under Mercurial version control.


title: PARAMETERS
content:
<b><b>-r</b> <i>REV</i>, <b>--rev</b> <i>REV</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show changesets specified by a revision or revset (e.g., a branch name, tag, or specific hash). This is a powerful way to filter history.<br><br><b><b>-l</b> <i>N</i>, <b>--limit</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limit the number of changesets displayed to the first <i>N</i> entries.<br><br><b><b>-u</b> <i>USER</i>, <b>--user</b> <i>USER</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show only changesets committed by the specified <i>USER</i> (can be a username or email address).<br><br><b><b>-d</b> <i>DATE</i>, <b>--date</b> <i>DATE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show changesets committed on or after/before a specific <i>DATE</i> or within a date range (e.g., '2023-01-01 to 2023-01-31').<br><br><b><b>-k</b> <i>TEXT</i>, <b>--keyword</b> <i>TEXT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show changesets whose commit message, author, or description contains the specified <i>TEXT</i>.<br><br><b><b>-m</b> <i>TEXT</i>, <b>--message</b> <i>TEXT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show changesets whose commit message contains the specified <i>TEXT</i>.<br><br><b><b>-P</b>, <b>--patch</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Include the patch (diff) for each changeset in the output. Useful for quickly seeing what changed.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show more details, such as affected files, parents, and branches for each changeset.<br><br><b><b>-G</b>, <b>--graph</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Draw an ASCII art revision graph alongside the changesets, illustrating branch and merge history.<br><br><b><b>-T</b> <i>TEMPLATE</i>, <b>--template</b> <i>TEMPLATE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use a custom template string to format the output of each changeset, allowing for highly flexible display.<br><br><b><b>--follow</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When applied to specific files, follow file history across copies and renames. Useful for understanding a file's full lineage.<br><br><b><b>--style</b> <i>STYLE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use a named style definition for formatting the output, providing predefined templates.<br><br><b><b>--branch</b> <i>BRANCH</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show changesets belonging only to the specified <i>BRANCH</i>.<br><br>


title: DESCRIPTION
content:
The <b>hg log</b> command displays the complete revision history of a Mercurial repository, or a filtered subset of it. It is a fundamental tool for understanding changes over time, who made them, when, and what was changed. By default, <b>hg log</b> shows all changesets in the current branch, ordered from newest to oldest, including the changeset hash, author, date, and commit message. Users can apply various filters to narrow down the displayed history, such as by specific files, authors, dates, or messages. The command also supports advanced formatting options, allowing users to customize the output extensively for specific analysis needs. It's an essential utility for tracing bugs, reviewing code, and understanding project evolution.


title: CAVEATS
content:
For very large repositories or histories, running <b>hg log</b> without specific filters (like <b>--limit</b> or <b>--rev</b>) can consume significant time and resources as it processes the entire history. The use of complex <I>revsets</I> or <I>templates</I> might require some familiarity with Mercurial's internal data structures and query language.


title: REVSETS
content:
<I>Revsets</I> are Mercurial's powerful query language for selecting changesets. They allow users to specify complex conditions to filter history based on parent-child relationships, dates, authors, branches, and more. For example, <b>hg log -r 'branch(default) and ancestors(.)'</b> shows all changesets on the 'default' branch up to the current revision. Mastering revsets significantly enhances the utility of <b>hg log</b>.


title: CUSTOM TEMPLATES
content:
The <b>--template</b> option allows users to define custom output formats using a mini-language. This can be used to extract specific information from each changeset (e.g., just the author and hash), or to format the log entries for integration with other tools. This flexibility makes <b>hg log</b> highly adaptable to various scripting and reporting needs beyond simple console viewing.


title: HISTORY
content:
The <b>hg log</b> command has been a core component of Mercurial (<b>hg</b>) since its early days, designed to provide efficient and detailed revision history in a distributed version control environment. Its capabilities have evolved with Mercurial itself, particularly with the introduction and enhancement of <I>revsets</I> and flexible output <I>templates</I>, making it a powerful and indispensable tool for developers managing changes.


title: SYNOPSIS
content:
<b>hg pull</b> [<i>OPTION</i>]... [<i>SOURCE</i>]<br><b>hg pull</b> [<i>OPTION</i>]... --force --uncompressed


title: PARAMETERS
content:
<b><b>-u</b>, <b>--update</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Update the working directory to the tip of the new branch after pulling. This is equivalent to running <b>hg update</b> after the pull.<br><br><b><b>-r</b>, <b>--rev</b> <i>&lt;REV&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pull only a specific revision or branch. Can be specified multiple times to pull a set of revisions.<br><br><b><b>-b</b>, <b>--branch</b> <i>&lt;BRANCH&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pull only a specific named branch. Can be specified multiple times to pull a set of branches.<br><br><b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the pull operation, even if incoming changes conflict or the remote repository's history is unrelated to the local one. Use with caution.<br><br><b><b>--no-update</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevent updating the working directory, overriding any configured automatic update behavior (e.g., from <b>hg fetch</b> aliases).<br><br><b><b>--uncompressed</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Bypass zlib compression during data transfer, useful for debugging or specific network conditions where compression is detrimental.<br><br><b><b>--insecure</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allow connections to repositories that offer only insecure (non-TLS, non-SSH) access, often for debugging or testing purposes.<br><br><b><b>--ssh</b> <i>&lt;CMD&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the SSH command to use for secure remote connections, overriding the default or configured SSH client.<br><br><b><b>--remotecmd</b> <i>&lt;CMD&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the command to run on the remote side for communication, usually for advanced server configurations.<br><br><b><b>--repository</b> <i>&lt;PATH&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the remote repository path. This is an alias for the <i>SOURCE</i> argument.<br><br><b><b>--bookmarks</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly pull bookmarks along with changesets. This is often the default behavior but can be useful for clarity.<br><br><b><b>--tool</b> <i>&lt;TOOL&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use a specific merge tool if conflicts arise during an update that is performed automatically by <b>hg pull -u</b>.<br><br><b><b>--dry-run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform a simulated pull operation and report what would be pulled without actually modifying the repository.<br><br><b><b>--all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pull all heads from the remote repository. This is typically the default behavior for a standard pull but can be explicitly stated.<br><br><b><b>--revs</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pull revisions listed in a specified file. The file must contain one revision identifier per line.<br><br>


title: DESCRIPTION
content:
<b>hg pull</b> is a fundamental command in Mercurial, a distributed version control system. It's used to fetch new changesets from a remote repository into your local repository. Unlike <b>hg clone</b>, which creates a new repository, <b>hg pull</b> updates an existing one. When you pull, Mercurial downloads the latest changes from the specified source (which can be a path to a local repository or a URL for a remote one) and incorporates them into your local history.<br><br>It's important to note that <b>hg pull</b> only downloads changesets; it does not automatically update your working directory. This means your files on disk remain unchanged after a pull, unless you explicitly use the <b>--update</b> (or <b>-u</b>) option, or follow up with an <b>hg update</b> command. This separation allows you to inspect the incoming changes before applying them to your working copy, providing flexibility for managing merges or reviewing history. It's a key operation for keeping your local repository synchronized with upstream changes in a collaborative environment.


title: CAVEATS
content:
<i><b>hg pull</b></i> only fetches changesets into your local repository; it does not automatically update your working directory. To see the fetched changes in your files, you must explicitly run <i><b>hg update</b></i> or use the <i><b>--update</b></i> option during the pull. If conflicts arise during an update after pull (e.g., with <i><b>-u</b></i>), manual merge resolution will be required. Pulling from an unrelated or significantly diverged repository might require the <i><b>--force</b></i> option, which should be used with extreme caution as it can lead to complex repository states.


title: DEFAULT PULL PATH
content:
If no <i>SOURCE</i> is specified, <b>hg pull</b> will attempt to pull from the path specified by the 'default' configuration key in your local repository's <i>.hg/hgrc</i> file. This is typically the repository from which your local repository was cloned.


title: REMOTE REPOSITORY SPECIFICATION (SOURCE)
content:
The <i>SOURCE</i> argument can be a local path to another repository (e.g., <i>/path/to/repo</i>), a URL (e.g., <i>http://example.com/repo</i>, <i>ssh://user@host/repo</i>), or a named path configured in the <i>[paths]</i> section of your <i>.hg/hgrc</i> file (e.g., <i><b>hg pull</b> my_remote</i>).


title: HISTORY
content:
Mercurial was created by Matt Mackall in 2005, primarily in response to the licensing changes for BitKeeper, which had previously been used for Linux kernel development. The <b>pull</b> command, being a core operation in distributed version control systems, has been a fundamental part of Mercurial since its early days. Its design reflects the DVCS philosophy of local repositories being self-contained, with <b>pull</b> serving as the mechanism to synchronize with other repositories without necessarily affecting the local working copy immediately, providing greater control over the integration process.


title: PARAMETERS
content:
<b>--force, -f</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pushes even if it creates new remote heads or results in a non-fast-forward update. Use with caution as it can rewrite remote history or complicate others' pulls.<br><br><b>--rev REV, -r REV</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pushes only the specified revision <i>REV</i> and its ancestors that are not yet at the destination.<br><br><b>--branch BRANCH, -b BRANCH</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pushes only changesets belonging to the named <i>BRANCH</i>. This will push the branch and its ancestors.<br><br><b>--bookmark BOOKMARK, -B BOOKMARK</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pushes the specified <i>BOOKMARK</i> and any associated changesets.<br><br><b>--new-branch</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows pushing new branches even if the remote repository is configured to reject them by default.<br><br><b>--mq</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When used in an MQ-enabled repository, pushes the applied patches (patches that are committed into the main repository).<br><br><b>--stream</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempts to push changes using a streaming protocol if supported by the server, potentially improving performance for large pushes.<br><br><b>--ssh CMD, -S CMD</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the <i>CMD</i> to use when connecting to a remote repository via SSH.<br><br><b>--remotecmd CMD, -e CMD</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the <i>CMD</i> to run on the remote side.<br><br><b>--bundle FILE, -t FILE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pushes changes into a local bundle <i>FILE</i> instead of a remote repository. This creates a file that can be transferred manually.<br><br><b>--insecure, -U</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not verify the server's SSL certificate when pushing over HTTPS. Not recommended for production environments.<br><br><b>DEST</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path or URL of the destination repository. If omitted, Mercurial uses the <i>default</i> path configured in the local repository's .hg/hgrc file.<br><br>


title: DESCRIPTION
content:
<i>hg push</i> is a fundamental command in Mercurial, a distributed version control system, used to transfer new changesets from your local repository to a remote repository. This operation makes your local commits visible and available to others who pull from the remote.<br><br>By default, <i>hg push</i> sends all new changesets, including new heads (branches), that are present in your local repository but not in the destination. If the remote repository has divergent changes (e.g., you pushed to a different branch than expected, or someone else pushed concurrent changes), Mercurial will typically prevent the push unless explicitly told to force it, ensuring repository integrity and preventing accidental history rewriting. It's crucial for collaboration in a distributed environment, allowing developers to share their work.


title: CAVEATS
content:
<b>Non-Fast-Forward Pushes:</b> Mercurial typically prevents pushes that would create new heads on the remote without merging, or that would remove history. The <i>--force</i> option bypasses this but should be used with extreme caution, as it can complicate other developers' work or lead to lost changes if not handled correctly.<br><br><b>Permissions:</b> Successful pushes require write permissions on the remote repository.<br><br><b>Network Connectivity:</b> An active and stable network connection is necessary to communicate with the remote repository.


title: DEFAULT DESTINATION
content:
If no destination is specified, <i>hg push</i> attempts to push to the default path configured in your repository's .hg/hgrc file, typically under the <i>[paths]</i> section (e.g., <i>default = ssh://user@host/repo</i>). This provides a convenient way to manage common remote targets.


title: PUSHING SPECIFIC CHANGES
content:
Beyond pushing all new changes, <i>hg push</i> offers granular control through options like <i>--branch</i>, <i>--rev</i>, or <i>--bookmark</i>. These allow developers to push only specific branches, revisions, or bookmarks, which is useful for targeted updates or when collaborating on multiple features simultaneously.


title: SERVER-SIDE HOOKS
content:
Remote Mercurial repositories often utilize server-side hooks (e.g., <i>pretxnpush</i>, <i>changegroup</i>) that trigger actions or enforce policies upon receiving a push. These hooks can perform validations, send notifications, or integrate with other systems, ensuring code quality and workflow compliance.


title: HISTORY
content:
Mercurial (<i>hg</i>) was initiated by <i>Matt Mackall</i> in 2005, evolving rapidly as a robust distributed version control system. The <i>hg push</i> command has been a cornerstone of its distributed workflow from its early days, essential for sharing changesets between repositories. Its core functionality for transferring committed changes has remained consistent, while additional options like <i>--new-branch</i>, <i>--bookmark</i>, and various protocol enhancements have been introduced over time to accommodate new features and improve efficiency. This continuous refinement reflects Mercurial's commitment to providing flexible and reliable version control for developers.


title: SYNOPSIS
content:
<I><b>hg remove</b> [<b>-A</b>] [<b>-f</b>] [<b>-I</b> <I>PATTERN</I>] [<b>-X</b> <I>PATTERN</I>] [<b>-n</b>] [<b>-S</b>] <I>FILE</I>...</I>


title: PARAMETERS
content:
<b><b>-A</b>, <b>--after</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Mark files as removed after a successful commit. This option is <b>DEPRECATED</b> and effectively makes <b>hg remove</b> behave like <b>hg forget</b>, meaning the files are assumed to be already deleted from the working directory and their removal is just registered.</I><br><br><b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Force removal of files, even if they have uncommitted changes. Using this option will discard any unsaved modifications to the file.</I><br><br><b><b>-I</b> <I>PATTERN</I>, <b>--include</b> <I>PATTERN</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Include only names matching the specified pattern for removal. This pattern can be a shell-style glob or a regular expression.</I><br><br><b><b>-X</b> <I>PATTERN</I>, <b>--exclude</b> <I>PATTERN</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Exclude names matching the specified pattern from removal. This pattern can be a shell-style glob or a regular expression.</I><br><br><b><b>-n</b>, <b>--dry-run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Do not perform any actual file operations; instead, just print what files would be removed. This is useful for previewing changes before execution.</I><br><br><b><b>-S</b>, <b>--subrepos</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Recurse into subrepositories when looking for files to remove, applying the removal operation within them.</I><br><br>


title: DESCRIPTION
content:
<I>The <b>hg remove</b> (or its alias <b>hg rm</b>) command is a fundamental operation in Mercurial used to mark one or more files for deletion from the repository. When invoked, it typically performs two primary actions:<br><br>1.  It deletes the specified files from your working directory.<br>2.  It marks these files as scheduled for removal in the repository's history, which will be finalized upon the next <b>hg commit</b>.<br><br>By default, <b>hg remove</b> will prevent the deletion of files that have uncommitted changes in the working directory to prevent accidental data loss. To override this safeguard, the <b>--force</b> option can be used. For scenarios where a file has been manually deleted from the working directory but is still tracked by the repository, <b>hg remove</b> can be used to formally register its removal with Mercurial.<br><br>It's crucial to understand that the actual removal from the repository's history is only confirmed when you perform a subsequent <b>hg commit</b>. Before this, the changes are merely staged for removal. If your intent is to stop tracking a file without physically deleting it from your working directory, the <b>hg forget</b> command is the recommended tool, as the <b>hg remove -A</b> (or <b>--after</b>) option is deprecated for this purpose.</I>


title: CAVEATS
content:
<I>1.  <b>Working Directory Deletion:</b> By default, <b>hg remove</b> permanently deletes files from your working directory. Always ensure you have backups or are certain about the removal before proceeding.<br>2.  <b>Requires Commit:</b> The file's removal is not recorded in the repository's history until you perform a subsequent <b>hg commit</b>. Until then, the file might still exist in previous revisions.<br>3.  <b>Uncommitted Changes:</b> Files with uncommitted modifications cannot be removed without the <b>--force</b> option, which will discard those changes.<br>4.  <b>Deprecated Option:</b> The <b>-A</b> / <b>--after</b> option is deprecated. For merely stopping tracking a file without deleting it from the working copy, <b>hg forget</b> is the recommended command.</I>


title: <I>DIFFERENCE FROM <B>RM</B></I>
content:
<I>Unlike the standard Linux <b>rm</b> command, which only deletes files from the file system, <b>hg remove</b> interacts with the Mercurial repository. It not only deletes the file from your working directory but also stages this deletion as a change to be committed to the version control system. This ensures that the file's removal is tracked and becomes a part of the project's historical record.</I>


title: <I>REVERTING A REMOVAL</I>
content:
<I>If you have executed <b>hg remove</b> but have not yet committed the changes, you can typically undo the operation using <b>hg revert <I>FILE</I></b>. This command will restore the file to its state prior to the removal and also remove the 'deleted' status from Mercurial's pending changes.</I>


title: HISTORY
content:
<I><b>hg remove</b> has been a core command in Mercurial since its early development, providing the essential functionality to manage the removal of tracked files from a project's version control. Its alias <b>hg rm</b> offers familiar syntax for users accustomed to Unix-like command-line interfaces. Over time, the Mercurial command set has evolved, leading to the deprecation of certain options, such as <b>-A</b> / <b>--after</b>, in favor of more specialized and clearly defined commands like <b>hg forget</b>, which explicitly separates the act of untracking a file from its physical deletion from the working directory.</I>


title: SEE ALSO
content:
<I>hg add(1)</I>, <I>hg commit(1)</I>, <I>hg revert(1)</I>, <I>hg status(1)</I>, <I>hg forget(1)</I>


title: PARAMETERS
content:
<b><I>REPO</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An optional path to a Mercurial repository. If not specified, the command uses the current working directory to find the repository root.<br><br>


title: DESCRIPTION
content:
The `<b>hg root</b>` command is a Mercurial utility that identifies and prints the absolute path to the root directory of the current or specified Mercurial repository. When executed within a repository's working copy or a subdirectory thereof, it outputs the path to the top-level directory containing the `.hg` metadata directory. If an optional <I>REPO</I> argument is provided, the command will attempt to find the root of that specific repository.<br><br>This command is particularly useful for scripting, navigation, or simply confirming your current repository's base location. It helps developers quickly ascertain where a repository begins, which is fundamental for understanding the scope of version control operations and ensuring commands are executed from the correct context.


title: CAVEATS
content:
The command will fail and report an error if executed in a directory that is not part of a Mercurial repository, or if the specified <I>REPO</I> path does not point to a valid Mercurial repository.


title: USE CASES
content:
`<b>hg root</b>` is frequently used in shell scripts to build paths relative to the repository root, or to `cd` into the root directory before executing other Mercurial commands. It's also helpful for debugging when you're unsure if you're in a Mercurial repository or where its base is located, providing a quick confirmation of your current version control context.


title: HISTORY
content:
The `<b>hg root</b>` command has been a fundamental part of Mercurial (hg) since its early days. As a distributed version control system, Mercurial relies on clear identification of repository boundaries. `<b>hg root</b>` was developed to provide a simple, programmatic way to locate the `.hg` directory, which defines the repository's root. Its design emphasizes simplicity and consistency, reflecting Mercurial's overall philosophy. It has remained a stable and essential utility throughout Mercurial's development history, serving as a core component for navigating and scripting within repositories.


title: PARAMETERS
content:
<b>-p <I>PORT</I>, --port <I>PORT</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the port number to listen on. Defaults to 8000.<br><br><b>-A <I>ADDR</I>, --address <I>ADDR</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the address to bind to. Defaults to `0.0.0.0` (all available interfaces).<br><br><b>-d, --daemon</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs the server in the background as a daemon process.<br><br><b>--pid-file <I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the process ID (PID) of the server to the specified file when running as a daemon.<br><br><b>--webdir <I>DIR</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Serves all Mercurial repositories found within the specified directory, creating a list of repositories on the home page.<br><br><b>--repo <I>REPO</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Serves a specific repository located at `REPO`. Can be used multiple times, implying `--webdir` if more than one is specified.<br><br><b>--base-url <I>URL</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the base URL for links generated by the server, useful when the server is behind a reverse proxy.<br><br><b>--disable-push</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables push operations to the served repositories, making them read-only.<br><br><b>--disable-pull</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables pull operations from the served repositories (useful for mirroring or specific read-only scenarios).<br><br><b>--allow-push <I>USERS</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A comma-separated list of usernames explicitly allowed to push. Requires external authentication to identify users.<br><br><b>--allow-pull <I>USERS</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A comma-separated list of usernames explicitly allowed to pull. Requires external authentication to identify users.<br><br><b>--access-allow <I>IP</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows access only from the specified IP address or network range (e.g., `192.168.1.0/24`). Can be repeated for multiple allowed sources.<br><br><b>--access-deny <I>IP</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Denies access from the specified IP address or network range. This rule takes precedence over `--access-allow`.<br><br><b>--certificate <I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the SSL/TLS certificate file (e.g., `server.pem`) for enabling HTTPS.<br><br><b>--key <I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the SSL/TLS private key file (e.g., `server.key`) for enabling HTTPS.<br><br><b>--access-log <I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes web server access logs to the specified file, detailing incoming requests.<br><br><b>--error-log <I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes web server error messages and diagnostic information to the specified file.<br><br><b>-C <I>SECTION.NAME</I>=<I>VALUE</I>, --config <I>SECTION.NAME</I>=<I>VALUE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a Mercurial configuration value for the server process, overriding values from configuration files.<br><br><b>--name <I>NAME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the display name for the served repository in the web interface, useful for `--repo` or single-directory serves.<br><br>


title: DESCRIPTION
content:
The <b>hg serve</b> command launches a lightweight, built-in web server to make one or more Mercurial repositories accessible via HTTP or HTTPS. It's designed for quick and easy sharing of repositories, local browsing, or simple collaborative setups, without the need for a full-fledged web server like Apache or Nginx.<br><br>When run, <b>hg serve</b> starts a server that allows clients to clone, pull, and potentially push changesets to the served repositories. It provides a basic web interface for browsing commits, files, and other repository contents. By default, it serves the current working directory as a single repository, but it can be configured to serve a specific repository or an entire directory containing multiple repositories.<br><br>While highly convenient for development, testing, and small teams, <b>hg serve</b> is generally not recommended for high-load production environments due to its basic security features and limited scalability compared to dedicated web servers combined with Mercurial's `hgweb.cgi` or `hgweb.wsgi` scripts.


title: CAVEATS
content:
<b>hg serve</b> is intended for simple, ephemeral use or within trusted networks. It lacks advanced security features, robust logging, and performance optimizations typically found in production-grade web servers. For public-facing or high-traffic scenarios, it is strongly recommended to use a dedicated web server (like Apache or Nginx) combined with Mercurial's `hgweb.cgi` or `hgweb.wsgi` scripts, which offer more control over authentication, authorization, and scalability. Direct user authentication is not built-in; `--allow-push` and `--allow-pull` often rely on external authentication (e.g., via a proxy server) or user entries in `hgweb.config`.


title: AUTHENTICATION AND AUTHORIZATION
content:
<b>hg serve</b> provides basic IP-based access control via `--access-allow` and `--access-deny`. For user-specific authentication and authorization (e.g., allowing specific users to push), it typically relies on external mechanisms. While `--allow-push` and `--allow-pull` options exist, they are often paired with an `hgweb.config` file or an HTTP proxy that handles authentication (e.g., HTTP Basic Auth) to identify users. <b>hg serve</b> itself does not manage user accounts, focusing on serving content.


title: HTTPS USAGE
content:
To serve repositories over HTTPS, you must provide valid SSL/TLS certificate and key files using the `--certificate` and `--key` options, respectively. For example: `hg serve --port 443 --certificate mycert.pem --key mykey.key`. Ensure the certificate and key files are correctly formatted, are readable by the user running the command, and that the specified port is not blocked by a firewall.


title: HISTORY
content:
The `hg serve` command has been a fundamental part of Mercurial since its early development. It was introduced to provide a convenient, lightweight way for developers to quickly share their repositories without needing to set up complex web server configurations. While `hgweb` (which uses CGI/WSGI with a full web server) existed for more robust deployments, `hg serve` filled the gap for immediate local testing, ad-hoc collaboration, and sharing within a small, trusted group. Its simplicity and ease of use have made it a popular choice for quick prototyping and demonstration purposes.


title: PARAMETERS
content:
<b><I>FILE</I>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional filenames or directory paths to limit the status output to specific items.<br><br><b>-A, --added</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show only files scheduled for addition.<br><br><b>-C, --clean</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show only clean files (not modified since the last commit).<br><br><b>-D, --deleted</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show only files scheduled for deletion or removal.<br><br><b>-M, --modified</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show only files that have been modified.<br><br><b>-U, --unknown</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show only files not tracked by Mercurial (untracked).<br><br><b>-I, --ignored</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show only files that are ignored via <I>.hgignore</I>.<br><br><b>-s, --summary</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print only a summary of file counts by status type.<br><br><b>-r <I>REV</I>, --rev <I>REV</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show status compared to the specified revision <I>REV</I> instead of the parent of the working directory.<br><br><b>-c <I>REV</I>, --change <I>REV</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show files that have changed between revision <I>REV</I> and the working directory.<br><br><b>-n, --no-status</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress the leading status characters (e.g., 'M ', 'A '). Only show filenames.<br><br><b>-0, --print0</b><br>&nbsp;&nbsp;&nbsp;&nbsp;End filenames with a null character (NUL) instead of a newline, useful for scripting with tools like <I>xargs -0</I>.<br><br><b>-T <I>STR</I>, --template <I>STR</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use the given template string <I>STR</I> to format the output for each file.<br><br><b>-X <I>PATTERN</I>, --exclude <I>PATTERN</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exclude files matching the given pattern <I>PATTERN</I> from the output.<br><br><b>-I <I>PATTERN</I>, --include <I>PATTERN</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Include files matching the given pattern <I>PATTERN</I> in the output (overrides excludes).<br><br><b>-S, --subrepos</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Recurse into subrepositories when checking status.<br><br>


title: DESCRIPTION
content:
The <I>hg status</I> command displays the status of files and directories in the working copy compared to the repository's tip. It's a fundamental tool for understanding local changes before committing, providing an immediate snapshot of modifications. By default, it lists files that are modified, added, removed, missing from the working copy, and unknown (untracked). The output is designed to be clear and concise, often color-coded to help users quickly distinguish different file states. This command is crucial for deciding which files to stage for the next commit, which to add or remove, or which to ignore, thus offering an essential overview of the working directory's current state relative to the version control system.


title: CAVEATS
content:
Performance can be slow on very large repositories with a vast number of untracked files, especially without a well-configured <I>.hgignore</I> file. By default, <I>hg status</I> does not automatically recurse into subrepositories unless the <I>-S</I> or <I>--subrepos</I> option is used. The command displays renames or copies as distinct additions and deletions; explicit rename/copy tracking is typically handled by other commands like <I>hg diff</I> or <I>hg log --follow</I>.


title: OUTPUT CODES
content:
The <I>hg status</I> command uses single-character codes at the beginning of each line to indicate the status of a file:<br><br><b>M</b>: Modified (file has been changed)<br><b>A</b>: Added (file is scheduled for addition)<br><b>R</b>: Removed (file is scheduled for removal)<br><b>!</b>: Missing (file has been deleted from the working copy but not yet committed)<br><b>?</b>: Unknown (file is not tracked by Mercurial)<br><b>C</b>: Clean (file has not been modified; shown only with <I>-C</I> or <I>--clean</I>)<br><b>I</b>: Ignored (file matches an <I>.hgignore</I> pattern; shown only with <I>-I</I> or <I>--ignored</I>)<br><b>U</b>: Unresolved (file has merge conflicts)


title: HISTORY
content:
<I>hg status</I> is a core command of Mercurial, a distributed version control system initiated by Matt Mackall in 2005. Designed to provide a clear and immediate overview of the working directory's state, it has been an integral part of Mercurial since its inception. Its simplicity and effectiveness align with Mercurial's broader philosophy of ease of use and clarity, with evolution focusing primarily on output options and formatting rather than its fundamental function.


title: PARAMETERS
content:
<b>-r <REV>, --rev <REV></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Update to the specified revision, which can be a changeset ID, tag, branch name, or bookmark.<br><br><b>-C, --clean</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Discard all uncommitted changes in the working directory before updating. <br><b>Use with extreme caution as changes are lost permanently.</b><br><br><b>-f, --force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the update operation. This implicitly handles uncommitted changes by either merging them or, if no merge is possible, requiring a clean.<br><br><b>-m, --merge</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Merge pending changes into the target revision. This is the default behavior when uncommitted changes exist.<br><br><b>-d <DATE>, --date <DATE></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Update to the revision closest to the specified date and time.<br><br><b>--mq</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Apply or unapply Mercurial Queue patches as part of the update process.<br><br><b>--tool <TOOL></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a merge tool to use for resolving conflicts during the update.<br><br>


title: DESCRIPTION
content:
The <b>hg-update</b> command, often a shell alias or script wrapper for the core Mercurial <b>hg update</b> command, is used to synchronize the working directory with a specified revision in the repository's history. This allows users to switch between branches, revert to older states, or fast-forward to newer changesets. If no revision is specified, <b>hg-update</b> defaults to updating to the tip of the current branch. When uncommitted changes exist in the working directory, <b>hg-update</b> by default attempts to merge these changes with the target revision. Alternatively, users can explicitly discard local changes using the <i>--clean</i> option or force an update (implying a merge or clean operation) with <i>--force</i>. It's a fundamental command for navigating and managing different states within a Mercurial repository.


title: CAVEATS
content:
Using <i>--clean</i> will permanently discard any uncommitted changes in your working directory. Always commit or shelve changes before using this option unless you are certain you want to lose them.<br>Updates that involve significant changes or conflicts might require manual merging.<br>The <b>hg-update</b> command is commonly a shell alias or wrapper script for the primary <b>hg update</b> command provided by Mercurial. Its exact behavior might depend on how it's configured in your environment.


title: REVISION SPECIFICATION
content:
The <i>REVISION</i> argument can be specified using various methods: <br><i>• Changeset ID:</i> A full or abbreviated hexadecimal ID (e.g., `a1b2c3d4e5f6`). <br><i>• Branch Name:</i> (e.g., `default`, `feature-branch`). <br><i>• Tag Name:</i> (e.g., `release-1.0`). <br><i>• Bookmark Name:</i> (e.g., `my-dev-bookmark`). <br><i>• Special Keywords:</i> Such as `tip` (the latest head of any branch), `.` or `null` (the working directory's current parent), `parent()` or `@` (the current revision).


title: DEFAULT BEHAVIOR
content:
If no <i>REVISION</i> is specified, <b>hg-update</b> updates the working directory to the tip of the current branch. If uncommitted changes exist, it attempts to merge them with the target revision. If an update would lose uncommitted changes and <i>--clean</i> is not used, the command will abort unless <i>--force</i> is specified.


title: HISTORY
content:
Mercurial, and by extension its core <b>update</b> command, was initially released in April 2005. The <b>update</b> functionality has been a fundamental part of Mercurial's design from its early stages, providing a robust way to navigate and manage the repository's history and working directory state. Its primary mechanisms, such as handling uncommitted changes through merging or cleaning, have remained consistent throughout Mercurial's development.


title: PARAMETERS
content:
<b><b>-i</b> <i>&lt;vendor:product&gt;</i>, <b>--id</b> <i>&lt;vendor:product&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the USB device by its Vendor ID and Product ID (e.g., <i>0a12:0001</i>). This is an alternative to providing a sysfs path.<br><br><b><b>-e</b>, <b>--enable-driver</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Re-enable the <i>uhid</i> driver after switching. (Less common in modern use cases, usually the default behavior is to switch drivers).<br><br><b><b>-r</b>, <b>--reset-device</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempt to reset the device after performing the mode switch. This can help with some problematic devices.<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;Output version information and exit.<br><br><b><i>device</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The sysfs path to the USB device (e.g., <i>/sys/bus/usb/devices/1-2</i>). This is the primary way to specify the target device if not using <b>--id</b>.<br><br>


title: DESCRIPTION
content:
<i>hid2hci</i> is a utility designed to switch certain Bluetooth devices from Human Interface Device (HID) mode to Host Controller Interface (HCI) mode. Many Bluetooth USB dongles, particularly those intended to work immediately with basic input devices (like a mouse or keyboard) during system boot or in BIOS, initially enumerate as HID devices. While in HID mode, they function primarily as simple input devices, not as a full Bluetooth host controller.<br><br>The command allows the operating system's standard Bluetooth stack to take control of the device by switching it to HCI mode, which is the standard communication protocol for Bluetooth host controllers. Once switched, the device becomes a fully functional Bluetooth adapter, capable of managing connections to various Bluetooth peripherals, rather than just simple input. This conversion often involves unbinding the device from the <i>uhid</i> kernel module and rebinding it to the <i>hci_usb</i> module, effectively re-enumerating it as a proper Bluetooth controller.


title: CAVEATS
content:
Requires <i>root</i> privileges to execute, as it manipulates kernel-level device drivers.<br>Not all Bluetooth devices require or support this conversion. Many modern dongles or integrated Bluetooth modules are correctly identified as HCI devices from the start.<br>The device may temporarily disappear from the system or change its device node path during the conversion process.<br>Incorrect usage or applying to an unsupported device may render the device temporarily unusable until a system reboot or manual driver re-attachment.


title: USAGE EXAMPLE
content:
To use <i>hid2hci</i>, you first need to identify your Bluetooth device. You can use <i>lsusb</i> to find its Vendor ID and Product ID, or its bus/device path.<br><br>1. <b>Identify the device:</b><br>   <i>$ lsusb</i><br>   (Look for an entry like: <i>Bus 001 Device 002: ID 0a12:0001 Cambridge Silicon Radio, Ltd Bluetooth Dongle (HCI mode)</i>)<br><br>   If the device is already in HID mode, it might appear differently, e.g., as a generic USB device or HID device.<br><br>2. <b>Execute the command (using ID):</b><br>   <i>$ sudo hid2hci -i 0a12:0001</i><br><br>   Or, if you know the sysfs path (e.g., from <i>lsusb -t</i> or <i>udevadm info -q path -n /dev/hidrawX</i>):<br>   <i>$ sudo hid2hci /sys/bus/usb/devices/1-2</i><br><br>After successful execution, the device should reappear as a standard Bluetooth HCI device, and you can then manage it with <i>bluetoothctl</i> or <i>hciconfig</i>.


title: AUTOMATIC SWITCHING VIA UDEV
content:
Modern Linux distributions often include <i>udev</i> rules that automatically handle the HID-to-HCI conversion for known problematic devices. These rules typically reside in <i>/lib/udev/rules.d/</i> and are named similarly to <i>97-hid2hci.rules</i>. If your device isn't automatically switching, it might be that the device's Vendor ID and Product ID are not listed in these rules, or there's an issue with the <i>udev</i> setup. Manually running <i>hid2hci</i> can bypass these automatic mechanisms for one-time troubleshooting or for unsupported devices.


title: HISTORY
content:
<i>hid2hci</i> is part of the <i>BlueZ</i> Bluetooth stack utilities for Linux. It emerged to address specific hardware quirks of certain Bluetooth dongles that initially presented themselves as HID devices. As kernel drivers and <i>udev</i> rules have evolved, the need for manual execution of <i>hid2hci</i> has somewhat diminished, with many systems now automatically handling the HID-to-HCI conversion via <i>udev</i> rules (e.g., <i>udev</i> rules like <i>/lib/udev/rules.d/97-hid2hci.rules</i>). However, it remains a valuable tool for troubleshooting or for devices that aren't automatically switched.


title: PARAMETERS
content:
<b><b>-s</b> <i>LANG</i>, <b>--syntax=</b><i>LANG</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the input programming language or file type for highlighting (e.g., <i>c++</i>, <i>python</i>, <i>java</i>).<br><br><b><b>-O</b> <i>FMT</i>, <b>--out-format=</b><i>FMT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the output format, such as <i>html</i>, <i>rtf</i>, <i>tex</i>, <i>ansi</i>, or <i>svg</i>.<br><br><b><b>-t</b> <i>NAME</i>, <b>--theme=</b><i>NAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects the color theme to apply for highlighting (e.g., <i>solarized-dark</i>, <i>default</i>).<br><br><b><b>-o</b> <i>FILE</i>, <b>--output=</b><i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the highlighted output to the specified <i>FILE</i> instead of standard output.<br><br><b><b>-l</b>, <b>--line-numbers</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes line numbers in the output.<br><br><b><b>--list-themes</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a list of all available color themes.<br><br><b><b>--list-languages</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows a list of all supported programming languages and file formats.<br><br>


title: DESCRIPTION
content:
<i>highlight</i> is a versatile command-line utility designed to syntax highlight source code, configuration files, and other structured text.<br><br>It supports a wide array of programming languages and markup formats. Users can output the highlighted text to various formats, including <i>HTML</i>, <i>RTF</i>, <i>LaTeX</i>, <i>SVG</i>, and <i>ANSI</i> escape sequences for terminal display.<br><br>This makes it invaluable for generating beautiful code snippets for documentation, web pages, presentations, or for simply improving readability directly in the terminal. It can automatically detect the input language or be explicitly told which language to use. Its extensive customization options allow users to choose color themes, control font sizes, and manage line numbering, among other features.


title: CAVEATS
content:
While <i>highlight</i> is robust, its automatic language detection can sometimes be inaccurate for very short snippets or files without clear language indicators. Large files might also impact performance. Customizing themes and output styles extensively requires understanding its configuration files, which can be somewhat intricate initially.


title: CONFIGURATION AND CUSTOMIZATION
content:
<i>highlight</i> is highly customizable through configuration files typically located in <i>/usr/share/highlight/</i> or <i>~/.highlight/</i>. These files define themes, language definitions, and general settings, allowing users to fine-tune virtually every aspect of the highlighting process, including adding new languages or modifying existing ones.


title: HISTORY
content:
The <i>highlight</i> utility was initially developed by Andre Simon, with its first release dating back to 2004. It has been consistently maintained and expanded over the years, growing its support for a vast number of programming languages, output formats, and customization features. Its continued development reflects its utility as a standalone, powerful command-line solution for syntax highlighting.


title: SYNOPSIS
content:
As <i>hipercdecode</i> is not a standard Linux command and its exact syntax depends on the specific implementation it might be part of, a generic synopsis cannot be provided. It likely takes the path to a trace file as an argument and may have options for output format or filtering.


title: PARAMETERS
content:
<b>N/A</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specific parameters cannot be listed as <i>hipercdecode</i> is not a standard command with a publicly documented interface. Any options would be highly dependent on the particular version or script it's embedded within.<br><br>


title: DESCRIPTION
content:
<i>hipercdecode</i> is not a standard, universally available Linux command. It is a specialized utility, typically found within environments utilizing IBM's <b>HiperSockets</b> technology, such as Linux on IBM Z (mainframes) or z/VM. Its primary function is to interpret and decode raw trace data captured from HiperSockets network interfaces. <br><br><b>HiperSockets</b> provide very high-speed, low-latency network connectivity between logical partitions (LPARs) or virtual machines running on the same mainframe system. When network issues arise in such environments, trace data is often collected. <i>hipercdecode</i> would then be used to parse this binary or hexadecimal trace data into a human-readable format, aiding system administrators and network engineers in diagnosing problems, analyzing packet flows, and understanding network behavior specific to HiperSockets communication. Without the specific package or context it comes from, its exact usage and options are not part of general Linux documentation.


title: CAVEATS
content:
<i>hipercdecode</i> is not a command typically found in general-purpose Linux distributions. It is highly specialized for IBM mainframe environments (Linux on Z, z/VM) and their <b>HiperSockets</b> networking. Its availability, syntax, and functionality are entirely dependent on the specific IBM tooling or custom scripts where it is deployed. Users on non-IBM Z architectures or without relevant IBM software will not have this command.


title: PURPOSE IN MAINFRAME ENVIRONMENTS
content:
<i>hipercdecode</i> is crucial for debugging network connectivity and performance issues within IBM Z mainframe logical partitions (LPARs) or z/VM guests that utilize <b>HiperSockets</b>. It helps translate raw system-level trace data into an understandable format, revealing details about internal packet flow, errors, and performance characteristics of the <b>HiperSockets</b> link.


title: PROPRIETARY NATURE
content:
The command likely deals with proprietary data formats generated by IBM hardware and firmware. This specialization means it's not a generic network analysis tool but a specific one tied to IBM's ecosystem.


title: HISTORY
content:
The concept behind <i>hipercdecode</i> is rooted in the necessity to debug high-performance, internal network interfaces like IBM's <b>HiperSockets</b>. <b>HiperSockets</b> were introduced to provide very fast communication directly within mainframe systems, avoiding external physical network adapters. As with any complex networking technology, tools for diagnostics and troubleshooting are essential. Utilities like <i>hipercdecode</i> would have evolved as part of IBM's support and development tools for their mainframe systems, specifically for Linux on Z and z/VM, to help system administrators interpret the proprietary trace formats generated by <b>HiperSockets</b> activity. It is not part of the GNU core utilities or a widely adopted open-source project.


title: SEE ALSO
content:
tcpdump(8) <i>(General network capture, not HiperSockets specific)</i>, wireshark(1) <i>(General network analysis, not HiperSockets specific)</i>


title: SYNOPSIS
content:
<b>hipstopgm</b> [<b>-force</b>] [<b>-invert</b>] [<b>-width</b>=<i>W</i>] [<b>-height</b>=<i>H</i>] [<b>-dpi</b>=<i>D</i>] [<b>-gamma</b>=<i>G</i>] [<i>filename</i>]


title: PARAMETERS
content:
<b><b>-force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Bypasses the initial check for a valid PCL stream signature and attempts to convert the input regardless, which can be useful for unusual or malformed PCL data.<br><br><b><b>-invert</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Flips the black and white values of the output image, making black pixels white and white pixels black.<br><br><b><b>-width</b>=<i>W</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly sets the width of the output PGM image in pixels. If not specified, <i>hipstopgm</i> attempts to determine the width from the PCL stream; otherwise, it defaults to 1000 pixels.<br><br><b><b>-height</b>=<i>H</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly sets the height of the output PGM image in pixels. If not specified, <i>hipstopgm</i> attempts to determine the height from the PCL stream; otherwise, it defaults to 1000 pixels.<br><br><b><b>-dpi</b>=<i>D</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the resolution of the image in dots per inch. If not specified, <i>hipstopgm</i> tries to extract this information from the PCL stream; otherwise, it defaults to 300 DPI.<br><br><b><b>-gamma</b>=<i>G</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies gamma correction to the output image. <i>G</i> is a floating-point value, with a default of 1.0 (no correction).<br><br><b><i>filename</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the HP-PCL input file. If omitted, <i>hipstopgm</i> reads its input from standard input (stdin).<br><br>


title: DESCRIPTION
content:
<i>hipstopgm</i> is a specialized utility within the Netpbm image processing suite, designed to convert monochrome bitmap data embedded within HP-PCL (Printer Command Language) streams into the Portable GreyMap (PGM) format. This command is particularly useful for extracting and processing image components from documents originally destined for HP-PCL compatible printers, such as those using HP-GL/2 or PCL 5. It reads the PCL data, typically from standard input, identifies and extracts the bitmap, and outputs a corresponding PGM image to standard output. While PGM is a grayscale format, <i>hipstopgm</i> effectively represents the black and white nature of the input monochrome bitmap. It serves as a crucial bridge for integrating PCL-based image data into broader image manipulation workflows supported by Netpbm and other graphic tools.


title: CAVEATS
content:
<i>hipstopgm</i> is specifically designed for monochrome HP-PCL bitmaps and will not process color PCL data. If no bitmap is found in the input stream, or if the stream is not recognized as PCL, the command may warn and exit. Default dimensions and DPI (1000x1000 pixels, 300 DPI) are used if the PCL stream does not provide this information.


title: STANDARD INPUT/OUTPUT
content:
By default, <i>hipstopgm</i> reads HP-PCL data from standard input (stdin) and writes the resulting PGM image to standard output (stdout). This design allows for seamless integration into shell pipelines, enabling complex image processing workflows by chaining multiple Netpbm utilities.


title: BITMAP DETECTION
content:
The command attempts to detect and extract a valid monochrome bitmap from the HP-PCL stream. If it cannot find a bitmap or if the input is malformed, it will typically issue a warning message and terminate, preventing the generation of invalid output.


title: HISTORY
content:
<i>hipstopgm</i> is a component of the comprehensive Netpbm toolkit, which originated from Jef Poskanzer's <i>pbmplus</i> package in the late 1980s. This specific utility was derived from <i>pcltoppm</i> by Brian Deal, reflecting Netpbm's ongoing development to support conversions for a wide array of legacy and specialized image formats, including those used by various printer languages.


title: SYNOPSIS
content:
<i>set -o histexpand</i> <br> <i>set +o histexpand</i> <br> <i>shopt -s histexpand</i> <br> <i>shopt -u histexpand</i>


title: PARAMETERS
content:
<b>set -o histexpand</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Enables</I> the <i>histexpand</i> shell option. When active, history expansion is performed, allowing <b>!</b> syntax to recall and modify previous commands.<br><br><b>set +o histexpand</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Disables</I> the <i>histexpand</i> shell option. The <b>!</b> character will be treated as a literal character, preventing history expansions.<br><br><b>shopt -s histexpand</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Another way to <I>enable</I> the <i>histexpand</i> shell option, specific to Bash shell options. This provides the same functionality as <i>set -o histexpand</i>.<br><br><b>shopt -u histexpand</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Another way to <I>disable</I> the <i>histexpand</i> shell option, specific to Bash shell options. This provides the same functionality as <i>set +o histexpand</i>.<br><br>


title: DESCRIPTION
content:
<i>histexpand</i> is a fundamental shell option in Bash that, when enabled, allows for history expansion. This powerful feature enables users to efficiently re-execute, modify, or insert specific parts of previously executed commands into the current command line. It primarily utilizes the <b>!</b> character to perform these expansions. For instance, <i>!!</i> instantly re-executes the last command, <i>!$</i> refers to the last argument of the preceding command, and <i>!grep</i> executes the most recent command that started with 'grep'. Disabling <i>histexpand</i> (or the <i>!</i> option, which is equivalent for <i>set -o</i>) prevents these intelligent expansions, treating <b>!</b> as a literal character in most contexts, except when followed by a space, newline, '=', or '('. In interactive Bash sessions, <i>histexpand</i> is typically enabled by default, significantly streamlining command-line productivity. Users can query its status using <i>set -o</i> or <i>shopt</i>.


title: CAVEATS
content:
History expansion can sometimes lead to unintended command execution if not used carefully, especially when dealing with commands containing <b>!</b>. Users should be aware of the exact expansion before pressing Enter. If <i>histexpand</i> is disabled, the <b>!</b> character will lose its special meaning for history recall. The shell variable <i>HISTCHARS</i> can influence which characters trigger history expansion.


title: <B>COMMON HISTORY EXPANSIONS</B>
content:
<i>!!</i> <br> Refers to the last command. <br><br><i>!$</i> <br> Refers to the last argument of the previous command. <br><br><i>!*</i> <br> Refers to all arguments of the previous command. <br><br><i>!string</i> <br> Refers to the most recent command beginning with 'string'. <br><br><i>!?string?</i> <br> Refers to the most recent command containing 'string'. <br><br><i>!N</i> <br> Refers to command number N in the history list. <br><br><i>!-N</i> <br> Refers to the Nth previous command. <br><br><i>^string1^string2^</i> <br> A quick substitution to replace 'string1' with 'string2' in the previous command. This form does not require <i>histexpand</i> to be enabled if <i>shopt -s cmdhist</i> is off, but it's part of the general history manipulation features.


title: HISTORY
content:
History expansion has been a feature of Unix shells, particularly <i>csh</i> (C Shell), since the 1970s. Bash later adopted and enhanced this functionality, making it a standard and powerful interactive feature. The <i>histexpand</i> option specifically provides granular control over whether this behavior is active. It's often enabled by default in interactive Bash sessions for convenience and productivity.


title: PARAMETERS
content:
<b><I>n</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the last <I>n</I> commands from the history list.<br><br><b>-c</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Clears the entire history list.<br><br><b>-d <I>offset</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deletes the history entry at the specified <I>offset</I> (position) in the list.<br><br><b>-s <I>entry</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds <I>entry</I> to the end of the history list as a single entry.<br><br><b>-r</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads the history file and appends its contents to the current history list.<br><br><b>-w</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the current history list to the history file, overwriting its contents.<br><br><b>-a</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Appends the 'new' history lines (those entered in the current session but not yet saved) to the history file.<br><br><b>-n</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads history lines not already read from the history file into the current history list.<br><br><b>-p</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs history substitution on the following arguments and displays the result without storing them in the history list.<br><br><b>-q</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses output when used with other options (e.g., `-a`, `-n`, `-r`, `-w`).<br><br>


title: DESCRIPTION
content:
The `history` command is a crucial <I>shell built-in</I> feature that allows users to view, manage, and re-execute previously entered commands. It significantly enhances productivity by reducing repetitive typing and providing an easy way to correct or re-run complex commands. Each command entered at the prompt is typically saved in a history list in memory and, upon shell exit, to a history file (commonly <I>.bash_history</I> for Bash). Users can navigate this history using arrow keys, search it incrementally (Ctrl+R), or manipulate it directly with the `history` command's various options. It's an indispensable tool for efficient command-line interaction, providing a persistent record of shell activities.


title: CAVEATS
content:
The `history` command is a <I>shell built-in</I> (e.g., in Bash, Zsh, Ksh). Its behavior can vary slightly between shells, and it is not an external executable like most commands found in `/bin` or `/usr/bin`.<br>History size, file location, and saving behavior are largely controlled by shell <I>environment variables</I> (e.g., `HISTSIZE`, `HISTFILE`, `HISTFILESIZE`, `HISTCONTROL`).<br>Sensitive commands (e.g., containing passwords) can be stored in the history file, posing a <I>security risk</I> if the file is not properly secured. Consider using `HISTCONTROL=ignorespace` to prevent commands prefixed with a space from being saved, or `HISTCONTROL=ignoreboth` (ignorespace and duplicates).


title: ENVIRONMENT VARIABLES
content:
Several environment variables control the behavior of the history list:<br><b>HISTSIZE</b>: The maximum number of commands to store in the history list in memory (default 1000).<br><b>HISTFILE</b>: The path to the history file where commands are saved (default <I>~/.bash_history</I>).<br><b>HISTFILESIZE</b>: The maximum number of lines contained in the history file (default 2000).<br><b>HISTCONTROL</b>: Controls how commands are saved to the history list. Common values include `ignorespace` (don't save commands prefixed with a space), `erasedups` (remove duplicate entries), and `ignoreboth` (combines both).


title: HISTORY EXPANSION
content:
Bash provides powerful history expansion capabilities using the `!` character, similar to csh. For example, `<b>!!</b>` re-executes the last command, `<b>!ls</b>` re-executes the last command starting with `ls`, and `<b>!$</b>` refers to the last argument of the previous command. This feature, enabled by default in interactive shells, can be controlled with `set -o histexpand` or `set -H`.


title: PERSISTENT HISTORY
content:
For history to be saved across shell sessions, the `HISTFILE` variable must be set. Typically, the `shopt -s histappend` option is enabled to append new history entries to the existing file rather than overwriting it upon shell exit. Advanced configurations might use `PROMPT_COMMAND` to save history after each command, ensuring no loss of history in case of unexpected shell termination.


title: HISTORY
content:
The concept of command history dates back to early interactive computing environments. In Unix, the C shell (<I>csh</I>) introduced a rudimentary `history` mechanism in the late 1970s, allowing users to recall and re-execute previous commands using event designators (like `!`). This feature proved immensely popular for improving command-line efficiency. Subsequent shells, notably the Korn shell (<I>ksh</I>) and the Bourne-Again shell (<I>bash</I>), built upon and significantly enhanced this capability. Bash's `history` built-in provides a robust set of options for managing the history list, reading from and writing to history files, and controlling history expansion, making it a cornerstone of modern shell interaction. Its design has evolved to handle persistent history across sessions and more sophisticated searching and manipulation.


title: SYNOPSIS
content:
<b>hive</b> [<i>options</i>] [<i>-e &lt;query_string&gt;</i> | <i>-f &lt;filepath&gt;</i>]<br>Common usage involves either interactive mode (running <b>hive</b> without arguments to enter the shell) or executing a single query/script.


title: PARAMETERS
content:
<b><b>-e &lt;quoted_query_string&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Execute a single HiveQL command. The query string must be <i>quoted</i>.<br><br><b><b>-f &lt;filepath&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Execute HiveQL commands from the specified file.<br><br><b><b>-H</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display help information and exit.<br><br><b><b>-i &lt;filepath&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Initialization script. Execute HiveQL commands from this file before entering interactive mode or executing the main query/script.<br><br><b><b>-S</b>, <b>--silent</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run in silent mode, suppressing progress and informational messages to output only query results.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run in verbose mode, displaying detailed execution information.<br><br><b><b>-p</b>, <b>--print-header</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the column headers in the output for query results.<br><br><b><b>--hiveconf &lt;property=value&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set a Hive configuration property. Can be used multiple times. Also aliased by <b>-D</b>.<br><br><b><b>--hivevar &lt;variable=value&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Define a Hive variable that can be used within HiveQL scripts (e.g., <i>${hivevar:myvar}</i>).<br><br><b><b>-database &lt;database_name&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the database to use upon starting the CLI.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the Hive version and exit.<br><br>


title: DESCRIPTION
content:
The <b>hive</b> command is the primary command-line interface (CLI) for interacting with Apache Hive. Hive is a data warehouse software built on top of Apache Hadoop that provides a SQL-like query language called HiveQL for querying and managing large datasets stored in distributed storage systems like HDFS. The <b>hive</b> CLI allows users to submit HiveQL queries, manage tables and databases, and execute scripts, effectively abstracting the complexities of underlying MapReduce, Tez, or Spark jobs. It translates HiveQL statements into distributed computations, enabling data analysts and developers to leverage SQL knowledge for big data analysis without needing to write complex Java code for Hadoop. This makes Hive a powerful tool for ETL processes, data warehousing, and ad-hoc queries over massive datasets.


title: CAVEATS
content:
<b>Performance Overhead</b>: Due to its reliance on Hadoop for execution, <b>hive</b> can incur significant startup and execution overhead, making it less suitable for low-latency queries or small datasets compared to traditional RDBMS.<br><b>Resource Intensive</b>: Hive queries consume cluster resources (CPU, memory, disk I/O) proportional to the data size and query complexity.<br><b>Schema-on-Read</b>: Hive enforces schema at query time rather than load time, which offers flexibility but can lead to data type errors if data doesn't conform to the defined schema.<br><b>Not OLTP</b>: Hive is designed for Online Analytical Processing (OLAP) and batch processing, not transactional workloads (OLTP). It lacks typical RDBMS features like row-level updates and real-time inserts for efficiency.


title: <B>INTERACTIVE MODE</B>
content:
To enter the interactive Hive shell, simply run <b>hive</b> without any arguments. From the shell, you can type HiveQL queries directly, which are executed upon pressing Enter and ending with a semicolon.


title: <B>SCRIPT EXECUTION</B>
content:
For batch processing or repeated tasks, it is common to put HiveQL commands into a <i>.hql</i> file and execute it using <b>hive -f my_script.hql</b>. This method is efficient for automated jobs.


title: <B>CONFIGURATION MANAGEMENT</B>
content:
Hive's behavior can be extensively configured via <i>hive-site.xml</i> or by passing <b>--hiveconf</b> (or <b>-D</b>) arguments on the command line. These properties control everything from query optimization to resource allocation.


title: HISTORY
content:
Apache Hive originated at Facebook in 2007 as a project to provide a SQL-like interface for ad-hoc queries and analysis over their massive datasets stored in Hadoop Distributed File System (HDFS). It was open-sourced in 2008 and quickly became an Apache Top-Level Project. Initially, Hive relied solely on MapReduce as its execution engine. Over time, it evolved to support more efficient engines like Apache Tez and Apache Spark, significantly improving query performance. Its development focused on making big data accessible to analysts familiar with SQL, abstracting away the complexities of distributed programming.


title: SYNOPSIS
content:
<b>hledger</b> <i>[GLOBAL_OPTIONS]</i> <COMMAND> <i>[COMMAND_OPTIONS] [ARGUMENTS]</i><br><br>Examples of common commands:<br><b>hledger</b> <i>[GLOBAL_OPTIONS]</i> balance <i>[ACCOUNT_REGEX...]</i><br><b>hledger</b> <i>[GLOBAL_OPTIONS]</i> register <i>[ACCOUNT_REGEX...]</i><br><b>hledger</b> <i>[GLOBAL_OPTIONS]</i> add <i>[ACCOUNT_REGEX...]</i>


title: PARAMETERS
content:
<b>--file FILE, -f FILE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the journal file to use.<br><br><b>--output-format FORMAT, -o FORMAT</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output format (e.g., <i>csv</i>, <i>json</i>, <i>html</i>, <i>text</i>).<br><br><b>--start DATE, -b DATE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes transactions on or after the specified date.<br><br><b>--end DATE, -e DATE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes transactions on or before the specified date.<br><br><b>--period PERIOD, -p PERIOD</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filters data for a specific period (e.g., <i>"last month"</i>, <i>"2023"</i>).<br><br><b>--depth N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limits the display depth of accounts in hierarchical reports.<br><br><b>--query QUERY</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filters transactions or posts using a search query (e.g., <i>"food and (date:2023/01/01..2023/01/31)"</i>).<br><br><b>--cost</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays amounts using their original cost.<br><br><b>--value</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays amounts using their current market value.<br><br>


title: DESCRIPTION
content:
<b>hledger</b> is a powerful, cross-platform command-line utility for double-entry accounting. It manages financial data stored in plain text files (often <i>.journal</i> or <i>.hledger</i> files). Inspired by the original Ledger command, <b>hledger</b> brings its own set of features and a Haskell implementation, focusing on reliability and a consistent user experience. It allows users to track income, expenses, assets, and liabilities by entering transactions in a human-readable format. <b>hledger</b> can generate various financial reports, including balance sheets, income statements, registers, and more, directly from the command line. Its plain text format makes it highly flexible, version-controllable (e.g., with Git), and future-proof, avoiding vendor lock-in typical of proprietary accounting software. It supports advanced features like recurring transactions, commodities, budgeting, and multiple currencies, making it suitable for both personal and small business finance management.


title: CAVEATS
content:
<ul><li><b>Learning Curve:</b> Requires understanding of double-entry accounting and its specific plain-text file format.</li><li><b>Text-based:</b> No GUI by default; interaction is purely through the command line.</li><li><b>Strict Syntax:</b> The journal file syntax is precise; minor errors can lead to unexpected results.</li><li><b>Data Integrity:</b> User is responsible for backing up journal files.</li></ul>


title: PLAIN TEXT DATA
content:
Financial data is stored in simple, human-readable text files, making it highly flexible, portable, and easily integrable with version control systems like Git for tracking changes.


title: EXTENSIBILITY
content:
Being a command-line tool, <b>hledger</b> can be easily scripted and integrated into custom workflows, allowing for automation of reporting or data input.


title: MULTI-CURRENCY SUPPORT
content:
Handles transactions and reports across multiple currencies with automated price fetching capabilities.


title: HISTORY
content:
<b>hledger</b> emerged as a reimplementation of the popular <b>Ledger</b> CLI accounting system, written in Haskell. Its development began in 2008, aiming to provide a robust, reliable, and easily maintainable alternative to <b>Ledger</b>'s C++ codebase. While inspired by <b>Ledger</b>'s concepts and command-line interface, <b>hledger</b> has evolved with its own distinct features, a slightly different syntax interpretation, and a strong focus on correctness and user-friendliness inherent to the Haskell language. It has gained a dedicated community and is actively maintained, becoming a significant tool in the plain text accounting ecosystem.


title: PARAMETERS
content:
<b>-f <I>FILE</I>, --file=<I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the journal file to read. If not provided, <b>hledger</b> looks for a default file (e.g., <code>~/.hledger.journal</code>).<br><br><b>-b, --balance</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the current balance of each account alongside its name.<br><br><b>-B, --cost</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows balances valued at cost basis.<br><br><b>-C, --market</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows balances valued at market price.<br><br><b>-E, --empty</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes accounts with zero balance or no transactions. By default, these are hidden unless queried directly.<br><br><b>-T, --tree</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays accounts in a hierarchical tree structure. This is the default display mode.<br><br><b>-S, --flat</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays accounts in a flat (non-hierarchical) list.<br><br><b>-n, --count</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the total number of transactions affecting each account.<br><br><b>-O, --unmarked</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows only accounts that are not marked (e.g., with <code>(closed)</code> or <code>(virtual)</code>) in the journal file.<br><br><b>-o <I>FORMAT</I>, --output-format=<I>FORMAT</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output format, such as <code>csv</code> for comma-separated values, <code>json</code>, or <code>text</code>.<br><br><b>-s <I>FIELD</I>, --sort=<I>FIELD</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sorts the accounts by a specified field (e.g., <code>name</code>, <code>balance</code>).<br><br><b>--depth=<I>N</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limits the displayed account hierarchy to a specified depth <code>N</code>.<br><br><b>[<I>ACCOUNT_QUERY</I>...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more regular expressions or account names to filter the displayed accounts. Only accounts matching the query will be shown.<br><br>


title: DESCRIPTION
content:
The <b>hledger accounts</b> command is a fundamental subcommand of the <b>hledger</b> plain text accounting system. Its primary function is to parse one or more journal files and present a comprehensive, hierarchical list of all accounts defined within them. This command is invaluable for understanding the structure of your financial records, auditing account names for consistency, or quickly locating specific accounts.<br><br>By default, <b>hledger accounts</b> displays accounts in a tree-like structure, reflecting their parent-child relationships (e.g., 'Assets:Bank:Checking'). It can also be configured to show flat lists, include account balances, transaction counts, or even market values, depending on the specified options. It supports filtering accounts using a query, allowing users to focus on specific branches or types of accounts. This makes it a versatile tool for both daily accounting oversight and deeper analysis of your financial setup, ensuring that all defined accounts are visible and correctly spelled.


title: CAVEATS
content:
The <b>hledger accounts</b> command relies entirely on the correctness and completeness of your <b>hledger</b> journal file(s). Any accounts not explicitly defined or implicitly used in transactions will not appear. Output can be extensive for very large journals without specific filtering via <code>ACCOUNT_QUERY</code> arguments. Ensure <b>hledger</b> is installed and accessible in your PATH.


title: JOURNAL FILE DEPENDENCY
content:
The command operates by parsing <b>hledger</b> journal files, typically named <code>.journal</code> or <code>.dat</code>. These files contain all your account definitions, transactions, and other financial records. The structure of your accounts (e.g., <code>Assets:Cash</code>, <code>Expenses:Groceries</code>) is entirely derived from how you define them in these journal files. Without a valid journal, <b>hledger accounts</b> has no data to display.


title: ACCOUNT QUERYING
content:
The optional <code>ACCOUNT_QUERY</code> arguments allow for powerful filtering of the accounts list. You can specify a full account name (e.g., <code>Assets:Bank:Checking</code>) or use regular expressions (e.g., <code>Expenses.*</code>) to display only a subset of your accounts. This is particularly useful for large journals or when you only need to inspect a specific branch of your account hierarchy.


title: HISTORY
content:
<b>hledger</b>, the plain text accounting system, was created by Simon Michael and first released in 2007 as a Haskell-based re-implementation of the popular <b>ledger</b> command-line accounting tool. The <b>accounts</b> subcommand has been a core and indispensable part of <b>hledger</b> from its early days, serving as one of the primary ways users can inspect and understand the structure of their financial data. Its design benefits from the robustness and expressiveness of Haskell, making it a reliable and efficient tool for plain text accounting enthusiasts.


title: PARAMETERS
content:
<b><B>-f FILE</B>, <B>--file=FILE</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specifies the main journal file to use for adding the entry.</I><br><br><b><B>-o FILE</B>, <B>--output-file=FILE</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Writes the newly added entry to the specified file instead of the default journal file.</I><br><br><b><B>-i FILE</B>, <B>--input-file=FILE</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Reads the new entry content from the specified file rather than prompting interactively.</I><br><br><b><B>-u</B>, <B>--unbalanced</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Allows the creation of entries where total debits do not equal total credits.</I><br><br><b><B>-x</B>, <B>--external</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Opens the entry content in an external text editor for modification before saving.</I><br><br><b><B>--auto-balance</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Automatically calculates and applies the balancing amount to the last account entered.</I><br><br><b><B>--dry-run</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Prints the entry that would be added to standard output without actually writing it to the journal file.</I><br><br><b><B>--force</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Used with <B>-o</B>, it overwrites the output file if it already exists.</I><br><br><b><B>--no-history</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Disables the suggestion of past values for interactive prompts like description and account names.</I><br><br><b><B>--no-hints</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Suppresses the display of helpful hints during the interactive entry process.</I><br><br><b><B>--edit-entry</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Opens the newly added entry in an external editor immediately after it's saved.</I><br><br><b><B>--edit-last</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Opens the last saved entry in the journal file in an external editor.</I><br><br><b><B>--edit-last-path=PATH</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specifies a particular file to open with <B>--edit-last</B>.</I><br><br>


title: DESCRIPTION
content:
<i>hledger-add</i> is an interactive subcommand of the <i>hledger</i> command-line accounting system, designed to simplify the process of adding new financial transactions (journal entries) to your ledger file. It guides you through a series of prompts for essential transaction details, including the date, a descriptive narration (payee/description), and individual account postings with their respective amounts. The command intelligently suggests dates, descriptions, and account names based on past entries, significantly accelerating data input and reducing errors. It also ensures that entries are balanced (debits equal credits) before writing them to the journal file, enhancing the integrity of your financial records. This interactive, guided approach makes managing finances with <i>hledger</i> more accessible, particularly for users who prefer a structured input method over direct text file manipulation.


title: CAVEATS
content:
<I>hledger-add</I> is primarily designed for interactive use; scripting it directly without <B>-i</B> requires careful handling of standard input. The <B>--input-file</B> option fundamentally alters its behavior from interactive input to batch processing. It relies on a properly configured <i>hledger</i> environment, including a journal file. Errors in manually entered account names or amounts may lead to incorrect entries if not reviewed carefully during the interactive process.


title: INTERACTIVE PROMPTS
content:
<i>hledger-add</i> guides the user through a structured series of prompts for each part of a transaction:<br><br>1. <B>Date:</B> Defaults to the current date, with easy navigation for other dates.<br>2. <B>Description:</B> For payee or narration, often suggesting past descriptions.<br>3. <B>Postings:</B> Prompts for account names and amounts. It offers auto-completion for existing accounts and helps ensure entries balance.


title: ENTRY BALANCING
content:
By default, <i>hledger-add</i> enforces that each transaction entry is balanced, meaning the sum of all debits must equal the sum of all credits. If an entry is unbalanced during input, the command will prompt the user to correct it. Alternatively, the <B>--unbalanced</B> flag can be used to bypass this check, or the <B>--auto-balance</B> option can automatically calculate and apply the necessary balancing amount to the last entered posting.


title: HISTORY
content:
<i>hledger-add</i> is a core component of the <i>hledger</i> plain text accounting system, which draws inspiration from the original <i>Ledger</i> software. Developed in Haskell, <i>hledger</i> aims to provide a robust, cross-platform solution for financial tracking. The <i>add</i> subcommand was introduced to offer a more user-friendly, interactive method for inputting transactions, addressing the demand for a guided data entry process that many users prefer over manual text file editing. Its ongoing development focuses on enhancing user experience through features like smart suggestions, auto-completion, and real-time balancing, making <i>hledger</i> more accessible to a wider user base.


title: PARAMETERS
content:
<b><b>--file=</b><I>FILE</I>, <b>-f</b><I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specify the journal file(s) to read. Defaults to <b>~/.hledger.journal</b> or <b>./.hledger.journal</b>.</I><br><br><b><b>--begin=</b><I>DATE</I>, <b>-b</b><I>DATE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Start date for transactions. Only transactions on or after this date are included.</I><br><br><b><b>--end=</b><I>DATE</I>, <b>-e</b><I>DATE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>End date for transactions. Only transactions on or before this date are included.</I><br><br><b><b>--period=</b><I>PERIODEXPR</I>, <b>-p</b><I>PERIODEXPR</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Filter transactions by a specific period expression (e.g., 'last month', '2023', '2023/1/1-2023/3/31').</I><br><br><b><b>--daily</b>, <b>-D</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Show daily balances. Useful with <b>--begin</b>/<b>--end</b> or <b>--period</b>.</I><br><br><b><b>--monthly</b>, <b>-M</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Show monthly balances.</I><br><br><b><b>--yearly</b>, <b>-Y</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Show yearly balances.</I><br><br><b><b>--empty</b>, <b>-E</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Include accounts with zero balances in the report.</I><br><br><b><b>--extended</b>, <b>-x</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Show an extended balance report including opening, closing, and change balances.</I><br><br><b><b>--tree</b>, <b>-T</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Display accounts in a hierarchical tree structure, reflecting their full names.</I><br><br><b><b>--depth=</b><I>N</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>When using tree view, limit the depth of displayed accounts (e.g., <b>--depth=2</b> shows only top two levels).</I><br><br><b><b>--pretty</b>, <b>-P</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Format output more prettily, aligning columns and adding visual separation.</I><br><br><b><b>--no-total</b>, <b>-N</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Do not show the grand total line at the bottom of the report.</I><br><br><b><b>--sort=</b><I>FIELD</I>, <b>-s</b><I>FIELD</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Sort accounts by a specified field (e.g., 'name', 'balance', 'last-date').</I><br><br><b><b>--sort-amounts</b>, <b>-S</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Sort accounts by their total balance amount in descending order.</I><br><br><b><b>--cost</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Show balances using transaction costs instead of market values.</I><br><br><b><b>--value</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Show balances using market values at the report's end date, requiring price entries.</I><br><br><b><b>--pivot=</b><I>FIELD</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Pivot the balance report by a transaction field (e.g., 'tag', 'payee'), creating columns for each value.</I><br><br><b><I>QUERY</I>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Optional query expressions to filter accounts or transactions (e.g., 'Expenses', 'account:Assets', 'tag:home').</I><br><br>


title: DESCRIPTION
content:
<I><b>hledger-balance</b> is a core command of the <b>hledger</b> plain text accounting system. It computes and displays the current or historical balances of accounts defined in your <b>hledger</b> journal files. This command is essential for understanding your financial position, tracking assets, liabilities, income, and expenses over various periods. It supports filtering by account name or transaction properties, aggregating balances by day, month, or year, and presenting the data in various formats including a hierarchical tree view. <b>hledger-balance</b> provides a flexible way to generate financial reports directly from your human-readable ledger data.</I>


title: CAVEATS
content:
<I><b>hledger-balance</b>'s performance can degrade with very large journal files or complex queries, especially when date-range filters are applied on every command execution against the entire journal. While highly flexible, generating intricate custom reports may sometimes require piping output to other command-line tools like <b>grep</b>, <b>awk</b>, or <b>sort</b>. Revalued balances (using <b>--value</b>) rely on accurate and complete price entries in the journal file; their accuracy directly depends on the quality of this data.</I>


title: <B>QUERYING BALANCES</B>
content:
<I>The `QUERY` arguments allow powerful filtering of accounts and transactions. For example, `<b>hledger balance expenses</b>` shows only expense accounts, `<b>hledger balance tag:rent</b>` shows balances for transactions tagged 'rent', and `<b>hledger balance assets 2023/01/01</b>` shows asset balances at the start of 2023.</I>


title: <B>OUTPUT CUSTOMIZATION</B>
content:
<I>Beyond basic formatting with <b>--tree</b> and <b>--pretty</b>, <b>hledger-balance</b> offers advanced options like <b>--balance-format</b> and <b>--balance-columns</b> for fine-grained control over the output columns and their display. This enables users to create highly specific and customized balance report layouts to suit their analytical needs.</I>


title: HISTORY
content:
<I><b>hledger</b> was created as an independent, Haskell-based reimplementation of <b>ledger</b>, aiming for improved code clarity, ease of development, and different design choices while maintaining compatibility with the plain text ledger file format. <b>hledger-balance</b> is one of its fundamental commands, mirroring the functionality of <b>ledger</b>'s `balance` command, and has been a core part of <b>hledger</b> since its early development. It has continuously evolved with new features like pivot tables and enhanced formatting options to meet diverse reporting needs.</I>


title: SEE ALSO
content:
<b>hledger(1)</b>: <I>The main hledger program and its general options.</I>, <b>hledger-register(1)</b>: <I>Displays a detailed transaction list (register) for specified accounts.</I>, <b>hledger-cashflow(1)</b>: <I>Calculates and displays cash flow statements from journal data.</I>, <b>ledger(1)</b>: <I>The original command-line accounting system written in C++, a predecessor to hledger.</I>


title: PARAMETERS
content:
<b><b>-f</b> <i>FILE</i>, <b>--file=</b><i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the ledger data file to process.<br><br><b><b>-b</b> <i>DATE</i>, <b>--begin=</b><i>DATE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the start date for transactions to consider. For a balance sheet, transactions up to this date are generally included.<br><br><b><b>-e</b> <i>DATE</i>, <b>--end=</b><i>DATE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the 'as of' date for the balance sheet. All transactions up to and including this date are included in the calculation.<br><br><b><b>-p</b> <i>PERIOD</i>, <b>--period=</b><i>PERIOD</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the time period for the report. For balance sheets, this implicitly sets the end date.<br><br><b><b>-V</b>, <b>--value</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Converts all amounts to a single commodity, useful for multi-currency ledgers to get a unified total.<br><br><b><b>-s</b>, <b>--show-empty</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes accounts with a zero balance in the report. By default, these are hidden.<br><br><b><b>-S</b>, <b>--sort-accounts</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sorts accounts alphabetically by their full name.<br><br><b><b>-E</b>, <b>--exact</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Matches account names exactly by the provided regular expressions, without implicitly including sub-accounts.<br><br><b><b>--depth=</b><i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limits the display of hierarchical accounts to a specified depth <i>N</i>.<br><br><b><b>--layout=</b><i>LAYOUT_FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses a custom report layout defined in a separate file for structured output.<br><br><b><b>--flat</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses the hierarchical indentation of accounts, displaying them on a single level.<br><br><b><b>--pivot=</b><i>FIELD</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Groups or pivots the report by a specific transaction field (e.g., 'tag', 'payee').<br><br><b><b>-O</b> <i>FORMAT</i>, <b>--output-format=</b><i>FORMAT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output format (e.g., 'text', 'csv', 'json').<br><br><b><b>-o</b> <i>FILE</i>, <b>--output-file=</b><i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Redirects the report output to a specified file instead of standard output.<br><br><b>[<i>ACCOUNT_REGEX</i>...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more regular expressions to filter which accounts are included in the report.<br><br>


title: DESCRIPTION
content:
The <b>hledger-balancesheet</b> command, a core subcommand of the <b>hledger</b> plain text accounting system, generates a balance sheet report. This report provides a financial snapshot at a specific point in time, detailing an entity's <i>assets</i> (what it owns), <i>liabilities</i> (what it owes), and <i>equity</i> (the residual value or net worth).<br><br>It is an essential tool for understanding the financial health of your ledger, allowing users to assess their financial position on any given date. The command supports various filtering options by date, account, and commodity, and allows for custom formatting and layout to suit diverse reporting needs. It aligns with the fundamental accounting equation: <i>Assets = Liabilities + Equity</i>.


title: CAVEATS
content:
A balance sheet is a snapshot in time; running it on different dates will yield different results. Its accuracy is entirely dependent on the completeness and correctness of the underlying ledger data. For multi-currency ledgers, the <b>--value</b> option is often necessary to get a meaningful total, as <b>hledger</b> does not automatically convert currencies without explicit instruction.


title: FUNDAMENTAL ACCOUNTING EQUATION
content:
The <b>hledger balancesheet</b> command implicitly represents the fundamental accounting equation: <i>Assets = Liabilities + Equity</i>. Assets are what you own, Liabilities are what you owe, and Equity is the residual value (your net worth). The report structure is designed to clearly show this relationship, providing a clear picture of financial position.


title: TIME SENSITIVITY
content:
Unlike an income statement which covers a period, a balance sheet is strictly 'as of' a specific date. If no date is specified with <b>-e</b> or <b>-p</b>, it defaults to the current date, showing the financial position at the end of the last recorded transaction on or before today.


title: HISTORY
content:
<b>hledger</b> is a free software accounting system that tracks money and commodities using plain text data files, inspired by the original <b>ledger</b> program. Development began in 2007 by Simon Michael, written in Haskell, with goals of simplicity, user-friendliness, and extensibility. The <b>balancesheet</b> subcommand has been a fundamental component since early versions, providing core financial reporting alongside income/expense statements. Its design has evolved to support various filtering, formatting, and custom layout options, reflecting the growing needs of its user base.


title: SEE ALSO
content:
hledger(1), hledger-incomeflow(1), hledger-cashflow(1), hledger-register(1), hledger-print(1), ledger(1)


title: PARAMETERS
content:
<b>-f <i>FILE</i>, --file=<i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the main journal file to read and write. Defaults to <i>~/.hledger.journal</i> or <i>.hledger.journal</i>.<br><br><b>-r <i>FILE</i>, --rules-file=<i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Load import rules from the specified file. This is essential for customizing how transactions are parsed and assigned.<br><br><b>-p, --print</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instead of adding entries to the journal file, print the generated entries to standard output. Useful for testing rules.<br><br><b>-i, --interactive</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run in interactive mode. This is the default if neither <b>--auto</b> nor <b>--add</b> is specified. It prompts the user for confirmation or input for each transaction.<br><br><b>-a, --auto</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run in automatic (non-interactive) mode. Transactions are processed according to rules without user intervention. Existing entries are skipped.<br><br><b>--add</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run in automatic mode and add entries directly to the journal. Implies <b>--auto</b> and overrides <b>--interactive</b>.<br><br><b>--dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Process transactions but do not make any changes to the journal file. Shows what would happen if the command were run normally.<br><br><b>--ignore-existing</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not skip entries that already exist in the journal. By default, <i>hledger-import</i> tries to avoid duplicating transactions.<br><br><b>--infer-rules</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempt to infer import rules from the input data. This can help in generating a starting point for a rules file (experimental).<br><br><b>--write-rules-file=<i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Write inferred rules to the specified file. Useful when combined with <b>--infer-rules</b>.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show more detailed output, including debug information about the parsing process.<br><br><b>--rules=<i>TEXT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provide import rules directly as a string on the command line instead of from a file.<br><br><b>--data=<i>TEXT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provide input data directly as a string on the command line instead of from a file.<br><br>


title: DESCRIPTION
content:
<i>hledger-import</i> is a crucial utility within the <i>hledger</i> plaintext accounting system.<br>It streamlines the process of importing financial transactions from various external data sources, such as CSV, OFX, and QIF files, directly into your <i>hledger</i> journal. The command operates by applying a set of user-defined rules, typically specified in a <i>.rules</i> file, to parse and transform the raw financial data.<br>These rules dictate how to identify transaction dates, amounts, descriptions, and assign accounts, enabling highly customized and repeatable import workflows. It supports both interactive modes for manual review and adjustment, and fully automatic modes for batch processing, significantly reducing the effort of manual data entry and ensuring data consistency in your financial records.


title: CAVEATS
content:
Effective use of <i>hledger-import</i> heavily relies on well-crafted <i>.rules</i> files, which can have a significant learning curve.<br>These rules are crucial for correctly parsing diverse financial data formats and mapping them to your desired <i>hledger</i> accounts. Be mindful of potential data inconsistencies from source files, which may require rule adjustments or manual intervention to ensure accurate financial records.


title: RULES FILE (<I>.RULES</I>) FORMAT
content:
The power of <i>hledger-import</i> lies in its declarative rules files. A rules file contains directives that instruct <i>hledger-import</i> how to parse specific data files.<br>Rules define patterns to match lines in the input data (e.g., CSV columns, OFX fields), extract relevant information like date, amount, description, and assign them to <i>hledger</i> entries. They also specify posting accounts, commodities, and apply transformations or conditions to automate account assignments.<br>This allows for highly flexible and automated categorization of transactions.


title: INTERACTIVE VS. AUTOMATIC MODES
content:
When running <i>hledger-import</i>, you can choose between interactive and automatic modes.<br>In <i>interactive mode</i> (default, or with <b>-i</b>), the command will prompt you for confirmation or allow you to edit each proposed transaction before adding it to your journal. This is useful for initial setup or when dealing with unfamiliar transactions.<br>In <i>automatic mode</i> (with <b>-a</b> or <b>--add</b>), <i>hledger-import</i> processes transactions without user intervention, relying entirely on the defined rules. This is ideal for batch processing recurring imports once your rules are well-tested.


title: HISTORY
content:
<i>hledger-import</i> is an integral part of the <i>hledger</i> project, an open-source plain text accounting system. <i>hledger</i> itself was created by Simon Michael around 2008 as a modern, Haskell-based alternative to the original <i>Ledger</i> command-line accounting tool.<br>Over the years, <i>hledger-import</i> has evolved significantly, adding support for various data formats (CSV, OFX, QIF) and sophisticated rule-based parsing, becoming a cornerstone for automating transaction workflows for its users.


title: PARAMETERS
content:
<b><b>-f</b> <i>FILE</i>, <b>--file=</b><i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the <i>hledger</i> journal file to use.<br><br><b><b>-b</b> <i>DATE</i>, <b>--begin=</b><i>DATE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the start date for the report period (e.g., '2023-01-01').<br><br><b><b>-e</b> <i>DATE</i>, <b>--end=</b><i>DATE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the end date for the report period (e.g., '2023-12-31').<br><br><b><b>-p</b> <i>PERIOD</i>, <b>--period=</b><i>PERIOD</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines a common period for the report (e.g., 'last month', 'this year'). Overrides <b>-b</b> and <b>-e</b>.<br><br><b><b>-D</b>, <b>--daily</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Segments the report by daily intervals.<br><br><b><b>-W</b>, <b>--weekly</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Segments the report by weekly intervals.<br><br><b><b>-M</b>, <b>--monthly</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Segments the report by monthly intervals.<br><br><b><b>-Q</b>, <b>--quarterly</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Segments the report by quarterly intervals.<br><br><b><b>-Y</b>, <b>--yearly</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Segments the report by yearly intervals.<br><br><b><b>-s</b>, <b>--subaccounts</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays individual subaccounts rather than consolidating them into their parent accounts.<br><br><b><b>-T</b>, <b>--tree</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Presents accounts in a hierarchical tree structure, reflecting their parent-child relationships.<br><br><b><b>--depth=</b><i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limits the displayed depth of the account tree when used with <b>--tree</b>.<br><br><b><b>-t</b>, <b>--add-total</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a final total line, typically showing the net profit/loss for the period.<br><br><b><b>--layout=</b><i>LAYOUT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output layout. Common values include 'wide', 'narrow', or 'compact'.<br><br><b><b>--net-profit-only</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays only the final net profit/loss total, suppressing detailed income and expense lines.<br><br><b><b>--income-first</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Orders the report to display income accounts before expense accounts (this is the default behavior).<br><br><b><b>--expenses-first</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Orders the report to display expense accounts before income accounts.<br><br><b><i>ACCOUNT_QUERY</i>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more regular expressions to filter which accounts are included in the report. For example, <i>^income</i> to show only income accounts, or <i>Travel</i> to show only travel-related expenses.<br><br>


title: DESCRIPTION
content:
The <i>hledger-incomestatement</i> command, typically an alias for <i>hledger income</i>, produces a financial report that summarizes an entity's revenues, expenses, and net profit or loss over a specific period. It is a crucial tool for understanding financial performance by showing how much money was earned and spent during a reporting interval.<br><br>This command works by aggregating all transactions posted to accounts designated as 'Income' and 'Expenses' within your <i>hledger</i> plain-text journal file. Users can specify various parameters such as date ranges, reporting periodicity (daily, monthly, yearly), and account filtering to tailor the report. The output typically displays a hierarchical breakdown of income sources and expense categories, culminating in a calculation of the net profit or loss.<br><br>It's an essential report for budgeting, financial analysis, and decision-making, allowing users to quickly assess profitability and identify areas of spending or income trends within their financial records managed by <i>hledger</i>.


title: CAVEATS
content:
The command <i>hledger-incomestatement</i> is primarily a shell alias or wrapper script for the core <i>hledger income</i> command. Its functionality is identical to <i>hledger income</i>. For accurate reporting, it relies on a well-structured <i>hledger</i> journal where income and expense accounts are clearly defined (typically as top-level 'Income' and 'Expenses' accounts). This report provides a cash-basis view unless specific accrual entries are manually recorded. Accuracy is entirely dependent on the correctness and completeness of your journal entries.<br><br>Keep in mind that <i>hledger</i>'s income statement focuses purely on income and expense accounts, not assets, liabilities, or equity, which are covered by other reports like the balance sheet.


title: TYPICAL ACCOUNT STRUCTURE
content:
For <i>hledger</i> to correctly generate an income statement, your journal accounts should follow a hierarchical structure. Typically, accounts relevant to the income statement begin with 'Income' or 'Expenses'. For example:<br><br><i>Income:Salary</i><br><i>Income:Investments</i><br><i>Expenses:Rent</i><br><i>Expenses:Groceries</i><br><i>Expenses:Utilities:Electricity</i><br><br>The command automatically identifies these top-level accounts and aggregates their subaccounts accordingly.


title: EXAMPLE USAGE
content:
To view your income statement for the current year, broken down monthly, with a total line and subaccounts:<br><br><b>hledger-incomestatement --monthly --add-total --subaccounts -p 'this year'</b><br><br>To see only the net profit for the last fiscal quarter:<br><br><b>hledger-incomestatement --net-profit-only -p 'last quarter'</b><br><br>To view expenses only for a specific account, like 'Travel', for all time:<br><br><b>hledger-incomestatement ^Expenses:Travel</b>


title: HISTORY
content:
<i>hledger</i> is a modern, free software project implemented in Haskell, inspired by the venerable <i>ledger</i> command-line accounting system. Developed with a focus on plain-text accounting principles, <i>hledger</i> aims to provide a robust, flexible, and user-friendly tool for personal and small business finance.<br><br>The income statement report, being a fundamental financial statement, was a core feature integrated into <i>hledger</i> from its early development. Its continuous refinement mirrors <i>hledger</i>'s ongoing improvements in parsing, reporting, and user experience, ensuring it remains an accurate and powerful tool for financial performance analysis.


title: PARAMETERS
content:
<b><I>FILE</I>, <I>-f FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the journal file(s) to load. Defaults to `~/.hledger.journal` or `hledger.journal`.<br><br><b><I>-p PORT</I>, <I>--port=PORT</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the port for the local web server to listen on. Default is usually 5000.<br><br><b><I>--host=HOST</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the host address for the server to bind to (e.g., `127.0.0.1` for local access).<br><br><b><I>--no-browser</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents <b>hledger-ui</b> from automatically opening a web browser after starting the server.<br><br><b><I>--refresh</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables automatic reloading of data in the UI when the journal files are modified.<br><br><b><I>--server</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs the web server continuously in server mode without exiting after initial requests.<br><br><b><I>QUERY</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A query string to pre-filter transactions or reports displayed in the UI (e.g., `account:expenses`).<br><br>


title: DESCRIPTION
content:
hledger-ui offers a user-friendly, web-based interface for <b>hledger</b>, the robust plain text accounting system. It significantly simplifies the process of interacting with your financial data by abstracting away the intricacies of command-line operations. When invoked, hledger-ui launches a local web server, primarily utilizing <b>hledger-web</b>, and subsequently opens your default web browser to the interface. This setup enables users to effortlessly browse transactions, generate and view various financial reports—such as detailed balances, income and expense statements—and apply powerful filters to their data using intuitive web controls. This tool is specifically designed to make <b>hledger</b> more accessible to individuals who prefer a graphical environment or wish to quickly review their finances without needing to memorize and type numerous <b>hledger</b> command-line arguments. It acts as a powerful, accessible graphical layer over <b>hledger</b>'s robust text-based accounting engine.


title: CAVEATS
content:
Requires both <b>hledger</b> and <b>hledger-web</b> executables to be installed and accessible in the system's PATH.<br>Runs a local web server, which consumes system resources while active.<br>Primarily designed for local, personal use; exposing it to the internet without robust security measures is not recommended.<br>The web interface might not expose every advanced or niche feature available directly via <b>hledger</b>'s command-line interface.


title: DEFAULT PORT AND ACCESS
content:
By default, <b>hledger-ui</b> typically starts its web server on <b>localhost:5000</b> (or the next available port) and attempts to automatically open your default web browser to this address. If the <b>--no-browser</b> option is used, you will need to manually navigate to the displayed URL in your browser.


title: CONFIGURATION
content:
While command-line arguments configure specific runs, many global <b>hledger</b> settings, such as default journal file location, default currency, and display preferences, are managed through <b>hledger</b>'s configuration files (e.g., <I>~/.hledger.journal</I> or <I>hledger.conf</I>).


title: HISTORY
content:
The <b>hledger</b> project, inspired by the <b>Ledger</b> command-line accounting tool, began its development in the early 2000s. As <b>hledger</b> grew in capability, the need for a more accessible, graphical interface became apparent. <b>hledger-web</b> was developed to provide the underlying web server component, and <b>hledger-ui</b> emerged as a convenient wrapper script to easily launch and interact with this web interface. This evolution allowed <b>hledger</b> to reach a broader audience, complementing its powerful text-based core with a user-friendly visual layer.


title: PARAMETERS
content:
<b>-f FILE, --file=FILE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the <i>journal file(s)</i> to load. Multiple <b>-f</b> or <b>--file</b> options can be provided to load several files.<br><br><b>-p PORT, --port=PORT</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the TCP port for the web server to listen on. The default port is <i>5000</i>.<br><br><b>--serve-dir=DIR</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a directory from which static files (e.g., CSS, JS) should be served alongside the web interface.<br><br><b>--rules-file=FILE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Loads a <i>rules file</i> to apply transformations to transactions during import or parsing.<br><br><b>--no-browser</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents <b>hledger-web</b> from automatically opening a web browser when it starts.<br><br><b>--base-url=URL</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the base URL for all links generated by the web interface. Useful when running behind a reverse proxy.<br><br><b>--access-log=FILE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a file to which HTTP access logs will be written.<br><br><b>--error-log=FILE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a file to which server error logs will be written.<br><br><b>--cors-origin=ORIGIN</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables Cross-Origin Resource Sharing (CORS) for requests originating from the specified domain.<br><br><b>--web-dir=DIR</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the directory containing <b>hledger-web</b>'s own static assets (e.g., its default HTML, CSS, JS).<br><br><b>--debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables debug mode, providing more verbose logging and potentially aiding in troubleshooting issues.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message with available command-line options and exits.<br><br><b>-v, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the version information of <b>hledger-web</b> and exits.<br><br>


title: DESCRIPTION
content:
<b>hledger-web</b> is the official web user interface for <b>hledger</b>, a powerful plain-text accounting system. It provides a convenient way to view, analyze, and manage your financial transactions through a modern web browser. Users can explore balances, generate reports, view register entries, and even add new transactions via an intuitive HTML interface. By default, it serves content on <i>http://localhost:5000</i> and automatically attempts to open a browser window to this address. It's a key component for users who prefer a graphical interface over the command-line for their <b>hledger</b> workflow, making financial data more accessible and interactive.


title: CAVEATS
content:
<ul><li><b>Security</b>: <b>hledger-web</b> does <i>not</i> provide built-in authentication or encryption (HTTPS). It is generally intended for local use or behind a secure reverse proxy that handles authentication and SSL/TLS. Exposing it directly to the internet without proper security measures is strongly discouraged.<br></li><li><b>Dependencies</b>: Requires a working <b>hledger</b> installation to parse journal files and perform calculations.<br></li><li><b>Journal Format</b>: Relies on the strict plain-text accounting format of <b>hledger</b> journal files. Malformed files may lead to errors or unexpected behavior.</li></ul>


title: DEFAULT BEHAVIOR
content:
By default, <b>hledger-web</b> listens on <i>localhost:5000</i> and automatically attempts to open your default web browser to this address upon startup.


title: EXTENSIBILITY
content:
While primarily a viewer, <b>hledger-web</b> allows basic transaction entry and can be customized by serving custom static files or integrating with other tools via its base URL option.


title: PLAIN TEXT FOCUS
content:
Despite being a web interface, <b>hledger-web</b> adheres to <b>hledger</b>'s core philosophy of plain-text accounting, ensuring your financial data remains in a human-readable, auditable format, stored directly in your journal files.


title: HISTORY
content:
<b>hledger-web</b> emerged as a key component of the <b>hledger</b> ecosystem, which began as a Haskell-based re-implementation of the popular <b>ledger</b> command-line accounting system. The <b>hledger</b> project, initiated by Simon Michael, aimed to provide a robust, cross-platform, and extensible plain-text accounting solution. Recognizing the growing demand for graphical interfaces, <b>hledger-web</b> was developed to offer an accessible browser-based UI, broadening <b>hledger</b>'s appeal beyond command-line enthusiasts. Its development has closely paralleled that of the core <b>hledger</b> tool, continuously adding features and improving usability for web-centric financial management.


title: DESCRIPTION
content:
The 'hn' command is not a standard utility found in common Linux distributions (e.g., Debian, Ubuntu, Fedora, CentOS, Arch Linux) or their core package repositories. Unlike widely recognized commands such as 'ls', 'cd', or 'grep', 'hn' does not have a predefined, universal purpose or syntax.<br><br> If you've encountered 'hn', it's highly likely to be one of the following:<br> <br>1. <b>A custom alias or shell function:</b> Many users or system administrators create short aliases for frequently used or complex commands (e.g., 'alias hn='hostname'').<br>2. <b>A custom script:</b> A shell script or program named 'hn' might have been placed in a directory included in the system's PATH variable.<br>3. <b>Part of a niche application:</b> A specific, less common software package might include a command named 'hn'.<br>4. <b>A typo:</b> It could be a mistyped version of a standard command (e.g., 'hostname', 'head -n').<br><br>Without specific context about its origin or environment, it's impossible to provide a definitive analysis of its intended functionality, parameters, or behavior. Users should exercise caution if running an unknown command.


title: CAVEATS
content:
Since 'hn' is not a standard Linux command, its behavior, existence, and any potential side effects are entirely dependent on how it was implemented in a specific environment. There are no general guarantees or standard practices for its use. Running unknown commands can pose security risks or lead to unintended system modifications. Always verify the source and purpose of non-standard commands before execution.


title: IDENTIFYING 'HN'
content:
If you encounter 'hn' and need to understand its origin, you can try the following commands in your terminal:<br> 1. <b>'type hn'</b>: This command will tell you if 'hn' is an alias, a shell function, or an executable file.<br> 2. <b>'which hn'</b>: If it's an executable, this will show its full path.<br> 3. <b>'ls -l $(which hn)'</b>: If it's a script, you can then inspect its contents (e.g., using 'cat' or 'less') to understand what it does.<br> 4. <b>'man hn'</b>: While unlikely for a non-standard command, it's worth checking if a local manual page exists for it.


title: HISTORY
content:
There is no documented history or development timeline for a standard 'hn' command within the Linux ecosystem, as it is not part of any widely recognized standard or distribution set of utilities.


title: PARAMETERS
content:
<b>&lt;<i>email_address</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The target email address to check for registration status across various online services.<br><br><b><b>--input-file</b> &lt;<i>file</i>&gt;, <b>-i</b> &lt;<i>file</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Read email addresses from a specified <i>file</i>, one email per line, for batch processing.<br><br><b><b>--verbose</b>, <b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display verbose output, providing more detailed information during the checking process, including service responses.<br><br><b><b>--json</b>, <b>-j</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output the results in JSON format, suitable for programmatic parsing and integration with other tools.<br><br><b><b>--only-used</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filter results to only display services where the email address is confirmed as <i>registered</i>.<br><br><b><b>--only-unused</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filter results to only display services where the email address is confirmed as <i>not registered</i>.<br><br><b><b>--only-unknown</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filter results to only display services where the registration status of the email address is <i>unknown</i>.<br><br><b><b>--no-color</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable colored output in the terminal, useful for non-interactive scripts or terminals that don't support ANSI colors.<br><br><b><b>--timeout</b> &lt;<i>seconds</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set a maximum <i>timeout</i> in seconds for individual network requests to services, preventing long hangs.<br><br><b><b>--proxy</b> &lt;<i>url</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use a specified <i>proxy</i> URL (e.g., <i>socks5://127.0.0.1:9050</i>, <i>http://user:pass@host:port</i>) for all network requests.<br><br><b><b>--version</b>, <b>-V</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the program's version number and exit.<br><br><b><b>--help</b>, <b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the help message and exit, showing available options and usage examples.<br><br>


title: DESCRIPTION
content:
<i>holehe</i> is an open-source intelligence (OSINT) command-line tool designed to check if a given email address is registered on a vast array of online services. It leverages various service APIs and public data points to verify email existence without requiring credentials. This allows investigators, security researchers, or curious individuals to rapidly ascertain a digital footprint associated with an email, potentially revealing social media profiles, e-commerce accounts, or other online presences.<br><br>It supports a wide range of popular services, including but not limited to, Instagram, Twitter, Facebook, TikTok, Spotify, Netflix, Adobe, and many more, making it a powerful reconnaissance utility. Its primary use case is ethical hacking, penetration testing, and digital forensics, helping to build a comprehensive profile of a target.


title: CAVEATS
content:
<b>Ethical Use</b>: <i>holehe</i> should only be used for legitimate and ethical purposes, such as security research, verifying your own data, or with explicit consent. Misuse can lead to privacy violations and legal consequences.<br><b>Rate Limiting & Accuracy</b>: Online services may implement rate limiting, which can cause the tool to temporarily fail or get blocked. The accuracy of results depends on the services' public APIs and how they handle registration checks, which can change over time or be intentionally obscured.<br><b>Dependencies</b>: Requires Python 3 and specific Python packages to be installed. It also requires an active internet connection to perform checks.


title: INSTALLATION
content:
<i>holehe</i> is typically installed using Python's package installer, pip. Ensure Python 3 and pip are installed on your system. You can install it by running: <br><code>pip3 install holehe</code>


title: ETHICAL CONSIDERATIONS
content:
Users are strongly advised to exercise caution and adhere to ethical guidelines when using <i>holehe</i>. Respect individual privacy, comply with all applicable laws and regulations, and obtain consent where necessary. This tool is intended for legitimate security research and auditing, not for malicious activities or unauthorized data collection.


title: HISTORY
content:
<i>holehe</i> was developed by @megadose as a Python-based open-source intelligence (OSINT) tool. Its creation aimed to streamline the process of checking email registration across a multitude of online platforms into a single, user-friendly command-line utility. Since its initial release, it has gained significant traction within the cybersecurity and OSINT communities for its effectiveness in reconnaissance and digital footprint analysis. The tool continues to evolve with updates, adding support for new services and features to enhance its utility and maintain accuracy against changing platform behaviors.


title: SYNOPSIS
content:
<b>home-manager</b> [<I>global-options</I>] <I>command</I> [<I>command-options</I>] [<I>arguments</I>]<br><br>Common commands:<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>home-manager</b> <I>switch</I> [--<I>flake</I> <I>uri</I>]<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>home-manager</b> <I>generations</I> [<I>subcommand</I>]<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>home-manager</b> <I>update</I>


title: PARAMETERS
content:
<b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Displays help information for the command or subcommand.</I><br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Prints the home-manager version number.</I><br><br><b><b>--flake</b> <I>uri</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specifies a Nix flake URI (e.g., 'path:./#home-manager') to use for the configuration, enabling a more modern and reproducible setup.</I><br><br><b><b>--impure</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Allows the build to access external files or the network, making it "impure" and potentially less reproducible.</I><br><br><b><b>--dry-run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Performs a trial run without making any actual changes to the system, showing what would happen.</I><br><br><b><b>--show-trace</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Shows a stack trace on Nix evaluation errors, aiding in debugging configuration issues.</I><br><br><b><b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Increases the verbosity of the output, providing more detailed information about the operation.</I><br><br><b><b>-f</b> <I>file</I>, <b>--file</b> <I>file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specifies the home-manager configuration file to use. Default is typically 'home.nix' or specified via flake inputs.</I><br><br><b><b>--no-warn-extra-config</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Disables warnings about extra configuration options found in the system-wide Nix configuration.</I><br><br>


title: DESCRIPTION
content:
<b>home-manager</b> is a powerful tool built on top of the Nix package manager, designed to declaratively manage a user's home directory configuration and installed packages. Unlike traditional methods of managing dotfiles and user-specific software (e.g., symlinks, manual installations), <b>home-manager</b> provides a reproducible and atomic way to define your entire user environment using Nix expressions. This means you can specify your shell configuration (bash, zsh, fish), text editor setups (Neovim, Emacs), desktop applications, user-level services, and even environment variables in a single, version-controlled configuration file.<br><br>It leverages Nix's atomic upgrades and rollbacks, allowing you to switch between configurations safely or revert to a previous working state if issues arise. <b>home-manager</b> can be used standalone on any Linux distribution (requiring only Nix to be installed) or integrated seamlessly with NixOS, complementing the system-wide configuration. Its primary goal is to make managing your personal computing environment reproducible, portable, and easy to share across multiple machines or with other users. By defining your home configuration declaratively, you gain confidence that your setup will be consistent regardless of the underlying system, simplifying setup for new machines and ensuring consistency over time.


title: CAVEATS
content:
The learning curve for Nix and its functional programming paradigm can be steep for new users, requiring time to understand declarative configurations and the Nix language. <br>Initial builds and significant configuration changes can be resource-intensive due to Nix's atomic and reproducible build processes. <br>Debugging complex <b>home-manager</b> configurations sometimes requires a deep understanding of Nix evaluation and error traces. <br>While powerful, its dependency on the Nix ecosystem means users must manage Nix channels or flake inputs, ensuring they are kept up-to-date for consistent and secure environments.


title: <B>DECLARATIVE CONFIGURATION</B>
content:
<I><b>home-manager</b> embodies the principle of declarative configuration, where the desired state of the user's environment is specified in a Nix expression, rather than a sequence of imperative commands. This approach ensures reproducibility and consistency across different machines, as the configuration describes "what" the environment should be, not "how" to achieve it.</I>


title: <B>ATOMIC UPGRADES AND ROLLBACKS</B>
content:
<I>Leveraging the capabilities of the Nix package manager, <b>home-manager</b> performs atomic upgrades and rollbacks. Each activation of a new configuration creates a new "generation" in the Nix store. If a new configuration causes issues, users can instantly revert to a previous, known-working generation, significantly reducing the risk of broken environments.</I>


title: HISTORY
content:
<b>home-manager</b> emerged from the Nix and NixOS community as a solution to the challenge of managing user-level configurations in a reproducible and declarative manner, similar to how NixOS manages system-wide configurations. Initially, users would often try to manage dotfiles manually or with simpler tools, which lacked the atomic updates and rollbacks provided by Nix. <b>home-manager</b> filled this gap by leveraging Nix's powerful functional package management capabilities to build and manage user environments from declarative specifications. Its development has been driven by the Nix community, evolving alongside Nix itself, with significant advancements particularly in integrating with the modern Nix "flakes" system, which further enhances reproducibility and ease of sharing configurations. It has become an essential tool for many NixOS users and those on other Linux distributions seeking a robust, portable, and version-controlled way to manage their personal computing setup.


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><br>&nbsp;&nbsp;&nbsp;&nbsp;Show version information and exit.<br><br><b><b>--json</b>=<i>pretty</i>|<i>short</i>|<i>off</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Control JSON output format for machine-readable data.<br><br><b><b>--root</b>=<i>PATH</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Operate on a specified root directory instead of the system's default.<br><br><b><b>--no-pager</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not pipe output into a pager.<br><br><b><b>--dry-run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show what would be done without actually making changes.<br><br><b><b>--no-ask-password</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not ask for user password interactively when creating/updating. Requires password to be passed via properties or environment.<br><br><b><b>status</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the current status of the <b>systemd-homed.service</b> and managed users.<br><br><b><b>create</b> <i>USER</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Create a new user account managed by <b>systemd-homed</b>.<br><br><b><b>remove</b> <i>USER</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remove a user account and their home directory.<br><br><b><b>activate</b> <i>USER</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Activate (mount) a user's home directory. This is usually done automatically on login.<br><br><b><b>deactivate</b> <i>USER</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deactivate (unmount) a user's home directory. This is usually done automatically on logout.<br><br><b><b>update</b> <i>USER</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Update properties of an existing user account (e.g., password, full name, shell).<br><br><b><b>password</b> <i>USER</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Change the password for a user account.<br><br><b><b>inspect</b> <i>USER</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display properties and details of a user account.<br><br><b><b>resize</b> <i>USER</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Resize the image file used for a user's home directory.<br><br><b><b>import</b> <i>PATH</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Import a user account from an exported file.<br><br><b><b>export</b> <i>USER</i> <i>PATH</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Export a user account and its data to a specified file.<br><br>


title: DESCRIPTION
content:
<i>homectl</i> is a command-line utility used to create, manage, and inspect user accounts and their associated home directories when managed by the <b>systemd-homed.service</b>. It provides a modern approach to user and home directory management, supporting features like encrypted home directories (often using LUKS), stateless setups, and various authentication methods such as FIDO2, PKCS#11, and traditional passwords.<br><br>The tool allows administrators to perform operations like creating new users, activating/deactivating home directories, changing user passwords, resizing home directory images, importing/exporting user accounts, and inspecting user properties. It's designed to simplify the complexities of secure and flexible home directory management in contemporary Linux environments.


title: CAVEATS
content:
<i>homectl</i> relies on the <b>systemd-homed.service</b> to be running and enabled. It manages user accounts differently from traditional methods like <b>useradd</b>/<b>usermod</b>, focusing on encrypted and ephemeral home directories. Not all system users are managed by <b>systemd-homed</b>, only those specifically configured for it. Errors in managing encryption keys or image files can lead to data loss or inaccessibility.


title: HOME DIRECTORY ENCRYPTION
content:
By default, <i>systemd-homed</i> (and thus <i>homectl</i>) manages home directories as LUKS-encrypted disk images. This provides a high level of security by encrypting the entire home directory contents at rest. User passwords, FIDO2 devices, or PKCS#11 tokens are used to unlock these encrypted images during login.


title: NSS INTEGRATION
content:
Users managed by <i>systemd-homed</i> are exposed to the system via the Name Service Switch (NSS) through the <b>nss-systemd</b> module. This allows standard system tools and applications to recognize and interact with <i>homed</i>-managed users, ensuring compatibility with existing Linux infrastructure while leveraging <i>homed</i>'s advanced features.


title: HISTORY
content:
<i>homectl</i> was introduced as part of the <b>systemd-homed</b> project with <b>systemd</b> version 245, released in early 2020. Its development aimed to address modern challenges in user management, such as secure handling of sensitive user data, supporting stateless systems, and integrating with advanced authentication mechanisms like FIDO2/PKCS#11. It represents a significant evolution in how user accounts and their associated home directories can be managed within the systemd ecosystem.


title: PARAMETERS
content:
<b><b>clone</b> <i>&lt;repo_url&gt;</i> [<i>&lt;castle_name&gt;</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Clones a Git repository as a new 'castle' into <i>homeshick</i>'s managed directory. If <i>&lt;castle_name&gt;</i> is omitted, it defaults to the repository's name.<br><br><b><b>pull</b> [<i>&lt;castle&gt;</i> ...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pulls the latest changes from the remote repository for the specified 'castle(s)'. If no 'castle' is specified, it pulls for all managed castles.<br><br><b><b>push</b> [<i>&lt;castle&gt;</i> ...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pushes local changes to the remote repository for the specified 'castle(s)'. If no 'castle' is specified, it pushes for all managed castles.<br><br><b><b>status</b> [<i>&lt;castle&gt;</i> ...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the Git status (e.g., uncommitted changes, untracked files) for the specified 'castle(s)'. If no 'castle' is specified, it shows status for all managed castles.<br><br><b><b>track</b> <i>&lt;file&gt;</i> [<i>&lt;file&gt;</i> ...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Moves an existing file from your home directory into its respective 'castle' and creates a symbolic link back to the original location. This marks the file for <i>homeshick</i> management.<br><br><b><b>link</b> [<i>&lt;castle&gt;</i> ...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates or re-establishes symbolic links from the specified 'castle(s)' to your home directory. If no 'castle' is specified, it links all managed castles.<br><br><b><b>list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all 'castles' currently managed by <i>homeshick</i>.<br><br><b><b>generate</b> <i>&lt;castle_name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a new, empty 'castle' (Git repository) ready for you to add dotfiles to it.<br><br><b><b>refresh</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Checks and re-establishes all symbolic links from all managed 'castles' to the home directory, ensuring consistency.<br><br><b><b>cd</b> <i>&lt;castle&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Changes the current directory into the specified 'castle's' repository.<br><br><b><b>shell</b> <i>&lt;command&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes an arbitrary shell command within each of your managed 'castles'.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output, showing more details about operations.<br><br><b><b>-q</b>, <b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress output, making operations quiet.<br><br><b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force operations, such as overwriting existing files during linking.<br><br><b><b>-n</b>, <b>--dry-run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform a trial run with no changes made, showing what would happen.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display help information for <i>homeshick</i> or a specific command.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the <i>homeshick</i> version.<br><br>


title: DESCRIPTION
content:
<i>Homeshick</i> is a lightweight and easy-to-use dotfile manager built on Git. It helps you manage your configuration files (dotfiles like .bashrc, .vimrc, .gitconfig) by storing them in Git repositories, which it calls 'castles'. Instead of scattering your dotfiles directly in your home directory, <i>homeshick</i> clones them into a hidden directory (e.g., <code>~/.homesick/repos/</code>) and then creates symbolic links from those 'castles' back to your home directory.<br><br>This approach allows you to keep your dotfiles version-controlled, synchronized across multiple machines, and easily shareable. It leverages Git for all the heavy lifting (pulling, pushing, branching, diffing), making it familiar for Git users. Being written purely in Bash, <i>homeshick</i> has minimal dependencies, making it highly portable and efficient for managing personal configurations.


title: CAVEATS
content:
<i>Homeshick</i> relies heavily on Git; therefore, Git must be installed and properly configured on your system. While it simplifies dotfile management, users should still have a basic understanding of Git commands for advanced operations or troubleshooting. It's primarily designed for Unix-like systems (Linux, macOS) and may not behave as expected on Windows environments without WSL or similar layers. Be cautious when using the <b>--force</b> option, as it can overwrite existing files in your home directory.


title: WHAT ARE 'CASTLES'?
content:
In <i>homeshick</i> terminology, a 'castle' refers to a Git repository that contains your dotfiles. These repositories are typically stored under <code>~/.homesick/repos/</code>. Each 'castle' can contain a collection of related configuration files, allowing you to organize your dotfiles logically (e.g., one castle for general shell configs, another for Vim, etc.).


title: HOW SYMLINKING WORKS
content:
When you manage dotfiles with <i>homeshick</i>, the original files are moved into their respective 'castles' within the <code>~/.homesick/repos/</code> directory. <i>Homeshick</i> then creates symbolic links (symlinks) from these locations back to where the applications expect them to be (e.g., <code>~/.bashrc</code> links to <code>~/.homesick/repos/my-shell-castle/bashrc</code>). This ensures applications find their configuration files while keeping the actual files version-controlled and neatly organized within the 'castles'.


title: HISTORY
content:
<i>Homeshick</i> was created by Lars H. Nielsen as a simple alternative for managing dotfiles, aiming for a tool that was easy to use, understood Git principles, and required minimal dependencies. It gained popularity for its straightforward Bash-based implementation, which makes it highly portable and robust for Unix-like systems. Its development has focused on maintaining simplicity and leveraging Git's power without over-complicating the user experience.


title: SYNOPSIS
content:
<B>host</B> [<I>options</I>] <I>name</I> [<I>server</I>]<br><br><I>name</I> can be a hostname or an IP address.<br><I>server</I> is an optional DNS server to query instead of the default configured ones.


title: PARAMETERS
content:
<b>-a</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<B>a</B>ll records. Equivalent to <B>-t ANY</B>.<br><br><b>-C</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Compare SOA records on authoritative name servers.<br><br><b>-d</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable <B>d</B>ebugging output.<br><br><b>-i</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display only the <B>i</B>P addresses in reverse lookups.<br><br><b>-l</b><br>&nbsp;&nbsp;&nbsp;&nbsp;List all hosts in a domain (zone transfer). Requires the name server to allow AXFR.<br><br><b>-N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not perform <B>N</B>on-authoritative lookups.<br><br><b>-r</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not use <B>r</B>ecursion.<br><br><b>-s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<B>s</B>imple output, terse.<br><br><b>-t <I>type</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Query for a specific record <B>t</B>ype (e.g., A, MX, NS, SOA, PTR, AAAA, ANY).<br><br><b>-T</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use <B>T</B>CP for queries instead of UDP.<br><br><b>-U</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use <B>U</B>DP for queries (default).<br><br><b>-v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable <B>v</B>erbose output.<br><br><b>-V</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the <B>V</B>ersion information and exit.<br><br><b>-w</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<B>w</B>ait indefinitely for a reply.<br><br><b>-W <I>time</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<B>W</B>ait for <I>time</I> seconds before timing out (default 5 seconds).<br><br><b>-4</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use IPv<B>4</B> only.<br><br><b>-6</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use IPv<B>6</B> only.<br><br>


title: DESCRIPTION
content:
The <I>host</I> command is a simple command-line utility used for performing DNS lookups. It translates hostnames to IP addresses (forward lookups) and IP addresses to hostnames (reverse lookups). It can query for various DNS record types, including A (address), AAAA (IPv6 address), MX (mail exchange), NS (name server), SOA (start of authority), and PTR (pointer). It's often preferred for quick, interactive lookups due to its clean and concise output format, making it easier to parse than tools like <I>dig</I> for simple queries.


title: CAVEATS
content:
<br>The output of <I>host</I> is generally less detailed than <I>dig</I>, which can be a limitation for complex DNS troubleshooting.<br>Performing zone transfers (<B>-l</B> option) may be blocked by DNS servers for security reasons.<br>For reverse lookups (IP to hostname), the reliability depends on proper PTR record configuration by the owner of the IP address block.


title: DEFAULT BEHAVIOR
content:
When invoked without a specific query type (<B>-t</B>), <I>host</I> attempts to resolve the name to an A record (IPv4 address) or AAAA record (IPv6 address). If the input is an IP address, it performs a reverse PTR lookup by default.


title: SERVER SPECIFICATION
content:
You can specify a particular DNS server to query by providing its IP address or hostname as the last argument, for example: <B>host example.com 8.8.8.8</B>. This is useful for testing specific DNS servers or for querying internal DNS zones.


title: HISTORY
content:
<br>The <I>host</I> command is part of the BIND (Berkeley Internet Name Domain) tools distribution, which is the most widely used DNS software on the internet. It was developed to provide a simpler alternative to <I>nslookup</I> and <I>dig</I> for common DNS query tasks, offering a more user-friendly output format for quick lookups. Its development has focused on reliability and ease of use for basic DNS diagnostics.


title: PARAMETERS
content:
<b><b>-B</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run <i>hostapd</i> in the background as a daemon.<br><br><b><b>-d</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable debugging messages. Use <b>-dd</b> for more verbose output.<br><br><b><b>-K</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Include key information in debug messages (use with caution in production).<br><br><b><b>-P</b> <I>pid_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Write the daemon's process ID (PID) to the specified file.<br><br><b><b>-e</b> <I>entropy_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Read and write entropy from/to the specified file, improving randomness.<br><br><b><b>-f</b> <I>debug_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Redirect all debugging output to the specified file instead of standard output.<br><br><b><b>-t</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Include timestamps in debug messages.<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the version information and exit.<br><br><b><b>-u</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable the internal privilege separation mechanism.<br><br><b><b>-q</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable quiet mode, reducing output to essential messages only.<br><br><b><b>-g</b> <I>control_interface</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a global control interface for external control programs.<br><br><b><I>configuration_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the mandatory configuration file (e.g., <i>/etc/hostapd/hostapd.conf</i>) that defines the AP's settings.<br><br>


title: DESCRIPTION
content:
<i>hostapd</i> is a userspace daemon that enables a wireless network interface card (WNIC) to act as an access point (AP) and authentication server.<br><br>It implements the IEEE 802.11 AP management, IEEE 802.1X/RADIUS authentication, and supports WPA, WPA2, and WPA3 security protocols. <i>hostapd</i> is crucial for setting up a functional Wi-Fi hotspot or access point on a Linux system, handling key exchange, authentication, and association for wireless clients.<br><br>It works with various wireless drivers, most commonly the <I>nl80211</I> driver, which is part of the Linux kernel's mac80211 subsystem. While <i>hostapd</i> manages the wireless AP and authentication, it typically relies on other tools like <I>dnsmasq</I> or <I>isc-dhcp-server</I> for DHCP and DNS services, and <I>iptables</I> for network address translation (NAT) and routing.


title: CAVEATS
content:
Requires a wireless adapter that supports AP (Access Point) mode, which is not universal across all Wi-Fi cards.<br><i>hostapd</i> solely manages the wireless interface and authentication; it does not handle IP addressing, DHCP, DNS, or network routing (NAT). These services must be configured separately using tools like <i>dnsmasq</i>, <i>isc-dhcp-server</i>, and <i>iptables</i>.<br>Complex configurations, especially involving advanced features like VLANs or external RADIUS servers, can be challenging and require a deep understanding of networking concepts.<br>Security is paramount. Improper configuration of WPA/WPA2/WPA3 can lead to vulnerable networks.


title: CONFIGURATION FILE
content:
The primary way to configure <i>hostapd</i> is through a text-based configuration file, typically located at <i>/etc/hostapd/hostapd.conf</i>. This file defines crucial settings such as the network interface to use, SSID (network name), operating channel, Wi-Fi security (WPA/WPA2/WPA3 passphrase or RADIUS settings), and advanced options like VLANs or client isolation. A well-configured file is essential for a functional and secure access point.


title: OPERATING MODES
content:
While its primary role is as an Access Point (AP), <i>hostapd</i> can also function as a standalone authentication server for both wireless and wired networks, utilizing RADIUS. This allows it to centralize authentication for multiple network devices or services beyond just its own Wi-Fi AP functionality. The most common use case remains its AP mode, transforming a Linux machine into a Wi-Fi hotspot.


title: HISTORY
content:
<i>hostapd</i> was primarily developed by Jouni Malinen as part of the broader <I>wpa_supplicant</I> project, which provides IEEE 802.1X/WPA/WPA2/WPA3 support for both client and access point roles. It quickly became the standard and most widely used solution for setting up Wi-Fi access points on Linux due to its comprehensive feature set, robustness, and active development.<br><br>Its development has continuously evolved to support new Wi-Fi standards (e.g., 802.11ac, 802.11ax/Wi-Fi 6, 802.11be/Wi-Fi 7) and security protocols (WPA3), making it a cornerstone for wireless networking in the Linux ecosystem.


title: SYNOPSIS
content:
<code><b>hostess</b> &lt;command&gt; [options] [arguments]</code><br><br>Common Commands:<br><code><b>hostess</b> add &lt;IP_ADDRESS&gt; &lt;HOSTNAME&gt; [HOSTNAME...]</code><br><code><b>hostess</b> rm &lt;HOSTNAME&gt; [HOSTNAME...]</code><br><code><b>hostess</b> ls</code><br><code><b>hostess</b> on &lt;HOSTNAME&gt; [HOSTNAME...]</code><br><code><b>hostess</b> off &lt;HOSTNAME&gt; [HOSTNAME...]</code>


title: PARAMETERS
content:
<b><code>add &lt;IP_ADDRESS&gt; &lt;HOSTNAME&gt; [HOSTNAME...]</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a new entry mapping <code>IP_ADDRESS</code> to one or more <code>HOSTNAME</code>s. If the IP exists, new hostnames are appended to that line.<br><br><b><code>rm &lt;HOSTNAME&gt; [HOSTNAME...]</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes one or more specific <code>HOSTNAME</code> entries from the <i>hosts</i> file. If a hostname is the last one for an IP, the entire line is removed.<br><br><b><code>ls</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all entries in the <i>hosts</i> file, indicating which are active and which are disabled (commented out).<br><br><b><code>on &lt;HOSTNAME&gt; [HOSTNAME...]</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables (uncomments) one or more previously disabled <code>HOSTNAME</code> entries, making them active for name resolution.<br><br><b><code>off &lt;HOSTNAME&gt; [HOSTNAME...]</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables (comments out) one or more specific <code>HOSTNAME</code> entries, effectively making them inactive without deleting them from the file.<br><br><b><code>-h</code>, <code>--help</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the help message and available commands for <b>hostess</b> or a specific subcommand.<br><br><b><code>-v</code>, <code>--version</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the <b>hostess</b> utility's version information.<br><br>


title: DESCRIPTION
content:
The <b>hostess</b> command is a powerful and convenient utility designed for streamlined management of the <i>/etc/hosts</i> file on Unix-like operating systems. It simplifies the common tasks associated with mapping IP addresses to hostnames, traditionally performed by manually editing the plain-text file. <b>hostess</b> provides subcommands to add, remove, list, enable, and disable entries, making it an ideal tool for developers, system administrators, or anyone who frequently modifies their local DNS mappings for development environments, ad blocking, or testing.<br><br>It handles the necessary permissions (often requiring <code>sudo</code> internally) and ensures the integrity of the <i>hosts</i> file, reducing the risk of syntax errors. By abstracting the manual editing process, <b>hostess</b> enhances productivity and reduces potential mistakes, offering a more reliable and scriptable way to manage local DNS resolution.


title: CAVEATS
content:
<b>hostess</b> is not a standard Unix command and needs to be installed separately, typically via `go get` or by downloading pre-compiled binaries. As it modifies the system-wide <i>/etc/hosts</i> file, it often requires superuser privileges (<code>sudo</code>) to execute its commands successfully. Care should be taken when making changes to avoid disrupting network resolution.


title: PERMISSIONS
content:
Commands that modify the <i>/etc/hosts</i> file (<code>add</code>, <code>rm</code>, <code>on</code>, <code>off</code>) typically require root privileges. <b>hostess</b> is often designed to prompt for <code>sudo</code> automatically if necessary, or the user may need to invoke it with <code>sudo hostess ...</code>.


title: IDEMPOTENCY
content:
Many <b>hostess</b> operations are idempotent; for example, attempting to add an existing entry or remove a non-existent one generally won't cause errors or unintended side effects, making it suitable for scripting.


title: HISTORY
content:
The <b>hostess</b> utility was primarily developed by Christian Bednarski and is written in Go. Its development aimed to provide a more ergonomic and reliable way to manage <i>/etc/hosts</i> entries programmatically or from the command line, avoiding the common pitfalls of manual file editing. It gained popularity among developers and sysadmins looking for a robust tool for local DNS manipulation, offering a structured approach to a traditionally manual process.


title: DESCRIPTION
content:
The <b>hostid</b> command in Linux is used to display the numeric identifier of the current host in hexadecimal format. This identifier is typically a 32-bit number. <br><br>Historically, this host ID was often derived from the system's primary IPv4 address, specifically the loopback address <i>127.0.0.1</i>, which translates to <i>0x7f000001</i>. <br><br>It's crucial to understand that <b>hostid</b> does <i>not</i> provide a unique identifier for a physical or virtual machine. Many systems, especially those where the host ID hasn't been explicitly configured, will report the default <i>0x7f000001</i>. For unique machine identification, other mechanisms like MAC addresses, DMI information, or system UUIDs (e.g., from <b>dmidecode</b>) are more appropriate. <br><br>The value returned by <b>hostid</b> can be set using the <b>sethostid(8)</b> command, which modifies the host ID stored in a system file (e.g., <i>/etc/hostid</i>). Its primary use is often in specific network environments or legacy applications that rely on this particular identifier.


title: CAVEATS
content:
The <b>hostid</b> command typically returns <i>0x7f000001</i> (representing <i>127.0.0.1</i>) unless explicitly set. This means it is <i>not</i> a unique identifier for a machine and should not be relied upon for such purposes. Many different systems will report the exact same host ID.


title: HOW THE HOST ID IS SET
content:
The value displayed by <b>hostid</b> is usually obtained from the <b>gethostid()</b> system call. This value can be persistently set using the <b>sethostid(8)</b> command, which typically writes the ID to a file like <i>/etc/hostid</i>. If this file doesn't exist or is empty, the system might default to <i>0x7f000001</i>.


title: USE CASES
content:
While not for unique identification, <b>hostid</b> might be used by licensing schemes tied to this specific ID or by legacy distributed systems that rely on it for host differentiation within a small, controlled environment.


title: HISTORY
content:
The <b>hostid</b> concept and the <b>gethostid()</b> system call originate from older Unix systems, dating back to Berkeley Software Distribution (BSD). It was part of the standard Unix utilities for system identification. Its usage has remained largely consistent, though its utility as a unique machine identifier has diminished over time as more robust identification methods emerged. It remains primarily for backward compatibility or very specific legacy application requirements.


title: PARAMETERS
content:
<b>--alias, -a</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the alias name of the host (if any).<br><br><b>--all-fqdns, -A</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display all FQDNs of the machine. This option enumerates all configured network interfaces and displays their associated FQDNs.<br><br><b>--domain, -d</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the DNS domain name.<br><br><b>--fqdn, --long, -f</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the Fully Qualified Domain Name (FQDN). This is usually `hostname.domainname`.<br><br><b>--ip-address, -i</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the IP address(es) of the hostname. Note that this works by looking up the current hostname, not directly querying network interfaces.<br><br><b>--all-ip-addresses, -I</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display all network interface addresses of the host.<br><br><b>--short, -s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the short host name (the part before the first dot).<br><br><b>--yp, --nis, -y</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the NIS/YP domain name.<br><br><b>--file <FILE>, -F <FILE></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Read the hostname from the specified file and set it.<br><br><b>[NAME]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the system's hostname to the specified NAME. This change is typically not persistent across reboots.<br><br><b>--version, -v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display version information and exit.<br><br><b>--help, -h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br>


title: DESCRIPTION
content:
The `hostname` command in Linux is a fundamental utility used to display or set the system's hostname, domain name, or NIS/YP domain name. It interacts with the kernel's hostname settings. When executed without any arguments, it prints the current hostname. With a single argument, it attempts to set the system's hostname to that value. However, direct setting via `hostname NAME` is often temporary and does not persist across reboots on modern systems using `systemd`. For persistent changes, one typically modifies `/etc/hostname` or uses the `hostnamectl` command. The `hostname` command is crucial for network identification, as the hostname is used by various network services to identify the machine. It can also provide different formats of the hostname, such as the Fully Qualified Domain Name (FQDN) or IP addresses, depending on the options provided.


title: CAVEATS
content:
Setting the hostname using `hostname NAME` is usually <I>not persistent</I> across reboots on modern Linux distributions (especially those using `systemd`). For persistence, modify `/etc/hostname` or use `hostnamectl`.<br>The hostname lookup for options like `-f` or `-i` relies on local DNS/hosts file configuration (e.g., `/etc/hosts` and `/etc/resolv.conf`). If these are misconfigured, the results might be inaccurate.<br>Changing the hostname can affect running services that rely on the old hostname for identification.


title: <B>PERSISTENT HOSTNAME CONFIGURATION</B>
content:
On `systemd`-based systems, the static hostname is typically stored in the `/etc/hostname` file. Directly editing this file and then rebooting (or using `hostnamectl set-hostname`) is the recommended way to make hostname changes permanent.


title: <B>HOSTNAME AND /ETC/HOSTS</B>
content:
The system's hostname should usually have a corresponding entry in the `/etc/hosts` file, typically mapping `127.0.0.1` to `localhost` and the system's hostname, to ensure proper local name resolution. Example: `127.0.0.1 <hostname.domain> <hostname> localhost.localdomain localhost`.


title: HISTORY
content:
The `hostname` command has been a standard Unix utility for many years, dating back to early Unix systems. Its primary function has remained consistent: to query and set the system's identification name. In the context of modern Linux distributions, particularly with the advent of `systemd`, the role of `hostname` for <I>setting</I> the hostname has somewhat shifted. While it still allows temporary changes, `systemd` introduced `hostnamectl` as the preferred and persistent method for managing the system's hostname, static hostname, pretty hostname, and transient hostname, often interacting with the `systemd-hostnamed` service. Despite this, `hostname` remains widely used for quickly <I>displaying</I> the current hostname.


title: SYNOPSIS
content:
<b>hostnamectl</b> [<i>OPTIONS</i>...] {<i>COMMAND</i>}<br><b>hostnamectl</b> [<i>OPTIONS</i>...] {<i>status</i>}<br><b>hostnamectl</b> [<i>OPTIONS</i>...] {<i>set-hostname</i> <i>NAME</i>}<br><b>hostnamectl</b> [<i>OPTIONS</i>...] {<i>set-pretty-hostname</i> <i>NAME</i>}<br><b>hostnamectl</b> [<i>OPTIONS</i>...] {<i>set-chassis</i> <i>TYPE</i>}<br><b>hostnamectl</b> [<i>OPTIONS</i>...] {<i>set-deployment</i> <i>ENVIRONMENT</i>}<br><b>hostnamectl</b> [<i>OPTIONS</i>...] {<i>set-location</i> <i>LOCATION</i>}


title: PARAMETERS
content:
<b>status</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the current system hostname and other related machine information.<br><br><b>set-hostname <i>NAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the system's static hostname. By default, it also attempts to update the transient and pretty hostnames to match. Requires root privileges.<br><br><b>set-pretty-hostname <i>NAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the system's pretty hostname, a free-form, human-readable name for display purposes. Requires root privileges.<br><br><b>set-chassis <i>TYPE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the chassis type of the machine (e.g., 'desktop', 'laptop', 'server', 'container', 'virtual'). Requires root privileges.<br><br><b>set-deployment <i>ENVIRONMENT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the deployment environment (e.g., 'development', 'staging', 'production'). Requires root privileges.<br><br><b>set-location <i>LOCATION</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the physical location of the machine (e.g., 'server room 1', 'desk 5B'). Requires root privileges.<br><br><b>--static</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When used with 'set-hostname', specifically sets only the static hostname. When used with 'status', shows only the static hostname.<br><br><b>--transient</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When used with 'set-hostname', specifically sets only the transient hostname. When used with 'status', shows only the transient hostname.<br><br><b>--pretty</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When used with 'set-hostname', specifically sets only the pretty hostname. When used with 'status', shows only the pretty hostname.<br><br><b>-H, --host <i>USERNAME@</i><i>HOSTNAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes the command on a specified remote host via SSH.<br><br><b>-M, --machine <i>CONTAINER</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes the command on a specified local container.<br><br><b>--no-ask-password</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not prompt for a password when communicating with the systemd hostnamed service.<br><br><b>--json=<i>MODE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Formats output as JSON. Modes include 'short', 'pretty', 'oneline', 'raw-data'.<br><br><b>--no-pager</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not pipe output into a pager.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a short help text and exits.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints a short version string and exits.<br><br>


title: DESCRIPTION
content:
<b>hostnamectl</b> is a utility included with the <b>systemd</b> init system, designed to query and change the system's hostname and related machine information. It provides a centralized and consistent interface for managing three distinct types of hostnames: <b>static</b>, <b>pretty</b>, and <b>transient</b>. The <b>static hostname</b> is the traditional hostname, stored persistently in <i>/etc/hostname</i>, and used by default when the system boots. The <b>pretty hostname</b> is a free-form, UTF-8 string intended for display to users, often more descriptive than the static hostname. The <b>transient hostname</b> is a dynamic hostname received from network configuration (e.g., DHCP or mDNS), which, if not available, defaults to the static hostname.<br>This command interacts with the <b>systemd-hostnamed.service</b> to apply changes. Unlike the older <b>hostname</b> command, <b>hostnamectl</b> ensures that changes to the static and pretty hostnames are persistent across reboots, simplifying system administration by consolidating hostname management into a single, modern tool. It also allows setting machine chassis type, deployment environment, and physical location, further categorizing the system for management purposes.


title: CAVEATS
content:
The <b>hostnamectl</b> command is a part of the <b>systemd</b> ecosystem and requires <b>systemd</b> to be running on the system. All commands that modify hostname settings (e.g., <b>set-hostname</b>, <b>set-pretty-hostname</b>) require root privileges or equivalent permissions. Changes to the static hostname are stored persistently in the <i>/etc/hostname</i> file. Changes to other machine properties (chassis, deployment, location) are managed by the <b>systemd-hostnamed.service</b> and stored in specific machine information files under <i>/etc/machine-info</i> or <i>/run/machine-info</i>.


title: UNDERSTANDING HOSTNAME TYPES
content:
<b>hostnamectl</b> manages three distinct hostname types:<br><ul><li><b>Static Hostname</b>: The traditional hostname, stored persistently in <i>/etc/hostname</i>. This is the primary hostname that the system uses at boot.</li><li><b>Pretty Hostname</b>: A free-form, human-readable UTF-8 string for display purposes, e.g., 'My Awesome Laptop'. It doesn't need to conform to hostname conventions.</li><li><b>Transient Hostname</b>: A hostname that is dynamically managed, typically by network configuration services like DHCP or mDNS. If no transient hostname is available, it defaults to the static hostname.</li></ul>


title: PERSISTENCE OF CHANGES
content:
Unlike the older <b>hostname</b> command, which only sets the kernel hostname temporarily, <b>hostnamectl</b> commands such as <b>set-hostname</b> ensure that the changes to the static and pretty hostnames are written to persistent configuration files (<i>/etc/hostname</i>, <i>/etc/machine-info</i>) and are therefore retained across system reboots. This makes <b>hostnamectl</b> the preferred tool for making permanent hostname changes.


title: HISTORY
content:
<b>hostnamectl</b> was introduced as part of the <b>systemd</b> init system project, which began development around 2010. Its primary goal was to modernize and unify system configuration management, including hostname settings, which traditionally involved disparate tools or direct file edits. By providing a single command-line interface, <b>hostnamectl</b> aimed to simplify persistent hostname configuration across reboots and to manage new concepts like 'pretty' and 'transient' hostnames, reflecting a broader shift towards more dynamic and discoverable system properties within the <b>Linux</b> ecosystem. It became a standard utility in distributions adopting <b>systemd</b>.


title: SEE ALSO
content:
hostname(1), systemd(1), systemd-hostnamed.service(8), systemd-firstboot(1), machine-info(5), os-release(5)


title: PARAMETERS
content:
<b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show a help message describing all available command options.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the installed HPLIP version being used by the utility.<br><br><b><b>-P</b> <I>printer_name</I>, <b>--printer=</b><I>printer_name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the target HP printer by its CUPS (Common Unix Printing System) queue name.<br><br><b><b>-d</b> <I>device_uri</I>, <b>--device=</b><I>device_uri</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the target HP printer by its device URI (e.g., <I>usb://HP/DeskJet?serial=ABCDEF</I>). This option overrides <b>--printer</b> if both are provided.<br><br><b><b>-i</b>, <b>--interactive</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run the alignment process in an interactive mode, prompting the user for necessary input throughout the procedure.<br><br><b><b>-c</b>, <b>--color</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifically align the color printhead. This option is typically used for printers with separate color and black printheads.<br><br><b><b>-b</b>, <b>--black</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifically align the black printhead. This option is typically used for printers with separate color and black printheads.<br><br>


title: DESCRIPTION
content:
<I>hp-align</I> is a command-line utility provided by the HPLIP (HP Linux Imaging and Printing) project. Its primary function is to perform printhead alignment for HP inkjet printers connected to a Linux system. <br><br>Printhead alignment is a crucial maintenance procedure that ensures optimal print quality, preventing issues such as streaks, misaligned lines, fuzzy text, or inaccurate colors. When executed, <I>hp-align</I> typically initiates a diagnostic process on the printer, which involves printing a specific alignment page. The user may then be prompted to follow on-screen instructions, often requiring the printed page to be scanned back into the printer or for visual confirmation of patterns. Proper alignment ensures that the microscopic nozzles on the printhead precisely deposit ink onto the paper, leading to sharp text and vibrant, accurate images. It serves as an essential tool for maintaining the performance of HP inkjet printers in a Linux environment.


title: CAVEATS
content:
<ul><li>Requires the HPLIP (HP Linux Imaging and Printing) software suite to be correctly installed and the printer to be configured via CUPS.</li><li>Not all HP printer models support software-driven electronic alignment; some might require manual alignment via the printer's physical control panel.</li><li>During the alignment process, the printer will usually print an alignment page. The user will typically need to follow further instructions, which might involve scanning this page back into the printer or making visual selections based on patterns.</li><li>The printer must be powered on and properly connected to the system (via USB, network, etc.) for the command to function.</li></ul>


title: WHEN TO USE HP-ALIGN
content:
This command should be utilized when you notice a degradation in print quality, such as visible streaks, misaligned text or images, blurry output, or inaccurate color reproduction. It is also recommended after replacing ink cartridges or if the printer has been moved or stored for an extended period.


title: ALIGNMENT PROCESS OVERVIEW
content:
When you run <I>hp-align</I>, it sends a command to your HP printer to print a specialized alignment sheet. This sheet contains various patterns that the printer uses to calibrate its printhead. Depending on the printer model, you might then be instructed to scan this page back using the printer's built-in scanner, or visually inspect the patterns and select the best one via the printer's control panel or a subsequent GUI utility. This feedback loop allows the printer's firmware to precisely adjust the firing of its tiny nozzles, ensuring accurate ink placement for sharp and clear prints.


title: HISTORY
content:
<I>hp-align</I> is an integral component of the HPLIP (HP Linux Imaging and Printing) project, an open-source initiative led by HP to provide comprehensive support for HP printers, scanners, and fax machines on Linux. Its development has evolved alongside the increasing complexity of HP inkjet printer technologies and the demand for robust driver support and maintenance utilities in the Linux ecosystem. The command ensures that essential printer maintenance tasks, often handled by proprietary software on other operating systems, are fully accessible to Linux users, thereby extending the usability and longevity of HP hardware.


title: SYNOPSIS
content:
<b>hp-check</b> [<b>-r</b>|<b>--run</b>] [<b>-t</b>|<b>--test</b>] [<b>-f</b>|<b>--fix</b>] [<b>-i</b>|<b>--interactive</b>] [<b>--auto</b>] [<b>-d</b>|<b>--debug</b>] [<b>--sysfs</b>] [<b>--force</b>] [<b>-v</b>|<b>--version</b>] [<b>-h</b>|<b>--help</b>]


title: PARAMETERS
content:
<b><b>-r</b>, <b>--run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes the diagnostic checks and generates a detailed report of the system's HPLIP configuration and potential issues.<br><br><b><b>-t</b>, <b>--test</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs a set of preliminary tests to quickly identify common problems without generating a full report.<br><br><b><b>-f</b>, <b>--fix</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempts to automatically fix detected issues, such as installing missing dependencies or correcting permissions. May require root privileges.<br><br><b><b>-i</b>, <b>--interactive</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prompts the user for input during the diagnostic process, allowing for guided troubleshooting and specific actions.<br><br><b><b>--auto</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs in an automatic, non-interactive mode, useful for scripting or unattended execution.<br><br><b><b>-d</b>, <b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose debug output, providing more detailed information for advanced troubleshooting and development purposes.<br><br><b><b>--sysfs</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the utility to use sysfs for device detection instead of udev, which can be useful on older systems or specific configurations.<br><br><b><b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces certain operations or circumvents warnings, to be used with caution.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the current version of the HPLIP software installed on the system.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows a brief help message with available command options and their usage.<br><br>


title: DESCRIPTION
content:
<i>hp-check</i> is a diagnostic utility included with the HPLIP (HP Linux Imaging and Printing) software suite. Its primary function is to analyze the system environment and the HPLIP installation to identify common problems that prevent HP printers or multi-function devices from operating correctly on Linux. It performs comprehensive checks on various aspects, including installed HPLIP components, necessary system dependencies, user permissions, device connectivity, and CUPS (Common Unix Printing System) configuration. <br><br>Users typically run <i>hp-check</i> when encountering printing or scanning errors, or after a fresh HPLIP installation to verify its integrity. The command generates a detailed report, often suggesting specific actions to resolve detected issues, such as installing missing packages, correcting file permissions, or reconfiguring printer connections. This makes it an invaluable first-line troubleshooting tool for HP device users on Linux, streamlining the process of diagnosing complex setup and operational problems.


title: CAVEATS
content:
Users should be aware that <i>hp-check</i> requires the HPLIP software package to be installed on their system. While it provides excellent diagnostic capabilities for HP devices, it is not a general-purpose system diagnostic tool. Running <i>hp-check</i> with the <b>--fix</b> option or performing certain system-level checks may require root privileges (e.g., using <b>sudo</b>) to modify system files or install packages. The output can sometimes be lengthy, but it's designed to guide users towards solutions.


title: COMMON USAGE SCENARIOS
content:
<i>hp-check</i> is frequently used after installing HPLIP to verify a successful setup, or as a first step in troubleshooting when an HP printer fails to print or scan. Running it with <b>-r</b> (report mode) provides a comprehensive overview, while <b>-f</b> (fix mode) attempts to resolve common issues automatically, saving manual configuration time.


title: INTERPRETING THE REPORT
content:
The output of <i>hp-check</i> typically categorizes findings into sections like 'System Information', 'HPLIP Status', 'Dependencies', 'Permissions', and 'Device Status'. It highlights 'MISSING' or 'FAILURE' items and often provides specific recommendations on how to resolve them, making it relatively straightforward for users to follow the troubleshooting steps.


title: HISTORY
content:
<i>hp-check</i> has been an integral component of the HPLIP (HP Linux Imaging and Printing) project since its early stages. The HPLIP project itself began around 2000, aiming to provide comprehensive printer and scanner support for HP devices on Linux. As HP released new models and Linux distributions evolved, <i>hp-check</i> has consistently been updated to incorporate new diagnostic routines, support new dependencies, and adapt to changes in system architectures and printing subsystems like CUPS. Its continued development ensures its relevance and effectiveness in troubleshooting a wide range of HP printer-related issues in the dynamic Linux environment.


title: PARAMETERS
content:
<b>-q, --clean-queues</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Cleans the print queues, removing all pending and stalled print jobs associated with HP printers.<br><br><b>-t, --clean-tmpfiles</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes temporary files generated by the HPLIP system, which can accumulate over time.<br><br><b>-l, --clean-logs</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Clears HPLIP-specific log files, useful for freeing up disk space or for fresh debugging.<br><br><b>-a, --clean-all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a comprehensive cleanup, equivalent to running with -q, -t, and -l combined. This is the <I>default action</I> if no specific cleanup option is provided.<br><br><b>-y, --assume-yes</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Automatically assumes 'yes' to all prompts, allowing the command to run non-interactively without user confirmation.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the current version of the HPLIP software and exits.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows a help message with available options and their descriptions.<br><br>


title: DESCRIPTION
content:
The <b>hp-clean</b> command is an essential utility within the <i>HPLIP (HP Linux Imaging and Printing)</i> software suite. Its primary function is to help troubleshoot and resolve common printing issues by <I>cleaning up various components</I> of the HP printing system on a Linux machine. This includes removing stalled print jobs from the CUPS (Common Unix Printing System) queue, deleting temporary files generated by HPLIP, and clearing accumulated log files.<br><br>Regular use of <b>hp-clean</b> can help resolve problems like print jobs stuck in the queue, printers appearing offline due to configuration issues, or general system sluggishness caused by excessive log or temporary files. It provides a quick way to reset the printing environment related to HP devices without requiring a full reinstallation of the HPLIP software.


title: CAVEATS
content:
The <b>hp-clean</b> command requires the <i>HPLIP software suite</i> to be installed on the system. It may require <I>root or sudo privileges</I> to effectively clean system-wide print queues and log files. Using this command will <I>stop any currently printing jobs</I> related to HP devices and clear all pending jobs in the queue. Always use with caution, especially if you have important jobs waiting to print.


title: USAGE CONTEXT
content:
<b>hp-clean</b> is most commonly invoked when troubleshooting <I>stalled print jobs</I>, when a printer is not responding, or after a printer configuration change. It serves as a first-line diagnostic and remediation tool to bring the HP printing system back to a clean, operational state.


title: HISTORY
content:
The <b>hp-clean</b> utility is an integral part of the <i>HPLIP (HP Linux Imaging and Printing)</i> project, which has been under active development since the early 2000s. Conceived to provide robust support for HP printers and scanners on Linux systems, HPLIP quickly became the de facto standard. <b>hp-clean</b> was introduced as a crucial troubleshooting tool, evolving alongside the main HPLIP suite to address common user issues like stalled print jobs and accumulated temporary files, reflecting the project's commitment to user-friendly maintenance.


title: PARAMETERS
content:
<b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information of the <b>hp-colorcal</b> utility and the HPLIP package it belongs to.<br><br><b><b>-g</b>, <b>--gui</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Launches the graphical user interface (GUI) for the color calibration process. This is often the default mode of operation, providing an interactive and user-friendly experience.<br><br><b><b>-d</b>, <b>--debug</b> <i>&lt;level&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables debug mode, providing more verbose output to the console for troubleshooting purposes. The <i>&lt;level&gt;</i> parameter specifies the verbosity level of the debug information.<br><br><b><b>-p</b>, <b>--printer</b> <i>&lt;name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the CUPS printer name or a PPD (PostScript Printer Description) file path to be used for calibration. This is useful when multiple HP printers are installed or when targeting a specific configuration.<br><br><b><b>-x</b>, <b>--device</b> <i>&lt;uri&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the device URI (Uniform Resource Identifier) of the printer. This can be an alternative way to select the target printer for calibration, particularly for direct device access.<br><br><b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the color calibration process to proceed, even if the utility determines that calibration is not recommended or necessary at the moment. Use with caution.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief help message and usage information for the <b>hp-colorcal</b> command.<br><br>


title: DESCRIPTION
content:
The <b>hp-colorcal</b> utility is a key component of the HPLIP (HP Linux Imaging and Printing) software suite, designed to assist users in achieving accurate color reproduction from their HP printers on Linux systems.<br><br>Color calibration is crucial for ensuring that the colors printed on paper match the intended colors as closely as possible, which is especially important for graphics professionals, photographers, or anyone requiring consistent and true-to-life color output. This tool guides the user through a process that typically involves printing a test pattern, then either scanning it (if a scanner is available and supported for automatic calibration) or visually inspecting the printed pattern to identify color inaccuracies.<br><br>Based on the feedback, <b>hp-colorcal</b> helps in adjusting the printer's color settings to compensate for variations in ink, paper, or the printer's internal mechanisms. By providing a structured approach to color management, it helps maintain print quality and consistency over time, ensuring vibrant and precise color prints.


title: CAVEATS
content:
The effectiveness of <b>hp-colorcal</b> heavily relies on the specific HP printer model and its level of support within the HPLIP framework. Not all HP printers may support automated color calibration or have the same range of adjustable features.<br><br>For automatic calibration, a working scanner (preferably an HP scanner also supported by HPLIP) is often required to scan the printed test patterns. Manual calibration, while possible, requires a keen eye and might yield less precise results.<br><br>CUPS (Common Unix Printing System) must be properly configured and the target HP printer must be set up and accessible through CUPS for <b>hp-colorcal</b> to function correctly.


title: COLOR CALIBRATION PROCESS OVERVIEW
content:
The typical color calibration process using <b>hp-colorcal</b>, especially in its GUI mode, involves several steps:<br>1. <i>Printing a Test Chart</i>: The utility instructs the printer to output a specific pattern with various color swatches and gradients designed for calibration.<br>2. <i>Analysis</i>: The user is then prompted to either scan this printed chart using an attached scanner (for automated analysis) or visually inspect it closely to identify any color shifts, inaccuracies, or inconsistencies.<br>3. <i>Adjustment</i>: Based on the analysis, the utility provides options to adjust the printer's color profiles or settings (e.g., brightness, contrast, saturation, or individual color channel adjustments).<br>4. <i>Verification</i>: Often, the process involves reprinting a new chart after adjustments to verify the improvements. This iterative process helps achieve optimal color reproduction for the specific printer and paper combination.


title: HISTORY
content:
<b>hp-colorcal</b> is an integral part of the HPLIP (HP Linux Imaging and Printing) project, which was initiated by HP to provide robust and comprehensive open-source drivers and utilities for HP inkjet and laser printers on Linux. The command has evolved alongside the HPLIP suite, incorporating support for new printer models and calibration technologies as they were developed.<br><br>Its development reflects HP's commitment to ensuring high-quality print output for Linux users, addressing the specific need for color accuracy in an open-source environment. The tool continues to be maintained and updated as part of the broader HPLIP project, adapting to changes in printing standards and hardware capabilities.


title: SYNOPSIS
content:
<b>hp-firmware</b> [<i>OPTIONS</i>]<br><b>hp-firmware --list</b> [<b>--all</b>]<br><b>hp-firmware --update</b> <i>&lt;COMPONENT&gt; &lt;FIRMWARE_FILE&gt;</i> [<b>--force</b>] [<b>--reboot</b>]<br><b>hp-firmware --version</b><br><b>hp-firmware --help</b>


title: PARAMETERS
content:
<b><b>--list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists the currently installed firmware versions for recognized hardware components on the system.<br><br><b><b>--update</b> <i>&lt;COMPONENT&gt; &lt;FIRMWARE_FILE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Initiates a firmware update for a specified <i>&lt;COMPONENT&gt;</i> using the provided <i>&lt;FIRMWARE_FILE&gt;</i>. The component name must match one recognized by the utility.<br><br><b><b>--all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used in conjunction with <b>--list</b> to display all recognized components, including those for which no firmware update is currently applicable or available.<br><br><b><b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the firmware update, overriding any version checks or warnings. Use with caution as forcing an update can potentially lead to system instability if the firmware is incompatible or corrupted.<br><br><b><b>--reboot</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Automatically reboots the system after a successful firmware update, if a reboot is required by the firmware for the changes to take effect.<br><br><b><b>--host</b> <i>&lt;IP_ADDRESS&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the IP address of the Integrated Lights-Out (iLO) interface for remote firmware management operations.<br><br><b><b>--user</b> <i>&lt;USERNAME&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the iLO username for authentication when performing remote operations.<br><br><b><b>--password</b> <i>&lt;PASSWORD&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the iLO password for authentication when performing remote operations. It is generally recommended to avoid entering passwords directly on the command line for security reasons.<br><br><b><b>--log-file</b> <i>&lt;FILE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Redirects the output and log messages of the command to the specified <i>&lt;FILE&gt;</i> instead of standard output.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information of the <b>hp-firmware</b> utility.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a concise help message with available options and syntax, then exits.<br><br>


title: DESCRIPTION
content:
The <b>hp-firmware</b> command is a utility provided by Hewlett Packard (HP) / Hewlett Packard Enterprise (HPE) for managing firmware on their server and workstation hardware running Linux.<br><br>It enables administrators to query the current firmware versions of various system components (like System ROM, iLO, network adapters, storage controllers, etc.) and to apply new firmware updates. This tool is crucial for maintaining system stability, security, and performance by ensuring that hardware components are running the latest compatible firmware.<br><br>It typically operates in conjunction with other HP/HPE system management tools and often requires specific firmware update files obtained from the HPE support website. While <b>hp-firmware</b> is still used on many legacy systems, newer HPE hardware and Linux distributions might utilize more modern tools like <b>hpe-fwupdate</b> or the <b>fwupd</b> daemon with its <b>fwupdate</b> utility.


title: CAVEATS
content:
The <b>hp-firmware</b> utility is specifically designed for Hewlett Packard (HP) / Hewlett Packard Enterprise (HPE) hardware and may not function on other vendor's systems.<br><br>It typically requires root privileges to execute. Firmware updates carry inherent risks; always ensure stable power and proper files before initiating an update. Incorrect or interrupted updates can render hardware components, or even the entire system, inoperable.<br><br>For newer HPE hardware or recent Linux distributions, <b>hp-firmware</b> might be deprecated or replaced by more modern tools like <b>hpe-fwupdate</b> or the general Linux <b>fwupd</b> framework. Always consult HPE's official documentation for your specific server model and Linux distribution for the recommended firmware update procedures.


title: FIRMWARE FILE ACQUISITION
content:
Firmware update files used by <b>hp-firmware</b> must typically be downloaded from the official HPE Support website. These files are usually provided in specific formats, often as `.bin` or `.rpm` packages containing the actual firmware image. Ensure you download the correct firmware version for your specific hardware model and operating system before attempting an update.


title: BEST PRACTICES FOR UPDATES
content:
Before performing any firmware update: 1. <I>Backup critical data</I>. 2. <I>Ensure stable power</I> (e.g., using a UPS). 3. <I>Verify the firmware file integrity</I> (checksums). 4. <I>Read the release notes</I> associated with the firmware update for specific instructions or prerequisites. 5. <I>Schedule downtime</I> as updates often require a system reboot and can take some time to complete.


title: HISTORY
content:
The <b>hp-firmware</b> utility emerged as part of HP's suite of Linux management tools, designed to provide enterprise-grade firmware management capabilities directly from the operating system.<br><br>It was developed to simplify the process of maintaining and updating server and workstation firmware, often working in conjunction with tools like HP System Management Homepage (SMH) and HP Insight Diagnostics. Its existence reflects the increasing need for integrated system management solutions in complex server environments, moving away from purely out-of-band updates or DOS-based flashing utilities. While still relevant for older HP/HPE systems, its role has been evolving with the advent of more generic firmware update frameworks in Linux and newer HPE-specific utilities.


title: PARAMETERS
content:
<b>-i <device-uri></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display basic device information for the specified <i>device URI</i>.<br><br><b>-a <device-uri></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display <b>all available information</b> for the specified <i>device URI</i>, including product, connectivity, and capabilities data.<br><br><b>-c <device-uri></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display connectivity information for the specified <i>device URI</i>, such as network status or connection type.<br><br><b>-p <device-uri></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display product-specific information for the specified <i>device URI</i>, including model name and firmware.<br><br><b>-s <device-uri></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display device capabilities information for the specified <i>device URI</i>, such as supported functions (print, scan, fax).<br><br><b>-w <device-uri></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display information related to the device's <i>Embedded Web Server (EWS)</i> for the specified <i>device URI</i>.<br><br><b>-t</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run in <i>test mode</i>, typically used for development or diagnostic purposes.<br><br><b>-d</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable <i>debug mode</i>, providing verbose output useful for troubleshooting.<br><br><b>-g</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Launch the <i>GUI mode</i>, if available, for interactive device information display.<br><br><b>-j</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output information in <i>JSON format</i>, suitable for programmatic parsing.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the <i>HPLIP</i> and utility version information.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the command's help message and available options.<br><br>


title: DESCRIPTION
content:
The `hp-info` command, part of the <i>HPLIP</i> (HP Linux Imaging and Printing) system, provides a detailed overview of <i>HP</i> imaging and printing devices connected to a <i>Linux</i> system.<br><br>It is an essential diagnostic tool for administrators and users alike, offering insights into device configuration, status, capabilities, and connectivity.<br><br>When executed without options, it typically lists all detected <i>HP</i> devices and their basic <i>URIs</i>. With specific options or a <i>device URI</i>, it can drill down to provide information such as product model, firmware version, serial number, driver status, network configuration, and scanner/fax capabilities, aiding in troubleshooting and setup.


title: CAVEATS
content:
<ul><li>Requires the <b>HPLIP</b> (<i>HP Linux Imaging and Printing</i>) package to be installed on the system.</li><li>For comprehensive device information or specific diagnostic functions, the command might require <b>root privileges</b>.</li><li>The target <i>HP</i> device must be <b>connected</b> to the system and <b>powered on</b> for `hp-info` to detect it and retrieve information.</li><li>Networked devices might require proper network configuration and discoverability for `hp-info` to locate them.</li></ul>


title: TYPICAL OUTPUT SECTIONS
content:
When run for a specific device, `hp-info` can provide various sections of information including:<br><i>Product Information</i> (Model Name, Product ID, Firmware Version, Serial Number), <i>Connectivity Information</i> (Connection Type, IP Address, Port), <i>Driver Information</i> (HPLIP Driver Version, CUPS Driver), <i>Status Information</i> (Device State, Warnings/Errors), and <i>Capabilities</i> (Printer, Scanner, Fax support).


title: HISTORY
content:
The `hp-info` command is an integral part of the <b>HPLIP</b> (<i>HP Linux Imaging and Printing</i>) project, which was initiated by <i>HP</i> in 2001 to provide robust <i>Linux</i> support for <i>HP</i> printers, scanners, and multi-function devices.<br><br>Over the years, <i>HPLIP</i> has evolved significantly, incorporating support for hundreds of <i>HP</i> models and becoming the de facto standard for <i>HP</i> device integration on <i>Linux</i>. `hp-info` has consistently served as a key utility for device identification and diagnostics throughout this development, reflecting the growing need for detailed hardware information in the <i>Linux</i> ecosystem.


title: PARAMETERS
content:
<b><b>-i</b>, <b>--info</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays general information about the <b>hp-levels</b> utility itself.<br><br><b><b>-g</b>, <b>--gui</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Launches a graphical user interface (GUI) for checking HP printer levels, providing a more visual representation of cartridge status.<br><br><b><b>-d</b> <I>level</I>, <b>--debug</b> <I>level</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables debug mode with a specified numerical <i>level</i> (e.g., 1-10). This provides verbose output, which is highly useful for troubleshooting communication issues or understanding the command's internal operations.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message detailing the command's usage and available options.<br><br>


title: DESCRIPTION
content:
The <b>hp-levels</b> command is a crucial utility within the HPLIP (HP Linux Imaging and Printing) software suite, designed specifically for managing HP printers on Linux systems. Its primary function is to provide users with a quick and convenient way to monitor the ink or toner cartridge levels of their connected HP printers directly from the command line. This tool queries the printer for its supply levels and displays them, often indicating percentages for black and color cartridges, or a general status like "OK" or "Low".<br><br>It's particularly useful for users who prefer command-line interfaces or for scripting purposes where graphical tools might be cumbersome. <b>hp-levels</b> helps users anticipate when cartridges need replacement, preventing unexpected interruptions during printing tasks.


title: CAVEATS
content:
<ul><li>Requires the HPLIP (HP Linux Imaging and Printing) software package to be installed and properly configured for your HP printer.</li><li>The printer must be powered on and actively connected to the system (via USB or network) for <b>hp-levels</b> to communicate with it.</li><li>Not all HP printer models may report precise ink/toner levels, or some older models might not be fully supported by the utility, potentially showing generic statuses like "Unknown" or "OK".</li><li>For network printers, proper network connectivity and firewall configurations are essential for detection and status retrieval.</li><li>The accuracy of reported levels can sometimes vary depending on the printer's firmware and communication protocol.</li></ul>


title: HOW IT WORKS
content:
<b>hp-levels</b> communicates directly with the HP printer, typically utilizing protocols such as SNMP (Simple Network Management Protocol) for network-connected printers or device-specific USB protocols for locally connected printers. It queries the printer's internal status registers to retrieve information about the ink or toner levels. The reported levels are usually presented as percentages, but can sometimes be simpler status indicators (e.g., "OK", "Low", "Empty") depending on the printer's capabilities and the information it exposes.


title: COMMON USAGE
content:
To check levels for a printer, simply running `hp-levels` will attempt to detect and display information for connected HP printers. If multiple HP printers are configured, it might list them or focus on the default one. For more detailed troubleshooting or to understand the communication process, combining it with the `<b>-d</b>` (debug) option can provide valuable insights into the interaction between the command and the printer.


title: HISTORY
content:
The <b>hp-levels</b> command is an integral part of the HPLIP (HP Linux Imaging and Printing) project, which was initiated by HP in 2000 to provide comprehensive Linux support for its printing and imaging devices. Developed as open-source software, HPLIP aims to ensure that HP printers, all-in-ones, and fax machines function seamlessly on Linux distributions. <b>hp-levels</b> was developed as a key utility within this suite to address the common user need of monitoring consumable levels, evolving alongside the broader HPLIP project to support new printer models and communication protocols. Its development has focused on robustness and ease of use, leveraging various printer communication methods (like SNMP for network printers or USB protocols) to retrieve cartridge status.


title: PARAMETERS
content:
<b>-i, --ip</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the IP address of a network-connected HP printer (e.g., 10.0.0.100).<br><br><b>-b, --bus</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the connection bus type (e.g., <i>usb</i>, <i>net</i>, <i>par</i>, <i>ser</i>, <i>pt</i>) for the printer.<br><br><b>-d, --deviceid</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides a specific device identifier for the printer, often useful for unique USB devices (e.g., from <i>lsusb -v</i> output).<br><br><b>-n, --name</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assigns a descriptive name to the printer for easier identification.<br><br><b>-x, --xml</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the generated URI and additional device information in XML format.<br><br><b>-r, --raw</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs only the raw, unformatted URI string to standard output, without additional details.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a comprehensive help message for the command and exits.<br><br><b>-v, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the installed HPLIP version number and exits.<br><br>


title: DESCRIPTION
content:
<i>hp-makeuri</i> is a specialized utility included in the HPLIP (HP Linux Imaging and Printing) software suite, designed to simplify the creation of Uniform Resource Identifiers (URIs) for HP printers. These URIs are fundamental for configuring and managing printers within the CUPS (Common Unix Printing System) environment on Linux systems.<br><br>The command can function interactively, guiding users through the process of discovering and selecting detected HP devices, or non-interactively by accepting command-line parameters such as an IP address for network printers, bus type (e.g., USB, network), and specific device IDs. By generating the correct URI format, <i>hp-makeuri</i> ensures that print jobs can be accurately routed to the target HP printer, facilitating seamless printer setup and operation across various connection methods.


title: CAVEATS
content:
<b>Requires HPLIP:</b> The command depends entirely on the HPLIP (HP Linux Imaging and Printing) drivers and utilities being installed on the system.<br><b>Root Privileges:</b> Certain operations, particularly direct hardware access or device discovery over USB or network, may necessitate root privileges to execute successfully.<br><b>Network Discovery:</b> Network printer detection can be significantly affected by firewall rules, network configuration, or the printer's own network settings.<br><b>Interactive Mode Recommended:</b> For complex setups or if specific parameters are unknown, it is often best to run the command without any arguments to utilize its guided interactive mode.


title: INTERACTIVE MODE
content:
When executed without any command-line options, <i>hp-makeuri</i> defaults to an interactive mode. In this mode, it actively scans for available HP printers, presents a list to the user, and guides them through the selection process to generate the correct URI. This feature is particularly helpful for users unfamiliar with specific device details or network configurations, making printer setup more accessible and user-friendly.


title: PURPOSE OF URI
content:
The URI (Uniform Resource Identifier) generated by <i>hp-makeuri</i> serves as a unique address that CUPS (Common Unix Printing System) uses to identify and communicate with a specific HP printer. Examples include <i>hp:/usb/OfficeJet_Pro_8600?serial=xxxxxx</i> for USB connections or <i>hp:/net/OfficeJet_Pro_8600?ip=10.0.0.100</i> for network connections. This standardized format ensures accurate routing of print jobs, enables proper driver selection, and facilitates effective device management within the Linux printing environment.


title: HISTORY
content:
<i>hp-makeuri</i> is an integral component of the HPLIP project, which was initiated by HP to provide robust and comprehensive support for HP printers and multi-function devices on Linux. Its development has closely paralleled the evolution of the HPLIP suite itself, continuously adapting to new printer models, connection technologies, and changes in Linux printing infrastructures.<br><br>The command emerged as a dedicated utility to standardize and simplify the crucial process of generating printer URIs, a fundamental step in CUPS-based printer configuration. Before its widespread adoption, users often had to manually construct complex URIs, which was prone to errors. <i>hp-makeuri</i> replaced this with an automated or guided interactive process, significantly enhancing user experience and printer setup reliability on Linux.


title: PARAMETERS
content:
<b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Displays a help message and exits.</i><br><br><b><b>-l</b>, <b>--list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Lists all detected HP devices with their details.</i><br><br><b><b>-a</b>, <b>--all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Probes all supported bus types (USB, network, parallel) for devices. This is often the default behavior.</i><br><br><b><b>-b</b> <i>&lt;bus_type&gt;</i>, <b>--bus</b> <i>&lt;bus_type&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies the bus type to probe. Common types include <b>usb</b>, <b>net</b> (network), and <b>par</b> (parallel).</i><br><br><b><b>-i</b> <i>&lt;ip_address&gt;</i>, <b>--ip</b> <i>&lt;ip_address&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>When probing the network bus, specifies a particular IP address to check for an HP device.</i><br><br><b><b>-m</b> <i>&lt;model_name&gt;</i>, <b>--model</b> <i>&lt;model_name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies a particular device model name to search for.</i><br><br><b><b>-u</b> <i>&lt;device_uri&gt;</i>, <b>--uri</b> <i>&lt;device_uri&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Allows probing a specific device identified by its URI (e.g., <b>usb://HP/Deskjet_3700?serial=...</b> or <b>hp:/net/HP_Printer_Name?ip=...</b>).</i><br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Displays the HPLIP version number and exits.</i><br><br><b><b>-d</b>, <b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Enables verbose debug output, useful for troubleshooting detection issues.</i><br><br><b><b>-t</b>, <b>--test</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Runs the probe in a test mode, often used internally for development or diagnostics.</i><br><br>


title: DESCRIPTION
content:
hp-probe is a utility included in the HPLIP (HP Linux Imaging and Printing) software suite. Its primary function is to automatically detect and identify HP printers, scanners, and multi-function devices connected to a Linux system. It can probe various connection types, including USB, network (wired and wireless), and parallel ports. While not typically run directly by end-users, it is an essential component used by other HPLIP tools like <b>hp-setup</b> (for configuring new devices) and <b>hp-doctor</b> (for diagnosing issues) to locate available HP hardware. The command provides detailed information about detected devices, such as their model, connection URI, and status, facilitating the setup and management of HP peripherals on Linux.


title: CAVEATS
content:
Requires the HPLIP (HP Linux Imaging and Printing) software suite to be installed on the system.<br>Network probing might require proper firewall rules to allow device discovery (e.g., mDNS/Bonjour).<br>For USB devices, ensure the necessary kernel modules (like <b>usblp</b>) are loaded and the user has appropriate permissions to access USB devices.


title: INTEGRATION WITH HPLIP TOOLS
content:
<b>hp-probe</b> is primarily an internal utility called by higher-level HPLIP tools. Users rarely need to execute <b>hp-probe</b> directly. Instead, <b>hp-setup</b> will automatically run <b>hp-probe</b> to find devices during the printer installation process, and <b>hp-doctor</b> may use it to identify connected devices when diagnosing problems. This integration streamlines the user experience for setting up and maintaining HP peripherals.


title: HISTORY
content:
<b>hp-probe</b> is an integral part of the HPLIP project, which was initiated by HP in 2004 to provide comprehensive printer and scanner support for Linux. Over the years, HPLIP has evolved to support a vast range of HP devices, and <b>hp-probe</b> has remained a core component for device auto-detection, adapting to new connection technologies and device models. Its development is tied directly to the ongoing maintenance and expansion of the HPLIP suite.


title: PARAMETERS
content:
<b>-d <device-uri>, --device=<device-uri></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the URI of the HP device to query. If omitted, the command may attempt to discover devices or apply to a default device.<br><br><b>-i, --info</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays comprehensive information about the specified or auto-detected HP device, including model, firmware, and supported features.<br><br><b>-l, --list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all auto-detected HP devices accessible to the system, showing their device URIs and models.<br><br><b>-s, --status</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Queries and reports the current status of the specified or auto-detected HP device, such as 'idle', 'printing', or 'error'.<br><br><b>-V, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the version of the HPLIP package installed on the system.<br><br><b>-?, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a concise help message with a summary of command-line options.<br><br><b>--debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables debug mode, providing more verbose output for troubleshooting.<br><br>


title: DESCRIPTION
content:
<b>hp-query</b> is a command-line utility that is part of the <I>HPLIP</I> (HP Linux Imaging and Printing) project. It serves as a diagnostic and information-gathering tool for HP printers and multi-function devices connected to a Linux system.<br><br>Users can leverage <b>hp-query</b> to retrieve various details about their HP hardware, including its current status, detected capabilities, configuration, and any encountered error conditions. It's particularly useful for troubleshooting connectivity problems or device malfunctions, offering a textual interface to inspect HP-specific information without relying on graphical tools. The command supports querying specific devices via their URI or discovering all available HP devices on the network or via USB.


title: CAVEATS
content:
<b>hp-query</b> relies on the <I>HPLIP</I> (HP Linux Imaging and Printing) drivers and libraries being correctly installed and configured on the system. Some operations, particularly device discovery or detailed information retrieval, might require root privileges or proper user group permissions for device access.<br><br>The output can be highly verbose and may require filtering or parsing for specific pieces of information. Device URIs can sometimes be complex and specific to the connection type (USB, network).


title: ROLE IN TROUBLESHOOTING
content:
Primarily used by system administrators and advanced users for diagnosing connectivity issues, checking device health, and verifying configuration details of HP printers and scanners. It helps in quickly identifying whether a problem lies with the device itself or the printing subsystem.


title: INTEGRATION WITH CUPS
content:
While <I>hp-query</I> provides HP-specific device details, it often complements the standard CUPS printing system. It can retrieve device URIs that are then used by CUPS commands like <I>lpadmin</I> or <I>lpstat</I> for printer queue management.


title: HISTORY
content:
<I>hp-query</I> is an integral part of the <I>HPLIP</I> (HP Linux Imaging and Printing) project, which was initiated by HP in the early 2000s. The primary goal of <I>HPLIP</I> was to provide robust and comprehensive open-source drivers and utilities for HP printers and multi-function devices on Linux operating systems, integrating seamlessly with the CUPS printing system. <I>hp-query</I> was developed as a key diagnostic and information-gathering tool within this suite, enabling users and system administrators to troubleshoot and manage HP hardware from the command line. Its development has paralleled the evolution of the HPLIP project itself, with ongoing updates to support new HP models and Linux distributions.


title: PARAMETERS
content:
<b><b>-r</b> <i>&lt;resolution&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the scan resolution in DPI (dots per inch). Example: <b>-r</b> <i>300</i>.<br><br><b><b>-m</b> <i>&lt;mode&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the scan mode. Common modes include <i>color</i>, <i>grayscale</i>, or <i>binary</i> (lineart).<br><br><b><b>-f</b> <i>&lt;format&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output file format. Common formats are <i>jpeg</i>, <i>png</i>, <i>tiff</i>, or <i>pdf</i>.<br><br><b><b>-s</b> <i>&lt;source&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects the scan source. Typically <i>flatbed</i> or <i>adf</i> (Automatic Document Feeder).<br><br><b><b>-o</b> <i>&lt;output_file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output filename. If omitted, the scan is saved to a default file (e.g., scan.jpeg).<br><br><b><b>-x</b> <i>&lt;width_pixels&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the scan width in pixels.<br><br><b><b>-y</b> <i>&lt;height_pixels&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the scan height in pixels.<br><br><b><b>-l</b> <i>&lt;x_coord_mm&gt;</i>, <b>-t</b> <i>&lt;y_coord_mm&gt;</i>, <b>-w</b> <i>&lt;width_mm&gt;</i>, <b>-h</b> <i>&lt;height_mm&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Define a specific scan area in millimeters: left, top, width, height.<br><br><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>hp-scan</b> utility.<br><br>


title: DESCRIPTION
content:
<b>hp-scan</b> is a command-line utility provided by the HPLIP (HP Linux Imaging and Printing) project. It enables users to scan documents and images directly from HP multifunction devices (MFPs) and standalone scanners connected to a Linux system. It leverages the SANE (Scanner Access Now Easy) backend to communicate with the hardware, offering control over various scan settings such as resolution, color mode, scan source (flatbed or ADF), and output file format. <br><br>While not providing a graphical interface, <b>hp-scan</b> is invaluable for basic scanning operations, scripting, and integrating scanning capabilities into custom workflows where a full GUI application might be overkill or unavailable. It supports saving scans in common image formats like JPEG, PNG, TIFF, and PDF.


title: CAVEATS
content:
For <b>hp-scan</b> to function, the HP device must be properly installed and configured within the HPLIP framework. This often involves running <b>hp-setup</b> first. Networked scanners require proper network connectivity. Scan quality and available options can vary significantly based on the specific HP device model and its capabilities.


title: INTEGRATION WITH HPLIP
content:
<b>hp-scan</b> is an integral part of the HPLIP suite, relying on the HPLIP daemon and drivers to interface with HP hardware. It's often used in conjunction with other HPLIP utilities.


title: SCRIPTING CAPABILITY
content:
Given its command-line interface, <b>hp-scan</b> is well-suited for automation. It can be easily incorporated into shell scripts for batch scanning, scheduled tasks, or integrating scanning into custom applications.


title: HISTORY
content:
The HPLIP project, which includes <b>hp-scan</b>, was initiated by HP in 2001 to provide comprehensive Linux support for their wide range of printers and scanners. <b>hp-scan</b> has evolved as a core component of this suite, adapting to new HP hardware and SANE backend developments, ensuring consistent scanning functionality for HP devices on Linux over the years.


title: PARAMETERS
content:
<b><b>-i</b>, <b>--interactive</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs the setup utility in interactive text mode.<br><br><b><b>-g</b>, <b>--gui</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Launches the graphical user interface for the setup utility. This is often the default behavior if a display is available.<br><br><b><b>-b</b> <i>&lt;bus-type&gt;</i>, <b>--bus=</b><i>&lt;bus-type&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scans for devices connected on a specific bus type (e.g., <i>usb</i> or <i>net</i>).<br><br><b><b>-u</b> <i>&lt;device-uri&gt;</i>, <b>--uri=</b><i>&lt;device-uri&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a direct device URI for setup, bypassing device detection (e.g., <i>hp:/net/HP_LaserJet_P2055dn?ip=192.168.1.100</i>).<br><br><b><b>-a</b>, <b>--add</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds the detected or specified printer device to CUPS without starting the full interactive setup. Requires a <i>--uri</i> or detected device.<br><br><b><b>--cups-test</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints a test page after successfully setting up the printer in CUPS.<br><br><b><b>--plugin</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the download and installation of any required proprietary HPLIP plugins, even if not automatically prompted.<br><br><b><b>--no-cups</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skips the CUPS printer configuration step.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the HPLIP version information.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows a help message and exits.<br><br>


title: DESCRIPTION
content:
<b>hp-setup</b> is a fundamental command-line utility from the HPLIP (HP Linux Imaging and Printing) project. Its primary purpose is to simplify the installation and configuration of HP printers and multi-function devices on Linux systems.<br><br>The command guides users through the process of detecting connected devices (via USB or network), downloading and installing necessary proprietary plug-ins (if required), configuring the appropriate drivers, and integrating the device with the CUPS (Common Unix Printing System) print server. It supports both interactive text-based setup and, by default or with the <i>--gui</i> option, can launch a graphical user interface for easier navigation. <b>hp-setup</b> is crucial for ensuring full functionality, including printing, scanning, and faxing capabilities, for a wide range of HP hardware.


title: CAVEATS
content:
Using <b>hp-setup</b> typically requires root privileges (e.g., via <i>sudo</i>) to modify system-wide CUPS configurations and install necessary drivers or plugins. An active internet connection may be required for downloading proprietary HPLIP plugins. Ensure CUPS is running before attempting to set up a printer. Compatibility may vary with specific HP printer models and HPLIP versions.


title: HISTORY
content:
<b>hp-setup</b> is a core component of the HPLIP project, which was initiated by HP to provide comprehensive and robust Linux support for its printing and imaging devices. The command has evolved significantly over the years, adapting to new printer technologies, network protocols, and Linux distribution changes, while maintaining its central role in user-friendly printer setup.


title: PARAMETERS
content:
<b><I>PRINTER_NAME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the printer to which the test page should be sent. If omitted, the default system printer is usually used.<br><br><b>-p <I>PRINTER</I>, --printer=<I>PRINTER</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly specifies the name of the printer to use for printing the test page. This is useful when multiple HP printers are configured.<br><br><b>-v, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information of the <b>hp-testpage</b> utility and exits.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows a help message detailing the command's usage and available options.<br><br><b>-i, --info</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides verbose information, typically integrating output similar to <b>hp-info</b> for diagnostic purposes.<br><br><b>-d, --debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables debug output, which can be useful for advanced troubleshooting by developers or experienced users.<br><br><b>-t, --terminal</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the command to run in terminal mode, suppressing any potential GUI elements.<br><br><b>-x, --x-display</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an X-display for graphical operations, primarily relevant if the command would otherwise launch a GUI (though less common for <b>hp-testpage</b> itself).<br><br>


title: DESCRIPTION
content:
The <b>hp-testpage</b> command is a utility provided by the <b>HPLIP</b> (HP Linux Imaging and Printing) project. Its primary function is to print a standard test page to an HP printer configured on a Linux system. This command is invaluable for verifying the correct setup and functionality of a printer after installation or for troubleshooting connectivity and printing issues. By generating a simple, known output, it helps determine if the problem lies with the printer itself, the print queue, or the application attempting to print. It can be run in a terminal and typically allows specifying a target printer, making it a quick diagnostic tool for administrators and users alike.


title: CAVEATS
content:
Requires the <b>HPLIP</b> package to be installed and properly configured on the system.<br>The target HP printer must be powered on, connected to the network or system (via USB/network), and configured within the CUPS printing system.<br>If the test page fails to print, it often indicates an issue with printer connectivity, driver installation, or CUPS queue configuration rather than the <b>hp-testpage</b> command itself.


title: HISTORY
content:
The <b>hp-testpage</b> command is an integral part of the <b>HPLIP</b> project, which began development in the early 2000s to provide comprehensive open-source support for HP printers, scanners, and multi-function devices on Linux and other Unix-like operating systems. Its inclusion reflects the need for a straightforward diagnostic tool within the HPLIP suite, allowing users to quickly verify the basic functionality of their HP printing devices without needing to rely on application-specific printing functions. Its usage has remained consistent over the years as a fundamental troubleshooting step.


title: SYNOPSIS
content:
<b>hp-timedate</b> [<i>-h</i>|<i>--help</i>] [<i>-v</i>|<i>--version</i>] [<i>-d</i>|<i>--device=&lt;device_uri&gt;</i>] [<i>-g</i>|<i>--get</i> | <i>-s</i>|<i>--set</i>] [<i>-i</i>|<i>--interactive</i>]


title: PARAMETERS
content:
<b><i>-h, --help</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Displays a brief help message and exits.<br><br><b><i>-v, --version</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Shows the HPLIP version information and exits.<br><br><b><i>-d &lt;device_uri&gt;, --device=&lt;device_uri&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Specifies the device URI for the HP device to operate on. If omitted, the command attempts to autodetect an available HP device. Example URI: <i>hp:/usb/DeskJet_2600_series?serial=ABC123DEF</i>.<br><br><b><i>-g, --get</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Retrieves and displays the current time and date from the specified HP device.<br><br><b><i>-s, --set</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Sets the time and date of the specified HP device to match the current system time. This operation typically requires root privileges.<br><br><b><i>-i, --interactive</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Runs the command in interactive mode, prompting the user for choices and confirmations during the operation.<br><br>


title: DESCRIPTION
content:
<i>hp-timedate</i> is a utility provided by the <i>HPLIP</i> (HP Linux Imaging and Printing) driver project, designed specifically to manage the time and date settings of connected HP peripherals, primarily printers. Unlike standard Linux commands such as <i>date</i> or <i>timedatectl</i> which control the system's clock, <i>hp-timedate</i> focuses on synchronizing or setting the internal clock of your HP hardware.<br><br>This command is essential for maintaining accurate timestamps on printouts, device logs, and for networked HP devices that rely on correct time synchronization for network services and security protocols. It allows users to query the device's current time and date (<i>--get</i> option) or set the device's time to match the host system's current time (<i>--set</i> option). Interaction with the HP device is facilitated by the HPLIP backend. For certain operations, particularly setting the device time, administrative privileges (e.g., using <i>sudo</i>) are typically required to ensure proper device access and modification. It ensures consistency between your Linux system and your HP equipment.


title: CAVEATS
content:
Requires the <i>hplip</i> package to be installed on your Linux system.<br>Setting the device time usually requires <i>root</i> privileges or proper <i>udev</i> rules configured for device access.<br>This command is exclusively designed for managing HP devices and will not interact with non-HP hardware or the system's clock directly.<br>The target HP device must be connected, powered on, and accessible by the system for the command to function correctly.


title: USAGE EXAMPLES
content:
<b>Get Device Time:</b><br>To retrieve the current time from your HP device:<br><i>hp-timedate -g -d hp:/usb/HP_LaserJet_MFP_M232-M237</i><br>If only one HP device is connected and detected, you can often omit the device URI:<br><i>hp-timedate -g</i><br><br><b>Set Device Time:</b><br>To synchronize your HP device's time with your system's current time, which often requires administrative privileges:<br><i>sudo hp-timedate -s -d hp:/net/HP_LaserJet_MFP_M232-M237</i><br>Or, for an autodetected device:<br><i>sudo hp-timedate -s</i><br>The command will confirm the operation and update the device's internal clock.


title: HISTORY
content:
The <i>hp-timedate</i> utility is an integral part of the <i>HPLIP</i> (HP Linux Imaging and Printing) project, which was initiated by HP and the open-source community around 2001. HPLIP was developed to provide comprehensive, unified support for HP printers, scanners, and multi-function devices across various Linux distributions. As HP devices evolved to include embedded clocks for logging, network synchronization, and timestamping functionalities, the need for a dedicated tool to manage these internal time settings arose. <i>hp-timedate</i> was thus introduced as part of this suite to specifically address device-side time management, ensuring consistency and accuracy between the Linux host and its connected HP peripherals. Its core functionality has remained focused on this specific task since its inception, reflecting the ongoing requirement for precise device clock synchronization.


title: PARAMETERS
content:
<b><i>-r</i>, <i>--raw</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sends a raw unload command directly to the device, bypassing standard HPLIP routines.<br><br><b><i>-u</i>, <i>--gui</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Invokes a graphical user interface (GUI) for the unload operation, if available.<br><br><b><i>-h</i>, <i>--help</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message with command usage and available options.<br><br><b><i>-v</i>, <i>--version</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the installed HPLIP version on the system.<br><br><b><i>-d</i>, <i>--debug</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables debug mode, providing verbose output useful for troubleshooting issues.<br><br><b><i>--auto</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempts to automatically detect a connected HP device and initiate the unload process without specifying a URI.<br><br><b><i>DEVICE_URI</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the Universal Resource Identifier of the target HP device (e.g., <i>hpaio:/usb/HP_Printer?serial=XXXXXXXXXX</i>). This URI can often be found using <b>hp-info</b> or <b>hp-makeuri</b>.<br><br>


title: DESCRIPTION
content:
<b>hp-unload</b> is a command-line utility provided as part of the HP Linux Imaging and Printing (HPLIP) driver suite. Its primary function is to programmatically unload or eject media, typically documents from the Automatic Document Feeder (ADF) or the scanner glass, of supported HP All-in-One or multifunction devices.<br><br>This command is particularly useful in scenarios where a document might be stuck after a scan operation, or if you need to clear the feeder without physically opening the device or using its control panel buttons. It helps in automating document handling tasks or recovering from minor document feeding issues during batch scanning. The command requires a device URI to identify the target HP device, ensuring the unload command is sent to the correct printer/scanner.


title: CAVEATS
content:
<b>hp-unload</b> requires the HPLIP driver suite to be correctly installed and configured for your HP device. It may not successfully unload media if the document is severely jammed, if the device is not responding, or if the device model does not fully support programmatic unloading. A valid <i>DEVICE_URI</i> is crucial for targeted unloading; otherwise, the command might fail or require <i>--auto</i> detection. This command is primarily designed for HP multifunction devices with ADF capabilities.


title: DEVICE URI IMPORTANCE
content:
The <i>DEVICE_URI</i> is a critical argument that uniquely identifies the target HP device on your system (e.g., via USB, network). Without it, <b>hp-unload</b> cannot direct the unload command to the correct hardware. You can usually find the device URI for your connected HP printer or scanner using <b>hp-info</b> or <b>hp-makeuri</b>, or by checking the output of a successful <b>hp-scan</b> command.


title: TROUBLESHOOTING UNLOAD ISSUES
content:
If <b>hp-unload</b> fails, ensure your device is powered on, properly connected, and not displaying any error states on its own control panel. Using the <i>--debug</i> option can provide more insights into communication failures or underlying problems. For severe paper jams that prevent automated ejection, manual intervention might still be necessary following the device's specific instructions.


title: HISTORY
content:
The <b>hp-unload</b> command is an integral part of the HP Linux Imaging and Printing (HPLIP) project, which was initiated by HP in the early 2000s to provide robust and comprehensive Linux support for their wide range of printers, scanners, and multifunction devices. Its inclusion reflects the need for programmatic control over device functions, particularly for document feeders, to enhance user experience and enable scripting of scanning workflows. Over the years, as HPLIP has evolved with new HP hardware and Linux distributions, <b>hp-unload</b> has remained a core utility for managing media ejection, improving convenience for users handling multi-page documents or resolving minor paper feed issues.


title: SEE ALSO
content:
hp-scan(1), hp-info(1), hp-setup(1), hp-sendfax(1), hp-makeuri(1), scanimage(1), sane-find-scanner(1)


title: SYNOPSIS
content:
<b>hping3</b> [<i>mode</i>] [<i>options</i>] <i>host</i><br><br><b>Common Modes:</b><br>  <i>(default)</i> TCP mode<br>  <b>-0</b>, <b>--rawip</b>  RAW IP mode<br>  <b>-1</b>, <b>--icmp</b>   ICMP mode<br>  <b>-2</b>, <b>--udp</b>    UDP mode<br><br><b>Example Invocation:</b><br>  hping3 -S -p 80 www.example.com<br>  hping3 --icmp --count 5 google.com


title: PARAMETERS
content:
<b><b>-c</b> <i><count></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stop after sending <i><count></i> packets.<br><br><b><b>-i</b> <i><wait></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set interval between packets to <i><wait></i> milliseconds (default is 1 second). Use 'u' for microseconds (e.g., <b>-i u1000</b>).<br><br><b><b>-p</b> <i><port></i>, <b>--destport</b> <i><port></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set destination port (default 0). Can be a specific port or <b>++</b> to increment for each packet (e.g., <b>-p ++80</b>).<br><br><b><b>-s</b> <i><port></i>, <b>--baseport</b> <i><port></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set source port (default random). Use <b>++</b> to increment for each packet.<br><br><b><b>-S</b>, <b>--syn</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set TCP SYN flag.<br><br><b><b>-A</b>, <b>--ack</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set TCP ACK flag.<br><br><b><b>-F</b>, <b>--fin</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set TCP FIN flag.<br><br><b><b>-P</b>, <b>--push</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set TCP PSH flag.<br><br><b><b>-U</b>, <b>--urg</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set TCP URG flag.<br><br><b><b>-R</b>, <b>--rst</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set TCP RST flag.<br><br><b><b>-d</b> <i><size></i>, <b>--data</b> <i><size></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set packet data size (payload size) in bytes. Default is 0.<br><br><b><b>-E</b> <i><file></i>, <b>--file</b> <i><file></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use <i><file></i> as data (payload).<br><br><b><b>-I</b> <i><interface></i>, <b>--interface</b> <i><interface></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify network interface (e.g., eth0, wlan0).<br><br><b><b>-V</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Verbose mode. Show more information about sent and received packets.<br><br><b><b>-q</b>, <b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Quiet mode. Show only the summary.<br><br><b><b>-T</b> <i><ttl></i>, <b>--ttl</b> <i><ttl></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set IP TTL (Time To Live).<br><br><b><b>--traceroute</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Traceroute mode. Increment TTL for each packet to discover hops.<br><br><b><b>--rand-source</b>, <b>--rand-dest</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use random source or destination IP addresses (only for RAW IP mode).<br><br><b><b>--flood</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Send packets as fast as possible, without showing replies. Can be used for DoS attacks.<br><br><b><b>-k</b>, <b>--keep</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Keep original source address, do not change it based on routing table (requires root).<br><br>


title: DESCRIPTION
content:
<b>hping</b> is a free packet generator and analyzer for the TCP/IP protocol. It's a command-line oriented <i>ping</i> program, but unlike the standard <i>ping</i> utility, <b>hping</b> can send custom ICMP, UDP, TCP, and RAW-IP packets. This versatility makes it an invaluable tool for network security professionals, system administrators, and developers.<br><br>It's widely used for testing firewalls, performing port scanning (similar to <b>nmap</b> but with more granular control), network troubleshooting, analyzing network protocols, performing DoS attacks (for testing purposes), and even for OS fingerprinting. <b>hping</b> allows users to specify nearly every aspect of the packet, including source and destination IP addresses, ports, TCP flags (SYN, ACK, PSH, URG, RST, FIN), sequence numbers, TTL, and payload data. It can also act as a simple traceroute, scan ranges of ports, and measure network latency. The current stable version is <b>hping3</b>.


title: CAVEATS
content:
Using <b>hping</b> for packet crafting and sending requires <i>root privileges</i> on most Linux systems, as it needs access to raw network sockets.<br><br>Care should be taken when using options like <b>--flood</b> or <b>hping</b> against systems you do not own or have permission to test, as it can be used for denial-of-service (DoS) attacks or be perceived as hostile network activity. Always ensure you have explicit authorization before scanning or testing any network or system.<br><br>While powerful, <b>hping</b> can be complex for beginners due to the vast number of options and the intricacies of TCP/IP protocols.


title: COMMON USE CASES
content:
<b>Firewall Testing:</b> Determine which ports are open or closed, and how a firewall reacts to different TCP flags (e.g., SYN, ACK, RST packets).<br><b>Port Scanning:</b> Efficiently scan a range of ports on a target host to identify open services.<br><b>Network Troubleshooting:</b> Diagnose network connectivity issues, measure latency, and test network performance.<br><b>OS Fingerprinting:</b> By observing how a target responds to specific packet combinations, one can often infer the operating system.<br><b>DoS Simulation:</b> Test the resilience of a server to a flood of packets (<i>only with explicit permission</i>).


title: BASIC USAGE EXAMPLES
content:
<b>1. Basic SYN Scan (Port 80):</b><br><i>hping3 -S -p 80 example.com</i><br><br>Sends SYN packets to port 80 of example.com. If a SYN/ACK is received, the port is open.<br><br><b>2. ICMP Echo Request (like ping):</b><br><i>hping3 -1 example.com</i><br><br>Sends ICMP echo requests and displays replies.<br><br><b>3. UDP Port Scan (Port 53):</b><br><i>hping3 -2 -p 53 example.com</i><br><br>Sends UDP packets to port 53. If no ICMP Port Unreachable is received, the port might be open.<br><br><b>4. Traceroute Mode:</b><br><i>hping3 --traceroute -p 80 example.com</i><br><br>Performs a traceroute by incrementing the TTL and sending TCP SYN packets to port 80.<br><br><b>5. Sending Custom Data:</b><br><i>hping3 -d 100 -E my_data.txt --tcp-timestamp example.com</i><br><br>Sends 100 bytes of data from 'my_data.txt' with TCP timestamps enabled.


title: HISTORY
content:
<b>hping</b> was originally created by <i>Salvatore Sanfilippo</i>, also known as 'Antirez', a renowned Italian programmer. The first version, <b>hping1</b>, was released in 1998, followed by <b>hping2</b> and the current stable version, <b>hping3</b>.<br><br>It was designed as a low-level packet generator and analyzer, extending the capabilities of the basic <i>ping</i> utility by allowing users to craft custom TCP/IP packets. Its development focused on providing a versatile tool for network security research, penetration testing, and general network diagnostics, quickly becoming a staple in many security toolkits.


title: SYNOPSIS
content:
<b>hr</b> [<i>options</i>]<br><i>Note: This synopsis represents a common usage pattern for various non-standard <b>hr</b> implementations, particularly those focused on drawing horizontal rules. Actual options may vary.</i>


title: PARAMETERS
content:
<b><i>--width</i>, <i>-w</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the desired width of the horizontal rule. If not specified, it often defaults to the terminal's width.<br><br><b><i>--line</i>, <i>-l</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the character(s) used to draw the horizontal line (e.g., '-', '=', '*'). Defaults to a dash character.<br><br><b><i>--color</i>, <i>-c</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the color of the horizontal rule, often using ANSI escape codes or predefined names (e.g., 'red', 'blue').<br><br><b><i>--align</i>, <i>-a</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls the alignment of the rule within the terminal space (e.g., 'left', 'center', 'right').<br><br><b><i>--padding</i>, <i>-p</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds empty space (padding) around the horizontal rule, often specified in characters.<br><br><b><i>--version</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information of the <b>hr</b> utility being used.<br><br><b><i>--help</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the help message and available options for the <b>hr</b> utility.<br><br>


title: DESCRIPTION
content:
The command <b>hr</b> is not a standard utility found in most Linux distributions by default. It commonly refers to a user-defined alias or function, or a third-party command-line tool, primarily used for generating and displaying a horizontal rule (a line of repeating characters) in the terminal. These rules are often employed for visual separation in scripts, logs, or command-line output to improve readability. While its core functionality is simple, specific implementations of <b>hr</b> can offer various customization options, such as specifying the width of the line, the character used to draw it, its color, and alignment. Users typically install such <b>hr</b> utilities separately or define them in their shell configuration files (e.g., <i>.bashrc</i>, <i>.zshrc</i>) to quickly produce decorative or organizational separators. Its non-standard nature means its exact behavior and available options can vary significantly depending on how it's implemented or which specific third-party package is installed.


title: CAVEATS
content:
The <b>hr</b> command is not a standard part of most Linux distributions. Its availability, functionality, and options depend entirely on whether a user has defined it as a shell alias/function or installed a specific third-party utility. Users attempting to use <b>hr</b> without prior installation or definition will likely encounter a "command not found" error. Therefore, its behavior is not universal or predictable across different systems and can vary significantly.


title: COMMON IMPLEMENTATIONS AND INSTALLATION
content:
The most prevalent <b>hr</b> implementations are custom shell aliases/functions (e.g., <i>alias hr='printf %s $(eval printf '%.0s-' {1..$(tput cols)})'</i> for Bash/Zsh) or dedicated third-party packages. For example, Node.js users might install a popular <b>hr</b> utility globally via npm (<b>npm install -g hr</b>), while Python users might find similar utilities through <i>pip</i>. The exact installation steps and available features vary depending on the chosen implementation.


title: HISTORY
content:
The concept of a <b>hr</b> command, for "horizontal rule," largely emerged from the widespread need for simple visual separators in terminal output. Initially, users would achieve this by manually typing repeating characters or using <b>echo</b> with a hardcoded string of dashes. Over time, shell aliases and functions became popular ways to automate this, providing a quick <b>hr</b> command. Various third-party utilities, often written in scripting languages like Node.js or Python, were developed to provide more robust and configurable horizontal rule generation, offering options for width, character, and color, and distributing them via package managers. This evolution reflects a common pattern in the Linux ecosystem where user needs for simple, repetitive tasks lead to custom scripts and eventually dedicated utilities.


title: SYNOPSIS
content:
<b>hsd-cli</b> [<i>options</i>] <i>&lt;command&gt;</i> [<i>arguments</i>]<br><br>Examples:<br><b>hsd-cli</b> <i>getblockchaininfo</i><br><b>hsd-cli</b> <i>wallet getbalance</i><br><b>hsd-cli</b> <i>name info hsd</i>


title: PARAMETERS
content:
<b><i>--config=&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative configuration file for <b>hsd-cli</b> settings.<br><br><b><i>--network=&lt;name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the Handshake network to connect to (e.g., <I>main</I>, <I>testnet</I>, <I>simnet</I>, <I>regtest</I>). Defaults to <I>main</I>.<br><br><b><i>--prefix=&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the data directory prefix for configuration and data storage.<br><br><b><i>--rpc-host=&lt;host&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the RPC host (IP address or hostname) of the <b>hsd</b> node to connect to. Defaults to <I>127.0.0.1</I>.<br><br><b><i>--rpc-port=&lt;port&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the RPC port of the <b>hsd</b> node to connect to. Defaults to <I>12037</I>.<br><br><b><i>--api-key=&lt;key&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides the API key for authenticated RPC calls to the <b>hsd</b> node.<br><br><b><i>--no-auth</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables RPC authentication for the connection. Use with caution, especially on public networks.<br><br><b><i>--ssl</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables SSL/TLS for the RPC connection to the <b>hsd</b> node.<br><br><b><i>--ca-file=&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the CA certificate file for SSL connections.<br><br><b><i>--cert-file=&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the client certificate file for SSL connections.<br><br><b><i>--key-file=&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the client key file for SSL connections.<br><br><b><i>--wallet-id=&lt;id&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the ID of the wallet to interact with, primarily for multi-wallet setups.<br><br><b><i>--wallet-auth</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables wallet RPC authentication, using credentials configured for the wallet.<br><br>


title: DESCRIPTION
content:
The <b>hsd-cli</b> command is the primary command-line interface for interacting with an <i>hsd</i> full node. It allows users to send commands to a running <i>hsd</i> daemon, facilitating a wide range of operations including <br>wallet management (e.g., checking balances, sending transactions), <br>blockchain queries (e.g., retrieving block information, transaction details), <br>and most notably, managing Handshake's decentralized naming system (e.g., registering names, updating DNS records, bidding on auctions). <br><br>It functions as an RPC client, abstracting the complexities of direct RPC calls to the <i>hsd</i> node's API. This tool is essential for developers, miners, and anyone actively participating in or building upon the Handshake blockchain.


title: CAVEATS
content:
<b>hsd-cli</b> requires a running <i>hsd</i> full node daemon to function. If the daemon is not running or is unreachable, commands will fail. <br><br>Proper RPC authentication (via API key or other credentials) is crucial for security, especially when exposing the RPC interface. <br><br>The command's behavior is dependent on the <i>hsd</i> node's synchronization status; blockchain queries may return outdated or incomplete information if the node is not fully synced.


title: RPC COMMAND STRUCTURE
content:
Unlike traditional Linux commands that accept options before arguments, <b>hsd-cli</b> typically uses an RPC-style structure where the first non-option argument is the RPC method name (e.g., <I>getblockchaininfo</I>, <I>wallet</I>, <I>name</I>), followed by method-specific arguments. Sub-commands like <I>wallet</I> or <I>name</I> often have their own sub-methods (e.g., <I>wallet getbalance</I>, <I>name update</I>).


title: DEFAULT CONNECTION
content:
By default, <b>hsd-cli</b> attempts to connect to an <b>hsd</b> node running on <I>localhost</I> (<I>127.0.0.1</I>) at the default RPC port (<I>12037</I>). These defaults can be overridden using the <I>--rpc-host</I> and <I>--rpc-port</I> options.


title: HISTORY
content:
The <b>hsd-cli</b> tool is an integral part of the Handshake project, developed alongside the <i>hsd</i> full node implementation. Its creation was driven by the need for a convenient and programmatic way to interact with the Handshake blockchain and its unique decentralized naming system. Since its inception, it has served as the primary interface for developers, miners, and domain owners to manage their Handshake assets, query blockchain data, and participate in name auctions and updates.


title: SYNOPSIS
content:
Given its non-standard nature, a generic synopsis for <b>hsw-cli</b> would be:<br><i><b>hsw-cli</b></i> [<i>OPTIONS</i>] [<i>COMMAND</i>] [<i>ARGUMENTS</i>]<br><br>The actual options, commands, and arguments will vary wildly depending on the specific implementation of <b>hsw-cli</b>.


title: PARAMETERS
content:
<b><i>--help</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Hypothetical)</i> Displays usage information or a list of available commands and options specific to the <b>hsw-cli</b> implementation.<br><br><b><i>--version</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Hypothetical)</i> Shows the version number of the <b>hsw-cli</b> tool or the associated software/firmware.<br><br><b><i>[command]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Hypothetical)</i> A specific sub-command to perform an action (e.g., <i>status</i>, <i>configure</i>, <i>diagnose</i>, <i>firmware-update</i>). The available commands are entirely dependent on the tool's purpose.<br><br><b><i>[options]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Hypothetical)</i> Options specific to a command or global settings (e.g., <i>-v</i> for verbose, <i>-f</i> for force, <i>-d &lt;device_id&gt;</i>).<br><br><b><i>[arguments]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Hypothetical)</i> Additional data or values required by a command (e.g., <i>set-config &lt;param&gt; &lt;value&gt;</i>, <i>log-level debug</i>).<br><br>


title: DESCRIPTION
content:
The <b>hsw-cli</b> command is <i>not a standard or universally available Linux utility</i>. Its functionality, syntax, and parameters are entirely dependent on the specific software package, hardware vendor, or custom implementation it belongs to. It is highly probable that 'HSW' is an acronym specific to its purpose, such as 'High-Speed Wireless', 'Hardware Software', or a specific product line.<br><br>Typically, such CLI tools are designed to interact with a particular piece of hardware (e.g., network cards, specialized processors, embedded devices) or a proprietary software service. This interaction often involves configuration, monitoring, diagnostic functions, firmware updates, or status reporting. Users encountering <b>hsw-cli</b> should consult the documentation provided with the specific software or hardware installation where this command is present, as generic information is not applicable.


title: CAVEATS
content:
The primary caveat for <b>hsw-cli</b> is its <b>highly contextual nature</b>. It is not a standard Linux command found on all systems. Its existence, purpose, and functionality are tied to a specific software installation, hardware driver, or vendor-specific utility. Therefore, any attempt to use or understand <b>hsw-cli</b> without knowledge of its originating package or hardware is likely to be unproductive or result in an 'command not found' error. Always refer to the documentation provided by the vendor or developer of the specific <b>hsw-cli</b> implementation you are using.


title: IDENTIFYING SPECIFIC <B>HSW-CLI</B> INFORMATION
content:
To determine the exact purpose and usage of <b>hsw-cli</b> on your system, consider the following:<br>1.  <b>Check installation source:</b> Identify which software package or hardware driver installed it.<br>2.  <b>Look for accompanying documentation:</b> Often, custom CLIs come with man pages (e.g., <i>man hsw-cli</i> if one exists) or readme files in their installation directory.<br>3.  <b>Use <i>hsw-cli --help</i> or <i>hsw-cli -h</i>:</b> While not guaranteed, many custom CLIs include built-in help.<br>4.  <b>Search your system:</b> Use <i>which hsw-cli</i> to find its path, then investigate the directory or parent package.


title: PARAMETERS
content:
<b><b>-a</b>, <b>--attribute</b> <<i>NAME</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the value of the specified attribute from matching elements.<br><br><b><b>-t</b>, <b>--text</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs only the inner text content of matching elements, stripping HTML tags.<br><br><b><b>-p</b>, <b>--pretty</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pretty-prints the resulting HTML output with proper indentation.<br><br><b><b>-o</b>, <b>--outer-html</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the complete HTML of matching elements, including the element itself. This is the default output format.<br><br><b><b>--ignore-errors</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Continues processing and ignores errors encountered while loading files or URLs.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief help message and exits.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints version information and exits.<br><br>


title: DESCRIPTION
content:
<i>htmlq</i> is a powerful command-line utility designed for parsing and querying HTML documents, analogous to how <i>jq</i> operates for JSON data. It allows users to extract specific elements or content from HTML by leveraging familiar CSS selectors. Written in Rust, <i>htmlq</i> is known for its speed and efficiency. It can read HTML from standard input (stdin) or directly from files specified by URL or local path. The tool is particularly useful for scripting web scraping tasks, automating data extraction from web pages, or simply inspecting HTML structure from the terminal without needing a browser. Its output can be configured to show the entire matching HTML element, its inner text content, or the value of a specific attribute, making it highly versatile for various data retrieval needs. <i>htmlq</i> simplifies complex HTML parsing into a straightforward command-line operation.


title: CAVEATS
content:
<i>htmlq</i> is primarily effective for static HTML content and is not designed to parse dynamically rendered pages that rely heavily on JavaScript without external tools (e.g., headless browsers). While its CSS selector support is robust for common patterns, some advanced or experimental CSS selectors might not be fully supported. Being a relatively newer tool, its widespread adoption might be less than older, more established utilities.


title: KEY ARGUMENTS
content:
While not 'options' in the traditional sense, these are crucial positional arguments defining <i>htmlq</i>'s primary operation:<br><b><I>SELECTOR</I></b>: The mandatory CSS selector string used to specify which HTML elements to extract. Examples include <code>p</code>, <code>.class-name</code>, <code>#id</code>, <code>a[href]</code>, <code>div > span</code>, etc.<br><b><I>FILE</I> | <I>URL</I>...</b>: Optional input source(s). If provided, <i>htmlq</i> will read HTML content from these local files or fetch it from the specified URLs. If no input source is given, <i>htmlq</i> reads from standard input (stdin).


title: USAGE EXAMPLES
content:
Here are common usage patterns for <i>htmlq</i>:<br><i>Fetch and extract all links from a URL:</i><br><b>curl -s https://example.com | htmlq 'a' --attribute href</b><br><br><i>Extract inner text of specific elements from a local file:</i><br><b>htmlq 'h2.title' --text index.html</b><br><br><i>Pretty-print a specific div from stdin:</i><br><b>cat document.html | htmlq 'div#main-content' --pretty</b>


title: HISTORY
content:
<i>htmlq</i> is an open-source project written in Rust, primarily developed by mgdm. It emerged as a modern, efficient alternative for command-line HTML parsing, drawing inspiration from the user-friendly approach of <i>jq</i> for JSON and the HTML capabilities of tools like <i>pup</i>. Its development aimed to provide a fast and reliable utility for web scraping and HTML data extraction, leveraging Rust's performance benefits and the familiarity of CSS selectors. Since its inception, it has gained traction among developers for its simplicity and effectiveness.


title: PARAMETERS
content:
<b><code>-d</code>, <code>--delay=DELAY</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the delay between updates, in tenths of a second (e.g., <code>-d 10</code> for 1 second).<br><br><b><code>-s</code>, <code>--sort-key=COLUMN</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sorts the process list by the specified column (e.g., <code>-s CPU</code> or <code>-s PERCENT_CPU</code>). Use <code>man htop</code> for a full list of valid column names.<br><br><b><code>-u</code>, <code>--user=USERNAME</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows only the processes of a specific user. Can be a username or user ID.<br><br><b><code>-p</code>, <code>--pid=PID,PID,...</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows only the specified PIDs (Process IDs). Multiple PIDs can be comma-separated.<br><br><b><code>-C</code>, <code>--no-color</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts <code>htop</code> in monochrome (no color) mode.<br><br><b><code>-F</code>, <code>--filter=FILTER</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies an initial filter to the process list. The filter text will be applied immediately upon startup.<br><br><b><code>-h</code>, <code>--help</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message and exits.<br><br><b><code>-v</code>, <code>--version</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays version information and exits.<br><br>


title: DESCRIPTION
content:
<code>htop</code> is an interactive, real-time process viewer and system monitor for Unix-like operating systems. It is designed as an enhanced alternative to the traditional <code>top</code> command, offering a more user-friendly interface and advanced functionalities. Unlike <code>top</code>, <code>htop</code> allows for vertical and horizontal scrolling through the process list, enabling users to view full command lines and all processes without truncation.<br><br>It provides a visual representation of CPU, memory, and swap usage through configurable meters. Users can easily kill processes, renice them, filter the process list, and sort by various criteria directly from the interactive interface using mouse or keyboard shortcuts. Its color-coded output enhances readability, making it easier to identify different process states and resource consumption. <code>htop</code> excels in providing a quick, intuitive overview of system performance and running processes, making it a favorite tool for system administrators and power users.


title: CAVEATS
content:
<code>htop</code> relies on the <code>ncurses</code> library for its interactive terminal interface. It might not be available or installed by default on highly minimal Linux installations. While offering significantly more features than <code>top</code>, its resource consumption can be marginally higher, though this difference is negligible on most modern systems.


title: <B>INTERACTIVE KEYBINDINGS</B>
content:
Common <code>htop</code> interactive keys (also accessible via function keys):<br><b>F1</b>/<b>h</b>: Help<br><b>F2</b>/<b>S</b>: Setup (configure display options)<br><b>F3</b>/<b>/</b>: Search/Filter processes by command name<br><b>F4</b>/<b>\</b>: Filter processes by user or command<br><b>F5</b>/<b>t</b>: Tree view (show processes in a hierarchical tree)<br><b>F6</b>/<b><</b> or <b>></b>: Select column to sort by<br><b>F7</b>/<b>[</b>: Nice - (decrease process priority)<br><b>F8</b>/<b>]</b>: Nice + (increase process priority)<br><b>F9</b>/<b>k</b>: Kill selected process<br><b>F10</b>/<b>q</b>: Quit <code>htop</code><br><b>Space</b>: Tag process (select multiple for batch operations)<br><b>l</b>: Show open files for selected process (requires <code>lsof</code>)<br><b>s</b>: Show system calls for selected process (requires <code>strace</code>)<br><b>M</b>: Sort by Memory usage<br><b>P</b>: Sort by CPU usage<br><b>T</b>: Sort by running Time<br><b>K</b>: Hide kernel threads<br><b>H</b>: Hide user threads<br><b>I</b>: Invert sort order<br><b>u</b>: Filter by user


title: <B>CUSTOMIZATION</B>
content:
The <code>htop</code> setup screen (accessible via <b>F2</b> or <b>S</b>) allows extensive customization of the display. Users can select which meters appear at the top (e.g., CPU, Memory, Swap, Load Average), their order, and their display style (e.g., text, bar, LED). They can also choose which columns are displayed in the process list (e.g., PID, User, CPU%, MEM%, Command), their order, and width. Additionally, <code>htop</code> offers several built-in color schemes to suit different preferences or terminal backgrounds. This high degree of customizability allows users to tailor <code>htop</code> to their specific monitoring needs and preferences, making it an incredibly versatile tool.


title: HISTORY
content:
<code>htop</code> was created by Hisham Muhammad and first publicly released around 2004. It was developed as a more user-friendly and feature-rich alternative to the traditional <code>top</code> utility, addressing several limitations and frustrations users often encountered with <code>top</code>, such as the inability to scroll horizontally, easily kill processes, or sort by arbitrary columns without complex commands. Its development focused on providing an interactive, colorful, and intuitive interface for process management and system monitoring, quickly gaining popularity among Linux users and becoming a staple tool in many distributions.


title: PARAMETERS
content:
<b><b>-c</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Create a new <i>passwdfile</i>. If the file already exists, it will be truncated and overwritten. This option must be used only when creating a new file.<br><br><b><b>-n</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not update the <i>passwdfile</i>; instead, output the results to standard output. This is useful for scripting or testing.<br><br><b><b>-m</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the use of <i>MD5</i> encryption for passwords. <i>MD5</i> was historically a common default, but is now considered less secure.<br><br><b><b>-B</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the use of <i>BCrypt</i> encryption for passwords. <i>BCrypt</i> is a strong, adaptive hashing algorithm and is generally recommended for new password entries due to its resistance to brute-force attacks.<br><br><b><b>-C</b> <i>cost</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the computing <i>cost</i> factor for <i>BCrypt</i> (logarithmic scale, typical values 5-12). Higher values increase security but require more CPU time for hashing.<br><br><b><b>-s</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the use of <i>SHA</i> encryption for passwords. <i>SHA</i> is also an older hashing method.<br><br><b><b>-d</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the use of <i>CRYPT</i> encryption for passwords. This is the weakest and least secure method, often relying on traditional UNIX <i>crypt(3)</i>.<br><br><b><b>-p</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not encrypt the password; store it as plain text. <b>This option is highly insecure and should never be used in production environments.</b><br><br><b><b>-b</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable batch mode. The password is provided directly on the command line as the third argument. <b>Avoid using this for security-critical passwords as it exposes the password in command history.</b><br><br><b><b>-i</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Read the password interactively from standard input. This overrides the <b>-b</b> option and is generally safer than <b>-b</b>.<br><br><b><b>-D</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Delete the specified <i>username</i> from the <i>passwdfile</i>.<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Verify the provided <i>password</i> against the hash stored for the <i>username</i> in the <i>passwdfile</i>. Outputs success or failure.<br><br><b><b>-x</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Read usernames to be deleted from standard input. Each username should be on a new line.<br><br>


title: DESCRIPTION
content:
The <i>htpasswd</i> command is a utility used to create and update flat-files containing usernames and encrypted passwords for <i>HTTP Basic Authentication</i>. These files are primarily utilized by the Apache HTTP Server to protect directories or resources, requiring clients to provide credentials before access. <br><br>When executed, <i>htpasswd</i> prompts for a new password (unless in batch mode), encrypts it using a specified algorithm (such as <i>MD5</i>, <i>SHA</i>, <i>BCrypt</i>, or the older <i>CRYPT</i> method), and stores the username and encrypted password in the designated file. It can add new users, update existing user passwords, or delete users. <br><br>While straightforward and easy to implement for small-scale authentication needs, it's crucial to understand that <i>htpasswd</i> relies on storing password hashes in a simple file. For enhanced security, especially for sensitive data or large user bases, more robust authentication mechanisms like database-backed systems or external identity providers are generally recommended. However, for quick protection of specific web resources, <i>htpasswd</i> remains a widely used and effective tool.


title: CAVEATS
content:
The <i>passwdfile</i> generated by <i>htpasswd</i> is a flat-file database of user credentials. <b>It is absolutely critical that this file is not accessible directly via the web server.</b> It should be placed outside the web document root (e.g., in <i>/etc/apache2/passwd/</i>) or its access should be explicitly denied by Apache configuration. <br><br>While <i>htpasswd</i> offers various hashing algorithms, older methods like <i>CRYPT</i> and <i>MD5</i> are considered weak against modern cracking techniques; <i>BCrypt</i> is the recommended choice for new entries. Storing passwords in plain text (using <b>-p</b>) is an extreme security risk and must be avoided. <br><br><i>htpasswd</i> is not designed for concurrent writes from multiple processes; simultaneous modifications can lead to file corruption. It's best suited for single-user management or scripted updates.


title: AUTHENTICATION METHOD
content:
<i>htpasswd</i> is specifically designed for use with Apache's <i>mod_auth_basic</i> (or similar modules) to implement <i>HTTP Basic Authentication</i>. This method transmits credentials (username and password) over the network, typically encoded in Base64. <b>For sensitive data, it is crucial to use <i>HTTPS</i> (SSL/TLS) to encrypt the communication channel and prevent credentials from being intercepted in plain text.</b>


title: FILE PERMISSIONS AND LOCATION
content:
The <i>passwdfile</i> should have strict file permissions, typically readable only by the Apache user (e.g., <i>www-data</i> or <i>apache</i>) and root. It should be placed outside the web server's document root (e.g., in <i>/etc/apache2/passwd/</i> or a similar secure location) to prevent direct access via a web browser. Incorrect permissions or location are common security vulnerabilities.


title: HISTORY
content:
The <i>htpasswd</i> utility has been an integral part of the Apache HTTP Server project since its inception in the mid-1990s. Its primary role has always been to provide a simple, file-based mechanism for <i>HTTP Basic Authentication</i>. Over the years, its development has largely focused on enhancing security by incorporating stronger password hashing algorithms. <br><br>Initially, it primarily supported the weak <i>CRYPT</i> algorithm (derived from UNIX <i>crypt(3)</i>). Later versions introduced <i>MD5</i> and <i>SHA</i> for improved security. More recently, support for <i>BCrypt</i> was added, addressing the need for a more robust, adaptive hashing function resistant to brute-force attacks. This evolution reflects the ongoing effort to balance ease of use with the increasing demands of cybersecurity.


title: PARAMETERS
content:
<b>-s, --silent</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress normal output. Only error messages will be displayed.<br><br><b>-q, --query</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Query mode. Print the remote time but do not set the local clock. Useful for checking the time difference without requiring root privileges.<br><br><b>-d, --debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable debug output for detailed information about the request and response.<br><br><b>-t <attempts>, --attempts=<attempts></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the maximum number of attempts to connect to the server and retrieve the time. Default is 1.<br><br><b>-l, --localtime</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Treat the received time as local time rather than UTC. This is usually not recommended as system clocks are typically UTC.<br><br><b>-i <interval>, --interval=<interval></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run in daemon mode, synchronizing the clock every <i>interval</i> seconds. Requires root privileges.<br><br><b>-p <proxy>, --proxy=<proxy></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use the specified HTTP proxy server. Format: <i>host:port</i>.<br><br><b>-a <user-agent>, --user-agent=<user-agent></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a custom <i>User-Agent</i> string for the HTTP request.<br><br><b>-c <certfile>, --certfile=<certfile></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the client certificate file for HTTPS authentication.<br><br><b>-k <keyfile>, --keyfile=<keyfile></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the client private key file for HTTPS authentication.<br><br><b>-r <rootcafile>, --rootcafile=<rootcafile></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to a file containing trusted CA certificates (PEM format) for verifying the server's SSL certificate.<br><br><b>-H <hostheader>, --hostheader=<hostheader></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a custom <i>Host</i> header for the HTTP request, useful for virtual hosting.<br><br><b>-S <ciphers>, --ciphers=<ciphers></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a list of acceptable SSL ciphers (e.g., 'ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH').<br><br><b>-u <user:password>, --user=<user:password></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify username and password for proxy authentication.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output, showing more details about the process.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display version information and exit.<br><br>


title: DESCRIPTION
content:
The <b>htpdate</b> command is a utility designed to synchronize the system's local clock by querying the time from a remote HTTP or HTTPS server. It extracts the time information from the <i>Date:</i> header of an HTTP response, making it a viable alternative to the Network Time Protocol (NTP) in environments where NTP ports are blocked but HTTP/HTTPS traffic is permitted. While generally less accurate than NTP due to reliance on TCP/IP latency and the server's HTTP header generation, <b>htpdate</b> provides a simple and effective method for time synchronization, particularly for clients or embedded systems behind strict firewalls or on networks with limited NTP access. It typically requires root privileges to modify the system clock.


title: CAVEATS
content:
<b>htpdate</b> is generally less accurate than NTP for time synchronization due to inherent TCP/IP latency and the imprecise nature of the HTTP <i>Date</i> header. It relies on the remote web server's clock being accurate and correctly set. Furthermore, it requires root privileges to set the system clock, and its effectiveness can be limited by firewalls or proxies that deeply inspect or modify HTTP headers.


title: USE CASES
content:
<b>htpdate</b> is ideal for systems in highly firewalled environments where only HTTP/HTTPS traffic is allowed. It's also suitable for devices or virtual machines that require basic time synchronization but lack full NTP client capabilities or where a full NTP daemon is considered overkill.


title: SECURITY CONSIDERATIONS
content:
When using HTTPS (<i>https://</i> URL), <b>htpdate</b> can verify the server's certificate. However, unlike NTP which includes authentication mechanisms, <b>htpdate</b> relies solely on the integrity of the HTTP <i>Date</i> header from the specified server. If the server is compromised or the <i>Date</i> header is manipulated, an attacker could potentially set an incorrect system time.


title: HISTORY
content:
Developed as a simple alternative to NTP, <b>htpdate</b> addresses scenarios where NTP might be unavailable or blocked by network firewalls. It provides a lightweight solution for basic clock synchronization by leveraging common HTTP/HTTPS ports (80/443), which are often open. Its niche is particularly relevant for embedded systems or clients in restrictive network environments where precise NTP synchronization isn't critical, but some level of clock accuracy is required.


title: SYNOPSIS
content:
<b>http</b> [<i>flags</i>] [<i>METHOD</i>] <i>URL</i> [<i>ITEM</i> [<i>ITEM</i> ...]]<br><br><b><i>METHOD</i></b>: Optional. The HTTP method (e.g., <b>GET</b>, <b>POST</b>, <b>PUT</b>, <b>DELETE</b>). If omitted, <b>GET</b> is the default unless request data is provided, in which case <b>POST</b> is inferred.<br><b><i>URL</i></b>: The target URL for the request.<br><b><i>ITEM</i></b>: Represents request data, headers, or files, defined as follows:<br><ul><li><b>KEY=VALUE</b>: Request data (form-encoded, e.g., <i>username=john</i>)</li><li><b>KEY:=VALUE</b>: JSON request data (e.g., <i>user:='{"id":1}'</i>)</li><li><b>KEY:=@FILE</b>: JSON field from file content (e.g., <i>data:=@data.json</i>)</li><li><b>KEY=@FILE</b>: File upload for a field (e.g., <i>image=@pic.jpg</i>)</li><li><b>@FILE</b>: Request body from a file (e.g., <i>@request.json</i>)</li><li><b>HEADER:VALUE</b>: Request header (e.g., <i>Authorization:Bearer TOKEN</i>)</li></ul>


title: PARAMETERS
content:
<b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the whole request and response, including headers and body.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show a help message and exit.<br><br><b>-p, --print <WHAT></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify what parts of the request/response to print. Use a combination of 'H' (request headers), 'B' (request body), 'h' (response headers), 'b' (response body). Default is 'hb'.<br><br><b>-o, --output FILE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Save output to a file instead of printing to stdout.<br><br><b>-d, --download</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Download the response body to a file. Implies <b>--output</b>, with the filename derived from the URL or Content-Disposition header.<br><br><b>-a, --auth USER:PASS</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify HTTP authentication credentials (e.g., 'user:password').<br><br><b>--auth-type TYPE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the authentication type. Common types are 'basic' (default) and 'digest'.<br><br><b>-j, --json</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Serialize data items as a JSON object (this is the default behavior if not specified).<br><br><b>-f, --form</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Serialize data items as a form-encoded string (<i>application/x-www-form-urlencoded</i>).<br><br><b>-x, --proxy PROTOCOL:HOST</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a proxy server (e.g., 'http:localhost:8080').<br><br><b>--verify <VALUE></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Verify SSL certificates. Can be 'yes' (default), 'no', or a path to a CA bundle file.<br><br><b>--timeout SECONDS</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set a timeout for the request in seconds.<br><br><b>-F, --follow</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Follow redirects.<br><br>


title: DESCRIPTION
content:
<i>HTTPie</i> (pronounced "aitch-tee-tee-pie") is a user-friendly command-line HTTP client. It aims to make CLI interaction with web services as human-friendly as possible, focusing on intuitive syntax, readable output, and convenience.<br><br>Designed for testing, debugging, and general interaction with HTTP servers, it simplifies common tasks such as making requests, inspecting responses, and handling data formats like JSON.<br><br>Key features include:<br><ul><li><b>Expressive syntax</b>: Requests are built with natural-looking key-value pairs for data and headers.</li><li><b>JSON by default</b>: Automatically infers JSON for request bodies and prettifies JSON responses, making API interaction seamless.</li><li><b>Colorized output</b>: Responses are syntax-highlighted for better readability.</li><li><b>Built-in authentication</b>: Supports various authentication schemes like Basic, Digest, and OAuth.</li><li><b>File uploads and downloads</b>: Easily handles file transfers.</li><li><b>Proxy support</b>: Configurable proxy settings.</li></ul>It offers a modern alternative to <i>curl</i>, prioritizing readability and ease of use over <i>curl's</i> vast array of options, which can sometimes be overwhelming for simple tasks. Its focus on modern web development workflows makes it a popular choice for developers and testers.


title: CAVEATS
content:
<ul><li><b>Python Dependency</b>: <i>HTTPie</i> is written in Python and requires a Python environment to be installed on the system.</li><li><b>Not Pre-installed</b>: Unlike <i>curl</i> or <i>wget</i>, <i>HTTPie</i> is generally not pre-installed on most Linux distributions and needs to be installed separately, typically via <i>pip</i> or a package manager.</li><li><b>Performance</b>: For extremely simple or repetitive requests, <i>curl</i> (being a C application) might offer marginally better performance due to lower overhead compared to <i>HTTPie's</i> Python-based execution.</li></ul>


title: JSON BY DEFAULT
content:
Unlike many other HTTP clients, <i>HTTPie</i> treats request data without explicit type indicators as JSON by default. This significantly streamlines interaction with JSON-based APIs, as users simply provide key-value pairs (e.g., <i>key=value</i>), and <i>HTTPie</i> automatically handles the JSON serialization. Response bodies that are JSON are also automatically pretty-printed and syntax-highlighted, greatly enhancing readability.


title: READABLE OUTPUT
content:
<i>HTTPie</i> prides itself on presenting HTTP responses in a clear, human-readable format. It automatically syntax-highlights headers and body content, especially JSON, making it easy to parse complex responses at a glance. This focus on aesthetic and functional output reduces the cognitive load during API development and debugging, making it a favorite for debugging and quick API tests.


title: HISTORY
content:
<i>HTTPie</i> was created by Jakub Roztocil and first released in 2012. Its development was motivated by a desire for a more intuitive and developer-friendly command-line HTTP client compared to existing tools like <i>curl</i>, which, while powerful, could be seen as having a steeper learning curve for modern web API interactions.<br><br>It quickly gained popularity for its focus on sensible defaults (like JSON support), expressive syntax, and readable, colorized output, making it an excellent tool for testing, debugging, and interacting with RESTful APIs. Its design principles prioritize human-friendliness, leading to widespread adoption within the developer community.


title: SYNOPSIS
content:
<b>http-prompt</b> <i>[<options>] [<initial_url>]</i><br><i>Starts an powerful interactive HTTP prompt, optionally pre-configured with a URL or session.</i>


title: PARAMETERS
content:
<b><b>--auth</b> <i>USER:PASS</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies HTTP basic or digest authentication credentials.</i><br><br><b><b>--auth-type</b> <i>TYPE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Sets the authentication type (<b>basic</b> or <b>digest</b>).</i><br><br><b><b>--proxy</b> <i>PROTOCOL:HOST</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Configures an HTTP proxy for requests.</i><br><br><b><b>--verify</b> <i>VALUE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Controls SSL certificate verification (<b>yes</b>, <b>no</b>, or a path to a CA bundle).</i><br><br><b><b>--ignore-netrc</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Prevents the use of credentials stored in <b>.netrc</b>.</i><br><br><b><b>--session</b> <i>PATH</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Loads or saves the session state to a specified file.</i><br><br><b><b>--body</b> <i>FILE_PATH</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Sets the request body content from a file.</i><br><br><b><b>--timeout</b> <i>SECONDS</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Sets a timeout duration for network requests.</i><br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Displays the current version of http-prompt and exits.</i><br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Shows the command's help message and exits.</i><br><br>


title: DESCRIPTION
content:
http-prompt is an interactive command-line HTTP client designed for effortless API testing and development. It provides a rich interactive prompt with features like auto-completion for headers, methods, and URLs, syntax highlighting, and persistent sessions. Built upon the powerful <b>Requests</b> library and inspired by <b>HTTPie</b>, it simplifies complex HTTP interactions by maintaining context across requests. Users can intuitively build, send, and inspect HTTP requests, making it an excellent tool for exploring RESTful APIs. It maintains a state, allowing you to modify previous requests, set default headers, and manage authentication credentials easily.


title: CAVEATS
content:
<i>Requires Python and its dependencies (<b>requests</b>, <b>httpie</b>, <b>prompt_toolkit</b>). While powerful for interactive use, it is not designed for scripting automated tasks in the same way <b>curl</b> or <b>HTTPie</b> are. Its primary strength lies in its interactive exploration and debugging capabilities.</i>


title: <I>INTERACTIVE MODE</I>
content:
<i>Once started, <b>http-prompt</b> enters an interactive shell where users can type HTTP methods, URLs, headers, and data. It supports various commands for managing the session, viewing history, and sending requests. The prompt provides real-time auto-completion and syntax highlighting, greatly speeding up API exploration.</i>


title: <I>SESSION MANAGEMENT</I>
content:
<i>A key feature is its ability to manage sessions. You can load or save your current request context (headers, authentication, base URL) to a file, allowing you to resume work or share configurations with others. This persistence is invaluable for continuous API development and testing.</i>


title: HISTORY
content:
<i><b>http-prompt</b> was created by @eliang, drawing inspiration from the user-friendly syntax of <b>HTTPie</b> and the powerful request capabilities of the <b>Requests</b> library. It was initially released around 2016, aiming to bridge the gap between simple command-line HTTP clients and more complex graphical tools by providing an interactive, stateful environment for API interaction and testing. Its development has focused on enhancing user experience through features like smart auto-completion and session management.</i>


title: SYNOPSIS
content:
<b>http-server</b> [<I>path</I>] [<I>options</I>]<br><br><I>path</I>: Optional. The directory to serve. Defaults to the current working directory (.).


title: PARAMETERS
content:
<b>-p, --port <port></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The port to listen on. Defaults to <i>8080</i>.<br><br><b>-a, --addr <address></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The address to bind to. Defaults to <i>0.0.0.0</i> (all available network interfaces).<br><br><b>-s, --silent</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress all output except for errors.<br><br><b>-d, --debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show more debug info.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show help information and exit.<br><br><b>-v, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show version number and exit.<br><br><b>-c, --cache <seconds></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the <i>Cache-Control</i> max-age header. Defaults to <i>3600</i> seconds (1 hour). Use <i>-1</i> for no-cache.<br><br><b>--cors [<header>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable <i>CORS</i> via the <i>Access-Control-Allow-Origin</i> header. Optionally specify a custom header value, e.g., "<i>*</i>".<br><br><b>-S, --ssl</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable <i>HTTPS</i>. Requires <i>--key</i> and <i>--cert</i>.<br><br><b>-K, --key <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the <i>SSL</i> key file.<br><br><b>-C, --cert <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the <i>SSL</i> certificate file.<br><br><b>-o, --open</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Open the browser to the server URL once it's ready.<br><br><b>-i, --index <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the default index file name. Defaults to <i>index.html</i>.<br><br><b>-L, --no-dotfiles</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not serve dotfiles (files starting with a period).<br><br><b>-E, --etags</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable <i>ETag</i> generation.<br><br><b>-U, --utc</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use <i>UTC</i> time in logs.<br><br><b>-P, --proxy <url></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Proxies all requests that are not found to the specified <i>url</i>.<br><br><b>-r, --robots</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Respond to <i>/robots.txt</i> with "User-agent: *<br>Disallow: /". (This is a single line, formatted as HTML to represent multiline text)<br><br><b>-x, --ext <extension></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Default file extension for requests. E.g., <i>--ext .html</i> will serve <i>foo.html</i> for a request to <i>/foo</i>.<br><br>


title: DESCRIPTION
content:
The <b>http-server</b> command provides a rapid and easy way to serve static files over HTTP from the command line. It is a popular <i>Node.js</i> module, designed for local development, testing, and sharing files within a network without complex server configurations. <br> <br> It automatically serves the current directory, or a specified path, making it ideal for front-end development, showcasing prototypes, or running single-page applications. Key features include support for CORS, caching, SSL, directory listing, and automatic opening of a browser upon startup. Its simplicity and portability (where Node.js is installed) make it a go-to tool for quick web serving needs, although it is <i>not recommended for production environments</i> due to its basic security and performance characteristics.


title: CAVEATS
content:
<ul><li><b>Node.js Dependency</b>: The <b>http-server</b> command is a <i>Node.js</i> package and requires <i>Node.js</i> and <i>npm</i> (or <i>yarn</i>) to be installed on your system. It is not a native Linux binary.</li><li><b>Development Use Only</b>: It is designed for development and local testing. It lacks advanced features, security measures, and performance optimizations required for production-grade web servers.</li><li><b>Static File Serving</b>: Primarily serves static files. It does not execute server-side scripts (e.g., PHP, ASP.NET) directly.</li></ul>


title: INSTALLATION
content:
To use <b>http-server</b>, you typically install it globally via <i>npm</i> or <i>yarn</i>: <br> <i>npm install -g http-server</i> <br> or <br> <i>yarn global add http-server</i>


title: BASIC USAGE EXAMPLE
content:
To serve files from the current directory on port <i>8080</i>: <br> <i>http-server</i> <br> To serve files from a specific directory on port <i>3000</i> and open in browser: <br> <i>http-server ./my-project -p 3000 -o</i>


title: HISTORY
content:
The <b>http-server</b> module was created by <i>Nodejitsu</i> (now <i>Npm, Inc.</i>) and is maintained by the <i>Node.js community</i>. It gained popularity rapidly due to its ease of use and the growing ecosystem of <i>Node.js</i> and front-end development workflows. It serves as a classic example of a "batteries included" tool for quickly getting a local HTTP server up and running, fulfilling a common need for developers to test web content directly in a browser without complex setup.


title: SEE ALSO
content:
<b>python3 -m http.server</b>: Python's built-in simple HTTP server, similar in functionality., <b>nginx(8)</b>: A high-performance, production-ready web server and reverse proxy., <b>apache2(8)</b>: A widely-used, robust, and feature-rich open-source HTTP server., <b>serve</b>: Another popular Node.js static file server, often used in conjunction with modern JavaScript frameworks.


title: PARAMETERS
content:
<b><I>directory</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the root directory from which to serve files. If omitted, the current working directory is typically used.<br><br><b><I>--port</I> <I>PORT</I>, <I>-p</I> <I>PORT</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the TCP port on which the server will listen for incoming connections. Default is often 8080 or 8000.<br><br><b><I>--host</I> <I>HOST</I>, <I>-a</I> <I>HOST</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the IP address or hostname for the server to bind to. Default is often 0.0.0.0 (all interfaces) or 127.0.0.1 (localhost).<br><br><b><I>--upload</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly enables the file upload feature. In some implementations, this might be implied by the command name or enabled by default.<br><br><b><I>--username</I> <I>USER</I>, <I>--password</I> <I>PASS</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Configures basic authentication for accessing the server and/or the upload functionality, requiring a username and password.<br><br><b><I>--cors</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables Cross-Origin Resource Sharing (CORS) headers, allowing requests from different origins.<br><br><b><I>--ssl</I> <I>CERT_FILE</I> <I>KEY_FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables HTTPS/SSL, requiring paths to a SSL certificate file and its corresponding key file.<br><br><b><I>--help</I>, <I>-h</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message with available command-line options and usage instructions.<br><br>


