# CommandSection

title: DESCRIPTION
content:
<i>tlmgr-arch</i> is an Arch Linux-specific wrapper script for the TeX Live package manager, <i>tlmgr</i>. On Arch Linux, TeX Live is typically installed system-wide via <i>pacman</i>. This differs from a standard TeX Live installation, which is usually self-contained in a dedicated directory. <i>tlmgr-arch</i> bridges this gap by setting the appropriate environment variables (like <i>TEXLIVE_INSTALL_ROOT</i> or <i>TEXMFROOT</i>) before invoking <i>tlmgr</i>.<br><br>This ensures that <i>tlmgr</i> operations, such as installing new packages, updating existing ones, or managing collections, interact correctly with the Arch-managed TeX Live installation and avoid conflicts with files handled by <i>pacman</i>. It allows users to leverage <i>tlmgr</i>'s full functionality for adding components that are not part of the standard Arch TeX Live packages or for managing local additions.


title: CAVEATS
content:
Always use <i>tlmgr-arch</i> instead of direct <i>tlmgr</i> on Arch Linux to prevent conflicts and ensure proper pathing, especially if you have both <i>pacman</i>-installed and <i>tlmgr</i>-installed components.<br><br><i>tlmgr-arch</i> primarily manages TeX Live components installed by <i>tlmgr</i> itself (e.g., in <i>/usr/local/share/texmf-dist</i> or <i>/opt/texlive</i> depending on the Arch setup for <i>tlmgr-arch</i>), not those installed and managed directly by <i>pacman</i>. For <i>pacman</i>-managed components, use <i>pacman</i> commands (e.g., <i>sudo pacman -S texlive-most</i>).<br><br>Some distributions might place the TeX Live user trees in different locations; <i>tlmgr-arch</i> aims to correctly identify this for Arch.


title: WHY TLMGR-ARCH IS NECESSARY ON ARCH LINUX
content:
On Arch Linux, TeX Live is installed and maintained primarily through the <i>pacman</i> package manager. This places TeX Live components into standard system directories like <i>/usr/share/texmf-dist</i>. In contrast, the official TeX Live distribution provides <i>tlmgr</i>, which expects a self-contained installation (e.g., in <i>/usr/local/texlive</i>).<br><br>Directly using <i>tlmgr</i> on an Arch-installed TeX Live without proper setup can lead to issues such as files being written to unexpected locations, permissions problems, or conflicts with <i>pacman</i>'s file tracking, potentially breaking your TeX Live installation or interfering with system integrity. <i>tlmgr-arch</i> solves this by correctly configuring the environment for <i>tlmgr</i>, allowing it to safely manage packages that are *not* provided by <i>pacman</i> (e.g., new packages, specific versions, or local additions) without corrupting the <i>pacman</i>-managed core TeX Live installation. It ensures that <i>tlmgr</i> operations target the correct user-writable locations while respecting the system-managed components.


title: HISTORY
content:
<i>tlmgr-arch</i> emerged as a necessary utility within the Arch Linux ecosystem due to the inherent differences in how TeX Live is typically installed and managed. While TeX Live's own package manager, <i>tlmgr</i>, is designed for self-contained installations that manage their entire directory tree, Arch Linux's philosophy dictates system-wide integration via <i>pacman</i>. This often means TeX Live files are scattered across standard system directories (e.g., <i>/usr/share/texmf-dist</i>). Directly running <i>tlmgr</i> on such an installation could lead to inconsistencies, permissions issues, or conflicts with <i>pacman</i>-managed files.<br><br>To resolve this, Arch developers or community members created <i>tlmgr-arch</i> as a wrapper. Its primary function is to set the correct environment variables and paths, allowing <i>tlmgr</i> to operate safely on the Arch-installed TeX Live, primarily for adding packages not included in Arch's <i>texlive-*</i> bundles or for managing user-specific TeX Live trees.


title: SYNOPSIS
content:
<b>tlmgr</b> backup [<i>options</i>] [<i>pkg</i>...]<br><b>tlmgr</b> backup <b>--all</b><br><b>tlmgr</b> backup <b>--list</b><br><b>tlmgr</b> backup <b>--delete</b> <i>N</i> | <b>--clean</b> <i>N</i>


title: PARAMETERS
content:
<b>--all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Backs up all currently installed TeX Live packages that are eligible for backup.<br><br><b>[pkg...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies one or more individual package names to back up. If no packages are specified and `--all` is not used, `tlmgr` will usually prompt or do nothing.<br><br><b>--list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all currently available backups, showing package names and their stored versions.<br><br><b>--delete N, --clean N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deletes backups that are older than <i>N</i> days. This helps manage disk space consumed by backups.<br><br><b>--dry-run, --no-execute</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a trial run without making any actual changes. It shows what would happen if the command were executed.<br><br><b>--no-checksums</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables the calculation of checksums for the backed-up files. This can speed up the backup process but reduces integrity verification.<br><br><b>--quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses most output messages, useful for scripting.<br><br>


title: DESCRIPTION
content:
`tlmgr backup` is a subcommand of the TeX Live Manager (tlmgr) utility designed to create and manage backups of installed TeX Live packages. This functionality is crucial for maintaining the stability of a TeX Live installation, as it allows users to revert to previous versions of packages in case an update introduces regressions or issues.<br><br>When executed, `tlmgr backup` stores older versions of package files, typically within a `.tlpkg/backup` directory inside the TeX Live installation tree. It can be used to back up specific packages, all installed packages, or to manage existing backups by listing or deleting them. While `tlmgr backup` is solely responsible for creating and maintaining these archives, the actual process of reverting to a backed-up version is handled by the `tlmgr restore` command or the `--rollback` option of `tlmgr update`.<br><br>The ability to create backups provides a safety net for users, ensuring that even after performing updates, a working configuration can be restored if necessary.


title: CAVEATS
content:
<ul><li>Backups consume significant disk space, especially when backing up many packages or using the `--all` option frequently.</li><li>`tlmgr-backup` only archives TeX Live package files; it does not back up user-specific configuration files, custom installed fonts, or documents.</li><li>The restoration process is handled by separate commands (`tlmgr restore` or `tlmgr update --rollback`), not `tlmgr backup` itself.</li></ul>


title: BACKUP STORAGE
content:
By default, `tlmgr` stores backups in a `.tlpkg/backup` subdirectory located within the root of your TeX Live installation. Each backed-up package version typically resides in its own compressed archive or directory within this structure.


title: AUTOMATIC BACKUPS
content:
TeX Live can be configured to automatically create backups during `tlmgr update` and `tlmgr install` operations. This behavior is controlled by the `autobackup` option, which can be enabled or disabled using `tlmgr option autobackup <0|1>`.


title: RESTORATION WORKFLOW
content:
It is crucial to understand that `tlmgr backup` merely <i>creates</i> the backup files. To revert to a previous version of a package, you must use `tlmgr restore <pkg> [version]` or, for system-wide rollbacks, `tlmgr update --rollback`.


title: HISTORY
content:
`tlmgr` (TeX Live Manager) was introduced in TeX Live 2008 as a comprehensive replacement for older management tools like `texconfig-sys` and `pkgtool`. The `backup` subcommand was an integral part of this new system, providing essential rollback capabilities for package updates and installations. Its introduction significantly improved the stability and maintainability of TeX Live installations by offering a reliable mechanism to revert to previous working states, especially as online updates became the standard.


title: SEE ALSO
content:
tlmgr(1): The main TeX Live Manager utility., tlmgr restore(1): Restores packages from backups created by `tlmgr backup`., tlmgr update(1): Updates installed TeX Live packages; can automatically trigger backups., tlmgr option(1): Manages TeX Live configuration options, including `autobackup`.


title: SYNOPSIS
content:
<I>Note: <br>&#34;tlmgr-candidates&#34; is not a direct executable command.<br>It refers to the concept of packages eligible for update within the TeX Live ecosystem.<br>To interact with update candidates, you typically use the following <I>tlmgr</I> commands:</I><br><br><b>tlmgr update --list</b><br><b>tlmgr update --dry-run</b><br><b>tlmgr update [<i>package...</i>]</b>


title: PARAMETERS
content:
<b><I>--list</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all packages that are identified as update candidates by <I>tlmgr</I> without performing any actual updates. This shows the packages along with their current and available versions.<br><br><b><I>--dry-run</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a simulation of the update process, showing which packages would be updated, installed, or removed, and resolving dependencies. Similar to <I>--list</I> but provides more detailed action plans.<br><br><b><I>--all</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When used with <I>tlmgr update</I>, this option instructs <I>tlmgr</I> to update all identified candidates (all packages for which a newer version is available in the repository).<br><br><b><I>--self</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Updates <I>tlmgr</I> itself, which is often treated as a special candidate due to its role in managing the TeX Live installation.<br><br><b><I>--repository <I>URL</I></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative repository URL from which to check for update candidates. This allows checking for updates from a specific mirror or a local repository.<br><br><b><I>--force</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Overrides some checks or warnings, potentially forcing an update even if <I>tlmgr</I> has concerns about the candidate.<br><br>


title: DESCRIPTION
content:
&#34;tlmgr-candidates&#34; is not a direct executable command in Linux. Instead, it refers to the crucial internal process and criteria used by <I>tlmgr</I> (the TeX Live Manager) to identify packages that are eligible for an update. When a user initiates an update operation, for example with <I>tlmgr update</I>, the first step involves <I>tlmgr</I> querying its configured TeX Live repositories to determine if newer versions of currently installed packages exist. These identified packages, which have a more recent version available remotely, are termed &#34;update candidates.&#34; The process involves a sophisticated comparison of version numbers, dependencies, and sometimes even checksums between the locally installed package and the remote offering. Factors such as the current TeX Live release (e.g., TL2023, TL2024) and the specific repository mirror chosen (e.g., a CTAN mirror) directly influence which packages appear as candidates. Users do not execute &#34;tlmgr-candidates&#34; directly; rather, they interact with this concept by using <I>tlmgr</I>&#39;s update-related subcommands. For instance, <I>tlmgr update --list</I> or <I>tlmgr update --dry-run</I> are commands that will explicitly show the list of packages that <I>tlmgr</I> considers to be update candidates, along with their current and proposed versions. This mechanism is fundamental to maintaining a secure, stable, and up-to-date TeX Live environment, ensuring access to the latest features, bug fixes, and compatibility improvements for all TeX/LaTeX-related components.


title: CAVEATS
content:
As &#34;tlmgr-candidates&#34; is not a standalone command, its behavior is entirely dependent on the <I>tlmgr</I> utility. It requires an active internet connection to query remote TeX Live repositories for available updates. The specific set of update candidates presented will vary based on the configured TeX Live release (e.g., TL2023, TL2024) and the chosen repository mirror, as different mirrors might synchronize at different times or host different versions. Care should be taken when updating, especially with pre-release or development versions of TeX Live, as updates might introduce instabilities.


title: HOW <I>TLMGR</I> IDENTIFIES CANDIDATES
content:
When <I>tlmgr update</I> is invoked, <I>tlmgr</I> compares the version numbers of locally installed packages against the latest versions listed in the TeX Live repository&#39;s database. If the remote version is newer, the package is flagged as an update candidate. This process also considers dependencies, ensuring that all necessary packages are present or updated for a successful installation.


title: IMPACT OF REPOSITORY SELECTION
content:
The specific TeX Live repository (mirror) configured for <I>tlmgr</I> directly influences the list of update candidates. Different mirrors might be synchronized at varying times, or during a release cycle, they might host different stages of development. Using a consistent and up-to-date mirror is crucial for getting the expected set of candidates and avoiding issues.


title: HISTORY
content:
The concept of managing update candidates has been integral to TeX Live&#39;s package management system since the introduction of <I>tlmgr</I> (TeX Live Manager). <I>tlmgr</I> replaced older, less sophisticated update mechanisms, providing a robust, internet-enabled way to keep TeX Live installations current. The logic for identifying and presenting update candidates has evolved with improvements in repository synchronization protocols, dependency resolution algorithms, and the increasing complexity of the TeX Live distribution itself. This continuous development ensures that users can reliably update their TeX distributions with the latest bug fixes and package versions.


title: SYNOPSIS
content:
<code>tlmgr check</code> [<I>options</I>]<br><code>tlmgr check --check-files</code> [<I>package</I>...]<br><code>tlmgr check --check-depends</code> [<I>package</I>...]<br><code>tlmgr check --check-mirrors</code><br><code>tlmgr check --check-mac-fonts</code><br><code>tlmgr check --check-profiles</code><br><code>tlmgr check --check-all</code>


title: PARAMETERS
content:
<b><b>--check-all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs all available integrity and consistency checks.<br><br><b><b>--check-files</b> [<I>pkg</I>...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Verifies the existence of all files for specified packages (or all installed packages if none are given) according to the TeX Live database.<br><br><b><b>--check-depends</b> [<I>pkg</I>...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Checks for missing dependencies for specified packages (or all installed packages if none are given).<br><br><b><b>--check-mirrors</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Validates the consistency and availability of the configured TeX Live mirrors.<br><br><b><b>--check-mac-fonts</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(macOS only) Checks consistency between TeX Live fonts and system font registrations.<br><br><b><b>--check-profiles</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Checks the consistency of font profiles, such as dvips and pdftex configurations.<br><br><b><b>--dry-run</b> (<code>-n</code>)</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Simulates the check operation without making any actual changes or fixes.<br><br>


title: DESCRIPTION
content:
<code>tlmgr-check</code> is a subcommand of the <I>TeX Live Manager</I> (<code>tlmgr</code>) utility.<br>Its primary purpose is to verify the integrity and consistency of a TeX Live installation. It can perform various checks, such as verifying the existence of files listed in the TeX Live database, checking for missing dependencies, ensuring mirror consistency, and validating font profiles on macOS. This command helps users identify potential issues arising from incomplete installations, corrupted packages, or inconsistencies between the local installation and the TeX Live repository. It's a crucial tool for diagnosing problems and maintaining a healthy TeX Live environment, often used after updates or when troubleshooting unexpected behavior.


title: CAVEATS
content:
Requires a working internet connection for mirror checks or when fetching information from the repository.<br>Can be time-consuming, especially for <b>--check-all</b> on large installations.<br>Fixing issues often requires subsequent <code>tlmgr</code> commands (e.g., <code>update</code>, <code>install</code>, <code>remove</code>). <code>tlmgr-check</code> identifies issues, but doesn't fix them.<br>On macOS, <b>--check-mac-fonts</b> might require administrator privileges or specific system configurations.


title: <B>RETURN STATUS</B>
content:
The command typically returns a non-zero exit status if any issues are found during the checks, and zero if the installation is consistent. This allows for scripting and automated checks.


title: <B>OUTPUT DETAILS</B>
content:
<code>tlmgr check</code> provides detailed output, indicating which checks are being performed and listing any inconsistencies or missing components it identifies. The verbosity level can be adjusted to control the amount of information displayed.


title: HISTORY
content:
The <code>tlmgr</code> utility, including its <code>check</code> subcommand, is an integral part of <I>TeX Live</I>, a comprehensive distribution of the <I>TeX</I> typesetting system. <I>TeX Live's</I> development began in the mid-1990s as a cross-platform replacement for previous distributions. The <code>tlmgr</code> tool was introduced to provide a robust and flexible command-line and GUI interface for managing the TeX Live installation, including package updates, installations, and integrity checks. The <code>check</code> functionality has evolved alongside <I>TeX Live</I>, adapting to new package structures, platform-specific considerations (like macOS font handling), and the increasing complexity of the distribution to ensure stability and reliability for users.


title: SYNOPSIS
content:
<b>tlmgr-conf</b> <i>&lt;key&gt;</i><br><b>tlmgr-conf</b> <i>&lt;key&gt;</i> <i>&lt;value&gt;</i><br><b>tlmgr-conf</b> --help<br><b>tlmgr-conf</b> --version


title: PARAMETERS
content:
<b><i>&lt;key&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the name of the configuration variable to query or modify. Examples include <b>repository</b>, <b>autobackup</b>, <b>backupdir</b>, <b>sys_paper</b>, <b>sys_language</b>, etc. When <i>&lt;key&gt;</i> is provided without <i>&lt;value&gt;</i>, the current setting for that variable is displayed.<br><br><b><i>&lt;value&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The new setting to assign to the specified <i>&lt;key&gt;</i>. If <i>&lt;value&gt;</i> is omitted, the command queries and displays the current setting of <i>&lt;key&gt;</i>. To unset a value, a specific "empty" or "default" value might be required depending on the key.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief help message and exits.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays version information about <b>tlmgr-conf</b> (which usually reflects <b>tlmgr</b>'s version) and exits.<br><br>


title: DESCRIPTION
content:
The <b>tlmgr-conf</b> command serves as a convenient wrapper or symbolic link, primarily used to manage the configuration settings of the TeX Live Manager (<b>tlmgr</b>). While it often invokes the <b>tlmgr config</b> or <b>tlmgr option</b> subcommands internally, its dedicated name emphasizes its role in configuration management. Users employ <b>tlmgr-conf</b> to query, set, or unset various operational parameters for <b>tlmgr</b>, affecting how it interacts with repositories, handles backups, sets default paper sizes, and more. This command provides a streamlined interface for customizing the behavior of your TeX Live installation, from system-wide preferences to user-specific overrides. It is an essential tool for administrators and advanced users who need fine-grained control over their TeX Live environment, ensuring updates and package installations proceed according to specific requirements.


title: CAVEATS
content:
<ul><li><b>tlmgr-conf</b> is often a simple script or alias that directly calls <b>tlmgr</b> with configuration-related arguments. Its exact behavior and available options are therefore heavily dependent on the underlying <b>tlmgr</b> version.</li><li>Modifying system-wide configuration options (e.g., those affecting <b>TEXMFSYSCONFIG</b>) typically requires administrative privileges (e.g., <b>sudo</b>). Incorrect changes can disrupt TeX Live's functionality or update process.</li><li>Be aware of the distinction between system-wide configuration (<b>tlmgr config</b>) and user-specific options (<b>tlmgr option</b>), as <b>tlmgr-conf</b> might default to one or offer ways to specify the scope.</li></ul>


title: CONFIGURATION SCOPES EXPLAINED
content:
When managing TeX Live configuration, it's crucial to understand the two main scopes: system-wide and user-specific.<br><i>System-wide configuration</i>, typically managed by <b>tlmgr config</b> (and thus accessible via <b>tlmgr-conf</b>), usually resides in files like <b>TEXMFSYSCONFIG/tlmgr/config</b> (e.g., <i>/usr/local/texlive/YYYY/tlpkg/texlive.tlmgr-config</i>). These settings apply to all users of the TeX Live installation and often require root privileges to modify.<br><i>User-specific options</i>, handled by <b>tlmgr option</b>, are stored in a user's <b>TEXMFCONFIG</b> directory (e.g., <i>~/.texliveYYYY/tlmgr/config</i>). These settings override system-wide defaults for the individual user, allowing for personalized behavior without affecting other users or requiring elevated privileges. <b>tlmgr-conf</b> usually interacts with the <b>tlmgr config</b> subsystem, but some distributions might configure it to interact with <b>tlmgr option</b> as well.


title: COMMON CONFIGURATION KEYS
content:
While the exact set of configurable keys can vary, some commonly managed options include:<ul><li><b>repository</b>: Specifies the URL of the TeX Live package repository to use for updates and installations.</li><li><b>autobackup</b>: A boolean (0 or 1) indicating whether <b>tlmgr</b> should automatically create backups of packages before updates.</li><li><b>backupdir</b>: Defines the directory where <b>tlmgr</b> stores package backups.</li><li><b>sys_paper</b>: Sets the system-wide default paper size (e.g., <b>a4</b>, <b>letter</b>).</li><li><b>sys_language</b>: Configures the system-wide default language for <b>tlmgr</b> messages.</li></ul>


title: HISTORY
content:
The <b>tlmgr</b> utility itself was introduced around TeX Live 2008, unifying package management tasks that were previously more complex or manual. The <b>tlmgr-conf</b> alias or script emerged as part of the broader effort to streamline <b>tlmgr</b>'s extensive functionality, providing a clear, concise entry point specifically for configuration management, reflecting the growing importance of easily customizable TeX Live installations. Its development is intertwined with the evolution of TeX Live as a robust and user-friendly distribution.


title: SYNOPSIS
content:
<pre>tlmgr-dump-tlpdb</pre><br>This command is primarily an internal script of the TeX Live system and is typically invoked without any direct user-provided arguments. Its behavior is often influenced by environment variables set by the calling <I>tlmgr</I> process.


title: DESCRIPTION
content:
The `tlmgr-dump-tlpdb` command is an internal utility script primarily used by the TeX Live Manager (<I>tlmgr</I>) to generate a comprehensive dump of the TeX Live Package Database (tlpdb). This database contains information about all installed and available TeX Live packages, including their versions, dependencies, and file lists. <br><br>While <I>tlmgr</I> provides user-friendly commands like `tlmgr dump` to access this information, `tlmgr-dump-tlpdb` is the underlying Perl script responsible for parsing the `tlpdb` file and outputting its contents in a machine-readable format to standard output. It is not generally intended for direct invocation by end-users, but rather as a backend component of the TeX Live package management system. Its output is crucial for <I>tlmgr</I> operations such as updates, installations, and consistency checks.


title: CAVEATS
content:
<I>Not for Direct User Use:</I> This command is an internal component of TeX Live and is not designed for direct invocation by end-users. Running it manually might produce raw, complex output that is difficult to interpret without understanding the `tlpdb` format.<br><br><I>Environment Dependency:</I> Its proper functioning heavily relies on the correct TeX Live environment being set up (e.g., via `PATH` and `TEXMFCNF` environment variables).<br><br><I>Output Format:</I> The output is highly structured and machine-readable, intended for parsing by <I>tlmgr</I> or other scripts, not for human readability.


title: USER INTERFACE
content:
For users wishing to inspect the TeX Live package database, the recommended command is `<b>tlmgr dump</b>`. This command offers various options (e.g., `--json`, `--machine-readable`, `--list-options`) to control the output format and content, making it much more user-friendly than directly invoking `tlmgr-dump-tlpdb`. It effectively acts as a wrapper around this internal script.


title: HISTORY
content:
`tlmgr-dump-tlpdb` is an integral part of the TeX Live distribution's package management system. As TeX Live evolved its robust <I>tlmgr</I> (TeX Live Manager) tool for managing installations, updates, and package information, specialized internal scripts like `tlmgr-dump-tlpdb` were developed to handle specific backend tasks, such as parsing and dumping the crucial `tlpdb` (TeX Live Package Database). Its development runs in parallel with the ongoing evolution of <I>tlmgr</I> itself, aiming to provide a reliable and efficient mechanism for querying package data programmatically.


title: SYNOPSIS
content:
<b>tlmgr generate</b> [<i>OPTION</i>...] { <b>ls-R</b> | <b>fmtutil</b> | <b>language</b> | <b>all</b> }


title: PARAMETERS
content:
<b>ls-R</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates the main <i>ls-R</i> file, a database of all files in the TeX Live installation for quick lookup. This is equivalent to running <b>mktexlsr</b>.<br><br><b>fmtutil</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates the <i>fmtutil.cnf</i> configuration file, which defines how TeX formats are built. This is then used by <b>fmtutil</b>.<br><br><b>language</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates the <i>language.dat</i>, <i>language.dat.lua</i>, and <i>language.def</i> files, which are essential for hyphenation patterns and language definitions used by packages like Babel.<br><br><b>all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates all the above-mentioned files (<i>ls-R</i>, <i>fmtutil.cnf</i>, and language files).<br><br><b>--local</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Operates only on the local TeX Live installation tree, ignoring system-wide or network installations.<br><br><b>--rebuild-fmt</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Applicable with 'fmtutil' or 'all')</i> After generating <i>fmtutil.cnf</i>, it also triggers the actual rebuilding of all TeX formats based on the new configuration.<br><br><b>--dest <dir></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Applicable with 'ls-R')</i> Specifies an alternative directory where the <i>ls-R</i> file should be written, instead of the default TeX Live root.<br><br><b>--only-installed</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Applicable with 'language')</i> When generating language files, only include languages corresponding to currently installed packages, omitting those not in use.<br><br><b>--quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses most output messages, showing only critical errors.<br><br><b>--debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose debug output, useful for troubleshooting.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a short help message and exits.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the <b>tlmgr</b> version information and exits.<br><br>


title: DESCRIPTION
content:
The <b>tlmgr generate</b> command is a crucial utility within the TeX Live distribution, responsible for regenerating various essential configuration and database files. These files ensure the correct functioning of your TeX Live installation, especially after updates, new package installations, or custom modifications. It unifies the process of creating files like <i>ls-R</i>, <i>fmtutil.cnf</i>, and the <i>language.dat</i>, <i>language.dat.lua</i>, and <i>language.def</i> files.<br><br>The <i>ls-R</i> file is a comprehensive database of all files within the TeX Live tree, enabling efficient file lookup by TeX programs. The <i>fmtutil.cnf</i> file defines how various TeX formats (e.g., LaTeX, Plain TeX) are built and managed. The <i>language.*</i> files are vital for hyphenation and language-specific settings, primarily used by packages like Babel and Polyglossia.<br><br>While <b>tlmgr generate</b> is often automatically invoked by other <b>tlmgr</b> commands (such as <b>tlmgr update</b> or <b>tlmgr install</b>), it can be run manually to address specific configuration issues, force a rebuild of these files, or after making manual changes to the TeX Live tree. Its primary purpose is to maintain consistency and ensure that all components of the TeX system can locate necessary files and use correct configurations.


title: CAVEATS
content:
Running <b>tlmgr generate</b> manually is generally not required for typical usage, as its functions are automatically invoked by other <b>tlmgr</b> commands like <b>update</b> and <b>install</b>.<br><br>For system-wide TeX Live installations, executing this command often requires administrative privileges (e.g., using <b>sudo</b>) to ensure the generated files can be written to their proper locations.<br><br>The generation process, especially for <i>ls-R</i> on large installations or rebuilding all formats, can be time-consuming and resource-intensive.


title: PURPOSE OF GENERATED FILES
content:
<ul><li><i>ls-R</i>: A flat-file database containing the path and modification time of every file in the TeX Live tree. TeX engines and utilities use this for fast file lookup, avoiding slow recursive directory scans.</li><li><i>fmtutil.cnf</i>: The configuration file for <b>fmtutil</b>, which lists all available TeX formats (like LaTeX, ConTeXt, Plain TeX) and specifies the source files and options needed to build their corresponding format files (<i>.fmt</i>).</li><li><i>language.dat</i>, <i>language.dat.lua</i>, <i>language.def</i>: These files provide a mapping from language names to hyphenation patterns and other language-specific definitions. They are crucial for packages like Babel and Polyglossia to correctly typeset documents in various languages by enabling proper hyphenation and locale-specific features.</li></ul>


title: HISTORY
content:
The <b>tlmgr</b> utility, which encompasses <b>tlmgr generate</b>, was introduced as the primary management tool for TeX Live distributions from version 2008 onwards. It aimed to consolidate and streamline various maintenance tasks previously handled by separate scripts or manual interventions, such as managing packages, updating the distribution, and regenerating critical configuration files. The <b>generate</b> subcommand specifically unified the regeneration of the TeX file database (<i>ls-R</i>) and format/language configuration files, making TeX Live maintenance more robust and user-friendly.


title: PARAMETERS
content:
<b><B>--help</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief help message and exits, detailing available options for launching the GUI.<br><br><b><B>--version</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays version information for the <B>tlmgr-gui</B> application and exits.<br><br>


title: DESCRIPTION
content:
The <B>tlmgr-gui</B> command launches the graphical user interface for <B>tlmgr</B>, the TeX Live Manager. It provides a user-friendly front-end for managing your TeX Live installation, allowing users to perform various administrative tasks without relying on the command line. <br><br>Through this GUI, users can easily:<br> <I>install</I> new TeX packages,<br> <I>update</I> existing ones,<br> <I>remove</I> unwanted packages,<br> <I>manage</I> TeX Live repositories,<br> and <I>configure</I> global TeX Live settings. <br><br>It simplifies the maintenance and customization of a TeX Live environment, making it accessible to a wider range of users, especially those less familiar with command-line operations.


title: CAVEATS
content:
The <B>tlmgr-gui</B> command requires a graphical environment (such as X Window System or Wayland) to function properly. It cannot be used on headless servers or in environments without display capabilities. Operations performed through the GUI, such as installing or updating system-wide TeX Live packages, may require appropriate user permissions (e.g., root privileges via <B>sudo</B>).


title: KEY FEATURES AND INTERACTION
content:
Upon launching, <B>tlmgr-gui</B> typically presents a main window with various tabs or sections dedicated to different management tasks, such as 'Packages', 'Configuration', 'Repositories', and 'Paper Size'. Users can easily browse through lists of installed and available packages, search for specific ones, view detailed information, and initiate installation or update processes with simple clicks. The interface provides visual feedback on ongoing operations and helps manage package dependencies automatically, streamlining the TeX Live maintenance workflow.


title: HISTORY
content:
<B>tlmgr-gui</B> was developed as an integral part of the TeX Live distribution to complement the powerful but command-line-centric <B>tlmgr</B> tool. Its introduction aimed to provide a more intuitive and accessible way for users to manage their TeX Live installations, especially for those who prefer visual interfaces. It has evolved with TeX Live over the years, continually improving its usability, stability, and feature set to simplify package and configuration management for TeX users worldwide.


title: PARAMETERS
content:
<b><i>package</i>|<i>scheme</i>|<i>collection</i>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies one or more names of TeX Live packages, schemes, or collections for which to display detailed information. If no names are provided, <b>tlmgr info</b> outputs general information about the TeX Live installation.<br><br><b>--list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all currently installed TeX Live packages, one per line. This option cannot be combined with specific package names and provides a simple list rather than detailed information.<br><br><b>--only-installed</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When displaying information for specified packages, this option restricts the output to only those packages that are currently installed on your system. It is useful for filtering results when a package might exist both locally and remotely.<br><br><b>--only-remote</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When displaying information for specified packages, this option restricts the output to only those packages that are available in the configured remote repositories but are <i>not</i> currently installed on your system. Useful for discovering available packages.<br><br><b>--data</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the information in a simple, machine-readable format, typically as <code>key=value</code> pairs. This format is useful for scripting and programmatic access to TeX Live data, although <code>--json</code> is generally preferred for new developments.<br><br><b>--json</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the information in JSON (JavaScript Object Notation) format. This is the recommended machine-readable output format, providing a structured and easily parseable representation of the TeX Live information.<br><br><b>--config</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays detailed configuration information about the current TeX Live installation, including paths, repository URL, and other environment-specific settings. This acts as a specific type of query for installation-wide settings rather than package-specific details.<br><br>


title: DESCRIPTION
content:
The <b>tlmgr-info</b> command, part of the TeX Live Manager (<code>tlmgr</code>) suite, is used to display comprehensive information about TeX Live packages, schemes, collections, or the entire TeX Live installation. When invoked without specific arguments, it provides an overview of your TeX Live setup, including the version, installation path, and configured repositories. When used with one or more package, scheme, or collection names, it furnishes detailed data for those specific items, such as their version, dependencies, installation status (installed or remote-only), size, and description.<br><br>It's an invaluable tool for users to verify installations, troubleshoot issues, check package versions, and understand the contents of their TeX Live environment. The command supports various options to filter the displayed information and control the output format, making it suitable for both human readability and machine processing.


title: CAVEATS
content:
The accuracy and completeness of the information displayed by <b>tlmgr-info</b> depend on the integrity of your local TeX Live installation database and the accessibility of the configured remote TeX Live repositories. Network issues can affect information retrieval for remote packages. Using <code>--data</code> or <code>--json</code> will drastically change the output format, making it unsuitable for direct human reading unless parsed by a dedicated tool.


title: DEFAULT BEHAVIOR
content:
When <b>tlmgr info</b> is executed without any package names or specific filtering options (like <code>--list</code> or <code>--config</code>), it provides a high-level summary of the current TeX Live installation. This includes the TeX Live version, the installation directory, the primary repository being used, and other general configuration details.


title: INFORMATION PROVIDED FOR PACKAGES
content:
For individual packages, <b>tlmgr info</b> typically provides comprehensive details such as: the <i>package name</i>, <i>version</i>, <i>tag</i> (e.g., 'installed', 'remote'), a <i>short description</i>, a more extensive <i>long description</i>, a list of <i>dependencies</i>, its <i>installation status</i> (whether it's installed locally or only available remotely), its <i>size</i>, and the <i>repository</i> it originates from. The exact fields may vary slightly depending on the package type and the chosen output format (e.g., default, <code>--data</code>, or <code>--json</code>).


title: HISTORY
content:
The <b>tlmgr</b> utility, which includes the <b>info</b> subcommand, was introduced as the successor to older TeX Live management tools like <code>install-tl</code>'s command-line interface. Its development aimed to provide a unified, robust, and extensible system for managing TeX Live installations. The <b>info</b> subcommand has been a core part of <b>tlmgr</b> since its inception, serving as a fundamental diagnostic and informational tool for TeX Live users and administrators.


title: PARAMETERS
content:
<b><i>package</i>|<I>collection</I>|<I>scheme</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more package names, collection names, or scheme names to be installed.<br><br><b><b>--reinstall</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces reinstallation of packages that are already installed.<br><br><b><b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Proceeds with the installation even if it means overwriting existing files or bypassing warnings.<br><br><b><b>--repository</b> <i>url</i>|<i>path</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative repository URL or local path from which to install packages.<br><br><b><b>--dry-run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Simulates the installation process and displays what would be done without making any actual changes.<br><br><b><b>--no-depends</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents the automatic installation of dependencies required by the specified packages.<br><br><b><b>--local</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Installs a local `.tlmgr` or `.tar.xz` package file instead of fetching from a remote repository.<br><br><b><b>--user</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Installs packages into the user's personal TeX tree instead of the system-wide tree (does not require root privileges).<br><br>


title: DESCRIPTION
content:
<b>tlmgr-install</b> is a vital subcommand of the TeX Live Manager (<code>tlmgr</code>) dedicated to installing packages, collections, or schemes into a TeX Live distribution.<br><br>It functions by connecting to the configured TeX Live repository, typically an online mirror or a local source, and then downloads and integrates the specified components into the local TeX Live tree. This command is essential for enhancing an existing TeX Live installation with new features, fonts, styles, or tools that may not have been part of the initial setup.<br><br>By default, <b>tlmgr-install</b> automatically resolves and installs any required dependencies for the specified items. Users can specify individual package names, or opt for higher-level structures like <i>collections</i> (pre-defined groups of related packages) or <i>schemes</i> (comprehensive sets of collections that represent a complete TeX Live profile). The command offers various options to customize the installation process, including forcing reinstallation, performing dry runs to preview changes, or specifying an alternative repository location. Correct usage ensures a robust and well-maintained TeX Live environment.


title: CAVEATS
content:
For system-wide installations, <b>tlmgr-install</b> often requires root or administrator privileges.<br>Network connectivity is necessary when installing from online repositories.<br>Using the <b>--force</b> option should be done with caution, as it can overwrite custom files or lead to unexpected behavior.<br>For updating already installed packages, <b>tlmgr update</b> is generally the preferred command over <b>tlmgr install</b>.


title: COLLECTIONS AND SCHEMES
content:
Beyond individual packages, <b>tlmgr-install</b> can install <i>collections</i> (logical groups of packages, e.g., <code>collection-fontsrecommended</code>) and <i>schemes</i> (pre-defined, comprehensive sets of collections, e.g., <code>scheme-full</code> or <code>scheme-basic</code>). This significantly simplifies the management of large sets of related packages.


title: SYSTEM VS. USER INSTALLATION
content:
By default, <b>tlmgr-install</b> attempts a system-wide installation. However, the <b>--user</b> option allows users to install packages into their home directory's personal TeX tree. This is particularly useful for users without root privileges or for those wishing to test packages without affecting the global system installation.


title: HISTORY
content:
The TeX Live Manager (<code>tlmgr</code>) replaced older package management tools like <code>teXconfig</code> and <code>tla</code> as the standard utility for managing TeX Live distributions. The <b>install</b> subcommand has been a fundamental part of <code>tlmgr</code> since its inception, providing a centralized and robust mechanism for adding components to a TeX Live installation. Its development has mirrored the evolution of TeX Live itself, aiming for greater ease of use and reliability in maintaining complex TeX environments.


title: SYNOPSIS
content:
<b>tlmgr key</b> [<i>options</i>] [<i>command</i>] [<i>arguments</i>]<br><br>Common commands:<br><b>tlmgr key list</b><br><b>tlmgr key add</b> <i>keyid</i><br><b>tlmgr key remove</b> <i>keyid</i><br><b>tlmgr key import</b> <i>filename</i><br><b>tlmgr key export</b> <i>keyid</i><br><b>tlmgr key fingerprint</b> <i>keyid</i>


title: PARAMETERS
content:
<b>list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Lists</I> all GPG keys currently trusted by <I>tlmgr</I> for repository verification.<br><br><b>add <keyid></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Adds</I> a specific GPG key to the trusted keyring using its 8- or 16-character key ID. The key is typically fetched from a public key server.<br><br><b>remove <keyid></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Removes</I> a GPG key from the trusted keyring using its key ID.<br><br><b>import <filename></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Imports</I> one or more GPG keys from a specified file. This is useful for adding keys that are not available on public key servers or provided directly by a mirror.<br><br><b>export <keyid></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Exports</I> a specific GPG key from the trusted keyring to standard output or a file.<br><br><b>fingerprint <keyid></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Displays</I> the fingerprint of a given key ID, helping to verify the key's authenticity.<br><br>


title: DESCRIPTION
content:
<I>tlmgr-key</I> is a subcommand of <I>tlmgr</I>, the TeX Live package manager, specifically designed for managing GPG (GNU Privacy Guard) keys. These keys are crucial for verifying the authenticity and integrity of TeX Live repositories and packages during updates and installations. By using cryptographic signatures, <I>tlmgr-key</I> helps ensure that the packages you download have not been tampered with and originate from trusted sources.<br><br>It allows users to list currently trusted keys, add new keys, remove existing ones, and import/export keys, primarily for situations where new mirrors or repository signing keys are introduced. Proper key management is essential for maintaining the security and reliability of your TeX Live installation.


title: CAVEATS
content:
<I>tlmgr-key</I> directly manipulates the GPG keyring used by TeX Live. Incorrectly adding or removing keys can lead to security vulnerabilities if untrusted keys are added, or prevent updates if necessary keys are removed.<br><br>Always verify the authenticity of new keys through official TeX Live channels before adding them. Network connectivity is often required for adding keys via public key servers.


title: IMPORTANCE OF KEY VERIFICATION
content:
GPG key verification is a critical security measure. It ensures that the TeX Live packages you download and install are genuinely from the TeX Live project and have not been altered maliciously during transit. Always prioritize using verified keys to safeguard your system.


title: KEY SERVERS
content:
When using `tlmgr key add`, the command typically attempts to fetch the key from a public key server. If you are behind a firewall or have specific network configurations, you might need to adjust your environment or import keys manually from a file.


title: HISTORY
content:
The <I>tlmgr-key</I> functionality was introduced into TeX Live as part of ongoing efforts to enhance the security of package management. Prior to its implementation, verifying the integrity of TeX Live packages relied less on cryptographic signatures, making the update process potentially more vulnerable to tampering. Its inclusion reflects a broader trend in software distribution towards robust digital signature verification to ensure trusted sources and prevent supply chain attacks.


title: SYNOPSIS
content:
<b>tlmgr option</b> [<i>OPTION</i>]... [<i>NAME</i> [<i>VALUE</i>]]<br><b>tlmgr option</b> [<i>OPTION</i>]... <b>--list</b><br><b>tlmgr option</b> [<i>OPTION</i>]... <b>--json</b><br><i>Note:</i> <b>tlmgr</b> is the main command, and <b>option</b> is its subcommand.


title: PARAMETERS
content:
<b>NAME</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the configuration option to query or set.<br><br><b>VALUE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The new value to set for the specified option <b>NAME</b>. If <b>VALUE</b> is omitted when <b>NAME</b> is provided, the current value of <b>NAME</b> is displayed.<br><br><b>--list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a list of all available configuration options along with their current values and a brief description.<br><br><b>--json</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the list of options and their values in JSON format, useful for scripting.<br><br><b>--show-help, -h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message with usage information for the <b>option</b> subcommand.<br><br><b>--config-path</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative path to the configuration file (advanced usage).<br><br><b>--dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows what would be done without actually making any changes.<br><br><b>--force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the operation, overriding some checks. (Use with caution).<br><br><b>--logfile FILE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a file to write log messages to.<br><br><b>--repository URL</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the repository to use for this operation. This overrides the default or currently configured repository.<br><br><b>--debug LEVEL</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the debugging level for more verbose output.<br><br><b>--arc-style STYLE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the style for archive backups, e.g., 'none', 'tlpdb', 'user'.<br><br>


title: DESCRIPTION
content:
<i>tlmgr option</i> is a powerful subcommand of the TeX Live Manager (<i>tlmgr</i>) used to inspect, set, or delete persistent configuration options for your TeX Live installation. These options control various aspects of how <i>tlmgr</i> operates, including the default package repository, whether to create backups during updates, the directory for backups, and other system-wide or user-specific settings. It allows users to customize TeX Live's behavior without editing configuration files directly, ensuring proper interaction with the <i>tlmgr</i> system. Options set via <i>tlmgr option</i> are stored persistently and affect all subsequent <i>tlmgr</i> commands. Understanding and utilizing these options is crucial for effective management and customization of a TeX Live environment.


title: CAVEATS
content:
<b>Persistent Changes:</b> Options set using <i>tlmgr option</i> are persistent and will affect all future <i>tlmgr</i> operations. Be cautious when changing critical options like <i>repository</i> paths.<br><b>Permissions:</b> For system-wide TeX Live installations, modifying options often requires administrative privileges (e.g., <b>sudo</b>). If you lack the necessary permissions, the command will fail.<br><b>Validation:</b> <i>tlmgr</i> generally performs some validation on option values, but providing invalid or nonsensical values can lead to unexpected behavior or breakage of your TeX Live installation.<br><b>Interference:</b> Be aware that certain options might interact with environment variables or other configuration files, potentially leading to conflicts if not managed carefully.<br><b>Command Misnomer:</b> The user specified 'tlmgr-option' which is not a standalone command. This analysis addresses the subcommand usage of <b>tlmgr option</b>.


title: COMMONLY CONFIGURED OPTIONS
content:
<i>repository:</i> Sets the URL of the primary TeX Live package repository. This is crucial for updates and installations.<br><i>autobackup:</i> Enables or disables automatic backups of packages before updates. Highly recommended for safety.<br><i>backupdir:</i> Specifies the directory where backup packages are stored.<br><i>paper:</i> Sets the default paper size (e.g., <b>a4</b>, <b>letter</b>) for dvips, dvipdfm, and other tools.<br><i>scheme:</i> Controls the installed TeX Live scheme (e.g., <b>full</b>, <b>basic</b>). (Though changing scheme is typically done during initial install or via <b>tlmgr install/remove</b>).


title: USER VS. SYSTEM CONFIGURATION
content:
By default, <i>tlmgr option</i> changes apply to the TeX Live installation as a whole (system-wide). However, <i>tlmgr</i> also supports user-specific configuration files, allowing individual users to override system settings without requiring root privileges. This typically involves setting <b>TLMGR_OPTIONS</b> environment variable or using <b>tlmgr --usermode</b>.


title: HISTORY
content:
The <b>tlmgr</b> (TeX Live Manager) tool was introduced in TeX Live 2008, replacing earlier, less integrated update mechanisms like <i>teTeX</i>'s <i>tla</i> and <i>updmap</i>. The <b>option</b> subcommand has been a fundamental part of <b>tlmgr</b> since its inception, providing a standardized and robust way to manage TeX Live's internal configuration without manual file editing. Its development reflects the ongoing effort to make TeX Live more user-friendly and maintainable, centralizing configuration management within the <b>tlmgr</b> framework.


title: SYNOPSIS
content:
tlmgr paper [options] <command> [size]<br><br><b>Commands:</b><br> tlmgr paper <b>list</b><br> tlmgr paper <b>get</b><br> tlmgr paper <b>set</b> <I>size</I>


title: PARAMETERS
content:
<b>list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all recognized paper sizes available for use.<br><br><b>get</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the currently configured default paper size.<br><br><b>set <size></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the default paper size to <I>size</I> (e.g., <I>a4</I>, <I>letter</I>). This updates configuration files for relevant TeX tools.<br><br><b>--force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the action, for example, to override warnings or non-standard configurations. Use with caution.<br><br><b>--all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When used with the <b>set</b> command, applies the paper size setting to all relevant configuration files and programs, ensuring comprehensive application.<br><br><b>--config-only</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Updates only the configuration files without attempting to apply changes to programs or regenerate format files. Useful for specific setup scenarios.<br><br>


title: DESCRIPTION
content:
The <b>tlmgr-paper</b> command is a subcommand of TeX Live's package manager, <b>tlmgr</b>. It provides a convenient way to manage the default paper size used by various TeX utilities such as dvips, pdfTeX, XeTeX, and LuaTeX. Instead of manually editing configuration files, <b>tlmgr-paper</b> allows users to list available paper sizes, retrieve the currently set default, or set a new global default. This ensures consistency across different TeX output drivers and tools. It primarily modifies system-wide configuration files to reflect the chosen paper size.


title: CAVEATS
content:
Changes made by <b>tlmgr-paper</b> are typically system-wide. For changes to take full effect, dependent programs might need to be re-run, or in some cases, formats might need to be rebuilt, although <b>tlmgr</b> usually handles the necessary rebuilds. Users might need administrative privileges (e.g., `sudo`) to modify system-wide settings.


title: CONFIGURATION FILES
content:
<b>tlmgr-paper</b> primarily modifies configuration files like <I>texmf.cnf</I> and settings for programs such as <I>dvips</I>, <I>pdftex</I>, <I>xetex</I>, <I>luatex</I>, and <I>xdvi</I>, ensuring they adhere to the chosen paper size default.


title: HISTORY
content:
<b>tlmgr</b> was introduced to simplify the management of TeX Live installations, replacing older, less integrated tools. The <b>paper</b> subcommand was included to centralize the historically fragmented process of setting default paper sizes across various TeX components, ensuring a more consistent user experience within the TeX Live ecosystem.


title: SYNOPSIS
content:
<br><b><code>tlmgr-path &lt;action&gt; [options]</code></b><br><br><i>Actions:</i> <code>show</code> | <code>add</code> | <code>remove</code> | <code>set</code>


title: PARAMETERS
content:
<b>show</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the current TeX Live related paths that are or should be in <b><code>PATH</code></b> and <b><code>MANPATH</code></b>. If sourced, it prints commands to be executed for adding/removing.<br><br><b>add</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds the TeX Live binary and man directories to the current <b><code>PATH</code></b> and <b><code>MANPATH</code></b> environment variables. This action is usually sourced to affect the current shell.<br><br><b>remove</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes TeX Live binary and man directories from <b><code>PATH</code></b> and <b><code>MANPATH</code></b>. Similar to 'add', this action is typically sourced.<br><br><b>set</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Resets <b><code>PATH</code></b> and <b><code>MANPATH</code></b> to include only the TeX Live directories and standard system paths, effectively removing other custom entries. <i>Use with caution</i> as it can clear other important paths.<br><br><b>--all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Used with <b><code>show</code></b>) Displays path information for all detected TeX Live installations on the system, rather than just the active one.<br><br><b>--dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a simulated run, showing what changes would be made to the environment variables without actually applying them. Useful for previewing changes.<br><br><b>--windows</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Handles path manipulation specific to Windows environments, often involving system-wide path modifications via the registry.<br><br><b>--dont-execute</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs the script not to execute any commands, typically used for internal debugging or specific programmatic interactions. Similar to <b><code>--dry-run</code></b>.<br><br>


title: DESCRIPTION
content:
<b><code>tlmgr-path</code></b> is a crucial helper script for TeX Live, designed to manage the <b><code>PATH</code></b> and <b><code>MANPATH</code></b> environment variables. It ensures that the executables and manual pages distributed with TeX Live are correctly accessible from your command line. While often invoked indirectly via the <b><code>tlmgr path</code></b> subcommand, <b><code>tlmgr-path</code></b> can also be used directly. Its primary function is to report, add, remove, or set the necessary directories in your shell's environment variables, making utilities like <b><code>pdflatex</code></b>, <b><code>xelatex</code></b>, <b><code>bibtex</code></b>, and their respective manual pages discoverable by the system. Proper configuration of these paths is essential for a functional TeX Live setup, allowing users to run TeX-related commands without specifying full paths.


title: CAVEATS
content:
It is critical to understand the difference between <i>executing</i> <b><code>tlmgr-path</code></b> and <i>sourcing</i> it. When executed directly (e.g., <b><code>tlmgr-path add</code></b>), the script performs actions only within its own subshell, and the changes do not persist in the parent shell's environment. To permanently modify the current shell's <b><code>PATH</code></b> and <b><code>MANPATH</code></b>, <b><code>tlmgr-path</code></b> <i>must be sourced</i> (e.g., <b><code>source tlmgr-path add</code></b> or <b><code>. tlmgr-path add</code></b>). Using the <b><code>set</code></b> action can be destructive if you rely on other custom paths, as it will clear all non-TeX Live and non-system paths. Incorrect usage can lead to your TeX Live binaries becoming inaccessible.


title: SOURCING THE SCRIPT
content:
To make <b><code>tlmgr-path</code></b>'s changes effective in your current shell session, you must <i>source</i> the script. This means running it with the <b><code>source</code></b> command or its shorthand <b><code>.</code></b> (dot) command, like <b><code>source /path/to/tlmgr-path add</code></b> or <b><code>. /path/to/tlmgr-path add</code></b>. This executes the script within the current shell, allowing it to modify the <b><code>PATH</code></b> and <b><code>MANPATH</code></b> environment variables of that shell. Without sourcing, any path modifications made by <b><code>tlmgr-path</code></b> will only apply to the subshell in which it was executed and will disappear immediately after the script finishes.


title: HISTORY
content:
<b><code>tlmgr-path</code></b> is an integral component of the TeX Live distribution, developed alongside the TeX Live Manager (<b><code>tlmgr</code></b>) to standardize and simplify the management of executable and manual page paths for TeX Live installations across various Unix-like systems and Windows. Its functionality ensures that users can easily integrate TeX Live into their existing shell environments without manual path configuration, evolving as TeX Live itself has grown and added features over its development history.


title: PARAMETERS
content:
<b>None</b><br>&nbsp;&nbsp;&nbsp;&nbsp;This command does not accept specific parameters of its own. It operates by scanning the existing TeX Live installation.<br><br>


title: DESCRIPTION
content:
The <b>tlmgr-recreate-tlpdb</b> command is a crucial utility within the TeX Live distribution, designed to rebuild or refresh its internal package database, known as the TeX Live Package Database (<i>tlpdb</i>). This database is essential for <b>tlmgr</b> (TeX Live Manager) to keep track of all installed packages, their versions, and their corresponding files.<br><br>When the <i>tlpdb</i> becomes corrupted, inconsistent, or out of sync with the actual files on the system due to manual file manipulations, incomplete updates, or system issues, <b>tlmgr</b> operations can fail or report incorrect information. Running <b>tlmgr-recreate-tlpdb</b> forces a rescan of the entire TeX Live installation tree. It identifies all installed packages and their components, then reconstructs a pristine <i>tlpdb</i> file based on this fresh scan. This process ensures that <b>tlmgr</b> regains an accurate and reliable understanding of the TeX Live environment, allowing subsequent package installations, removals, or updates to proceed correctly.


title: CAVEATS
content:
<b>Administrative Privileges:</b> Rebuilding the TeX Live database typically requires administrative or root privileges (e.g., using <b>sudo</b>) to access and modify the TeX Live installation directory.<br><br><b>Time-Consuming:</b> For large TeX Live installations, the database recreation process can take a significant amount of time as it involves scanning numerous files and directories.<br><br><b>Troubleshooting Tool:</b> While effective for database inconsistencies, it does not resolve underlying file system corruption or package conflicts not related to the <i>tlpdb</i> itself. It's a tool to fix the <i>database view</i> of your installation.<br><br><b>Not for Regular Use:</b> This command should only be used when <b>tlmgr</b> operations are failing due to suspected database corruption or inconsistencies, not as a routine maintenance task.


title: WHAT IT DOES
content:
The command works by traversing the entire TeX Live installation, typically located under <i>/usr/local/texlive/YYYY</i> or a similar path. It identifies all installed packages, their files, and their metadata by examining the actual contents on disk, rather than relying on the potentially corrupt existing <i>tlpdb</i>. It then compiles this information into a new, consistent <i>tlpdb</i> file, which is usually stored in the <i>texmf-dist/tlpkg</i> directory within your TeX Live installation. This new database replaces the old one, providing <b>tlmgr</b> with an accurate map of your installed TeX Live components.


title: WHEN TO USE IT
content:
You should consider using <b>tlmgr-recreate-tlpdb</b> in the following scenarios:<br>- When <b>tlmgr</b> reports errors indicating database corruption (e.g., '<i>tlpdb</i> parse error', 'unknown package').<br>- After manually moving, deleting, or altering files within your TeX Live installation without using <b>tlmgr</b>, which can lead to inconsistencies.<br>- If the list of installed packages displayed by <b>tlmgr info --list</b> or similar commands appears incorrect or incomplete.<br>- Following a system crash or power failure during a <b>tlmgr</b> operation that might have left the database in an inconsistent state.<br>- As a last resort for inexplicable <b>tlmgr</b> issues before resorting to a full reinstallation of TeX Live.


title: HISTORY
content:
<b>tlmgr-recreate-tlpdb</b> is an integral part of the TeX Live utility suite, which was introduced to standardize and modernize package management for TeX Live distributions. As <b>tlmgr</b> became the primary tool for managing TeX Live installations, the need for a mechanism to repair or regenerate its central database (<i>tlpdb</i>) became apparent. This command (or its equivalent as a <b>tlmgr</b> subcommand) was developed to ensure the robustness and maintainability of TeX Live installations against various forms of database corruption or inconsistencies that can arise over time.


title: PARAMETERS
content:
<b><i>package_name</i>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more names of the TeX Live package(s), collection(s), or scheme(s) to be uninstalled.<br><br><b><b>--dry-run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Simulate the removal process without making any actual changes. This option shows which packages would be uninstalled.<br><br><b><b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the removal, even if other installed packages depend on the specified ones. This can severely break your TeX Live installation and should be used with extreme caution.<br><br><b><b>--no-depends</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skip the checking and resolution of package dependencies during the removal process. Using this option is highly discouraged as it can lead to a broken or incomplete installation.<br><br>


title: DESCRIPTION
content:
<i>tlmgr-remove</i> is a subcommand of <i>tlmgr</i>, the TeX Live package manager, used to uninstall installed TeX Live packages, collections, or schemes.<br><br>It provides a convenient way to manage the disk space consumed by TeX Live installations by removing unwanted or redundant components. When a package is removed, <i>tlmgr</i> typically handles the necessary cleanup and updates the TeX Live database. It's crucial to use this command with caution, especially when removing core components, as it can affect the functionality of your TeX Live distribution. For system-wide installations, administrator privileges (e.g., <b>sudo</b>) are usually required.


title: CAVEATS
content:
<b>Caveats and Limitations:</b><br>1. For system-wide TeX Live installations, <i>tlmgr-remove</i> typically requires administrator privileges (e.g., using <b>sudo</b>).<br>2. Using the <b>--force</b> or <b>--no-depends</b> options can easily corrupt your TeX Live installation by removing essential dependencies or critical packages.<br>3. Always ensure you know what you are removing, as uninstalling core components can render your TeX Live distribution unusable.


title: DEPENDENCY MANAGEMENT
content:
By default, <i>tlmgr-remove</i> intelligently handles package dependencies, preventing the removal of packages that are required by other installed components. This behavior ensures the integrity of your TeX Live installation, unless explicitly overridden by options like <b>--force</b> or <b>--no-depends</b>.


title: PERMISSIONS
content:
When TeX Live is installed system-wide (e.g., in a directory like <i>/usr/local/texlive</i>), performing removal operations with <i>tlmgr-remove</i> will require root privileges. This is typically achieved by prefixing the command with <b>sudo</b>. For user-specific TeX Live installations, root permissions are usually not necessary.


title: HISTORY
content:
<i>tlmgr</i> was developed to be the primary management tool for TeX Live, replacing older, less integrated utilities. The <i>remove</i> functionality has been a fundamental part of <i>tlmgr</i> since its inception, evolving to handle the complex structure of TeX Live distributions, including collections and schemes, providing a robust way to manage installed components.


title: SYNOPSIS
content:
<b>tlmgr</b> [<I>options</I>] <I>command</I> [<I>args</I>]<br>Specifically, repository-related options often used with commands like <i>update</i>, <i>install</i>, <i>option</i>:<br><b>tlmgr</b> <b>--repository</b> <I>URL</I>|<I>PATH</I> <I>command</I> [<I>args</I>]<br><b>tlmgr</b> <b>--location</b> <I>URL</I>|<I>PATH</I> <I>command</I> [<I>args</I>]<br><b>tlmgr</b> <b>option repository</b> [<I>URL</I>|<I>PATH</I>]


title: PARAMETERS
content:
<b>--repository <I>URL</I>|<I>PATH</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the TeX Live repository to use for the current command execution. Can be a URL (e.g., <I>http://mirror.ctan.org/systems/texlive/tlnet</I>) or a local path to a TeX Live installation (e.g., <I>/path/to/my/texlive/install</I>).<br><br><b>--location <I>URL</I>|<I>PATH</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An alias for the <b>--repository</b> option, serving the same purpose of specifying the package source.<br><br><b>option repository [<I>URL</I>|<I>PATH</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When used with <b>tlmgr option</b>, this command allows you to query the currently configured default repository or set a new persistent default repository. If <I>URL</I>|<I>PATH</I> is omitted, it displays the current setting. This setting persists across <b>tlmgr</b> invocations unless overridden by <b>--repository</b> or <b>--location</b>.<br><br>


title: DESCRIPTION
content:
<i>tlmgr-repository</i> is not a direct command, but rather a conceptual topic within the <b>tlmgr</b> (TeX Live Manager) utility, which is used to administer a TeX Live installation. It refers to the mechanism by which <b>tlmgr</b> locates, accesses, and manages the repositories from which TeX Live packages are downloaded and updated. TeX Live installations can be configured to use specific network repositories (mirrors) or local repositories (e.g., from an ISO image or a local directory). Understanding <i>tlmgr-repository</i> is crucial for users who need to switch update sources, install packages from non-standard locations, or manage offline TeX Live installations. <b>tlmgr</b> offers various options to specify or change the repository location, such as <b>--repository</b> or <b>--location</b>, allowing users to control where their TeX Live packages originate. This ensures flexibility for different network environments and update strategies. Furthermore, <b>tlmgr</b> maintains a persistent default repository setting, which can be overridden for individual commands, providing fine-grained control over package sources.


title: CAVEATS
content:
<i>tlmgr-repository</i> itself is not an executable command; it describes the mechanism and options within <b>tlmgr</b> for managing package sources.<br>When specifying a network URL, ensure proper internet connectivity and no firewall/proxy issues are blocking access to the repository.<br>Local repositories, often used for offline installations, must be manually created and kept synchronized with official CTAN mirrors if updates are desired.<br>Using the <b>--repository</b> or <b>--location</b> options on the command line overrides any persistently configured default repository for that specific <b>tlmgr</b> command execution.


title: DEFAULT REPOSITORY SELECTION
content:
By default, <b>tlmgr</b> attempts to find a suitable network repository by checking a predefined list of CTAN mirrors or a configured URL. This default can be permanently changed using <b>tlmgr option repository <I>URL</I>|<I>PATH</I></b>, making future <b>tlmgr</b> operations default to the specified source.


title: LOCAL AND OFFLINE REPOSITORIES
content:
For installations without constant internet access, TeX Live allows creation of local repositories from the official TeX Live ISO image or by mirroring the CTAN network repository using tools like <b>rsync</b>. These local repositories can then be specified using the <b>--repository</b> or <b>--location</b> options for offline updates and installations, providing a portable and self-contained TeX Live environment.


title: HISTORY
content:
The concept of a central repository for TeX Live packages has been fundamental since the inception of TeX Live itself, evolving with the distribution. The <b>tlmgr</b> utility, introduced around TeX Live 2008, centralized the management of these repositories, replacing earlier, more manual methods. Its design aimed to simplify package installation and updates by abstracting the repository location and providing robust options for specifying mirror sites or local sources. The <b>--repository</b> and <b>option repository</b> functionalities have been core features of <b>tlmgr</b> since its early versions, reflecting the need for flexible source management in diverse user environments.


title: SYNOPSIS
content:
<B>tlmgr restore</B> <I>&lt;backup_id&gt;</I> [<I>--verify</I>]<br><B>tlmgr restore</B> <I>--list</I><br><B>tlmgr restore</B> <I>--delete</I> <I>&lt;backup_id&gt;</I><br><B>tlmgr restore</B> <I>--delete-all</I>


title: PARAMETERS
content:
<b><I>&lt;backup_id&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the unique identifier of the backup to be restored or deleted. This ID is typically a timestamp in the format <I>YYYY-MM-DD-HH-MM</I>.<br><br><b><I>--list</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all available backups, displaying their unique IDs, creation dates, and sizes. This helps in identifying the correct backup to use.<br><br><b><I>--delete</I> <I>&lt;backup_id&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deletes the specified backup from the backup storage directory. This frees up disk space.<br><br><b><I>--delete-all</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deletes all existing backups. This action is irreversible and should be used with extreme caution.<br><br><b><I>--verify</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When used with a <I>&lt;backup_id&gt;</I>, this option performs an integrity check on the specified backup before proceeding with the restore operation, ensuring the backup is not corrupted.<br><br>


title: DESCRIPTION
content:
The <B>tlmgr-restore</B> command, typically invoked as a subcommand of <B>tlmgr</B> (TeX Live Manager), is used to revert a TeX Live installation to a previously saved state. This powerful recovery tool relies on backups that were created using the <B>tlmgr-backup</B> command. Its primary purpose is to recover from accidental deletions, corrupted installations, or to simply roll back to a known stable configuration prior to a problematic update or change.<br><br>When executed, <B>tlmgr-restore</B> meticulously replaces the current files of your TeX Live distribution with the contents of the specified backup archive. It's a highly destructive operation, as it directly overwrites existing files. Therefore, careful selection of the correct backup ID and a thorough understanding of the implications are paramount before proceeding. Beyond restoration, the command also provides convenient functionalities to list all available backups and to delete specific or all unwanted backups, assisting in managing storage space and maintaining an organized recovery strategy.


title: CAVEATS
content:
Restoring a TeX Live installation is a <B>destructive</B> operation that overwrites existing files. <B>Always ensure you have selected the correct backup ID</B>.<br>This command only restores files managed by TeX Live's package system; it does not manage user-specific configuration files or manually added files outside of the TeX Live package structure.<br>Backups must have been created by <B>tlmgr-backup</B>. Restoring an older state might revert crucial security updates or bug fixes present in newer versions of packages.


title: BACKUP LOCATION
content:
By default, TeX Live backups created by <B>tlmgr-backup</B> are stored in a dedicated directory within your TeX Live installation. This location is typically found under the <I>TEXMFVAR</I> tree, often at <I>$TEXMFVAR/backup</I>. Each backup is usually stored as a compressed archive (e.g., a zip file), with its filename corresponding to the backup's timestamp ID.


title: RESTORATION SCOPE
content:
The <B>tlmgr-restore</B> operation primarily focuses on restoring the state of the TeX Live installation's core files and packages. It ensures that the files managed by <B>tlmgr</B> itself are reverted to their state at the time the backup was created. It does not typically affect system-wide configurations outside the TeX Live tree, user-specific configurations in home directories (e.g., <I>~/.texmf-var</I>), or other custom modifications not directly handled by <B>tlmgr</B>'s package management.


title: HISTORY
content:
The <B>tlmgr</B> (TeX Live Manager) suite, which encompasses the essential backup and restore functionalities, was developed to significantly enhance the management of the comprehensive TeX Live distribution. Prior to <B>tlmgr</B>'s widespread adoption (beginning with TeX Live 2008 and improved in subsequent releases), managing TeX Live installations and updates was often a more manual and error-prone process. The introduction of <B>tlmgr</B> provided a robust, centralized package management system, offering features like dependency resolution, seamless package installation, and the critical ability to create and restore system backups for disaster recovery and version rollback, ensuring greater stability and ease of maintenance for TeX Live users.


title: PARAMETERS
content:
<b><b>--all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Updates all installed packages, including the TeX Live core system and <b>tlmgr</b> itself. This is the most common and recommended update mode.<br><br><b><b>--self</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Updates only the <b>tlmgr</b> program itself to the latest version available in the repository. This is often the first step recommended if you encounter issues with <b>tlmgr</b>.<br><br><b><b>--dry-run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a 'dry run' of the update process. It shows which packages would be updated without actually downloading or installing anything. Useful for previewing changes.<br><br><b><b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces an update or installation, even if TeX Live thinks it's not necessary or if a package is already installed. Use with caution.<br><br><b><b>--clean</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;After a successful update, removes old package backups created during previous updates. This can save disk space. Can also be run separately as <b>tlmgr clean --all</b>.<br><br><b><b>--no-auto-backup</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables the automatic backup of old packages during an update. By default, <b>tlmgr</b> keeps a backup of the previous version of updated packages, allowing for rollback. Use this option to save disk space if backups are not desired.<br><br><b><b>--no-auto-install</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When updating packages, if a new dependency is required, <b>tlmgr</b> normally installs it automatically. This option prevents such automatic installations.<br><br><b><b>--repository <I>URL</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative CTAN repository mirror to use for the update. This can be a local path or a remote URL (e.g., <b>http://mirror.ctan.org/systems/texlive/tlnet</b>). Overrides the default configured repository.<br><br><b><b>--list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all available updates without performing any actions. Similar to <b>--dry-run</b> but typically shows a more concise list of what's available.<br><br><b><b><I>PACKAGE</I>...</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies one or more individual package names to update. If no packages are specified and <b>--all</b> is not used, <b>tlmgr update</b> behaves like <b>--list</b>.<br><br>


title: DESCRIPTION
content:
The <b>tlmgr update</b> command is the primary method for keeping a TeX Live installation current. It is a subcommand of <b>tlmgr</b>, the TeX Live Manager, which handles the installation, removal, and management of TeX Live packages.<br><br>When executed, <b>tlmgr update</b> connects to the configured TeX Live repository (typically an online CTAN mirror) to check for newer versions of installed packages, the TeX Live core system, and even the <b>tlmgr</b> program itself. It can update everything at once, just the manager, or specific packages.<br><br>The update process involves:<br><i>1. Synchronizing local package lists with the repository.</i><br><i>2. Identifying packages that have newer versions available.</i><br><i>3. Downloading the updated files.</i><br><i>4. Installing the new versions, often creating backups of the old files.</i><br><br>Regular use of <b>tlmgr update --all</b> is recommended to ensure you have the latest bug fixes, new features, and compatibility with recent LaTeX documents.


title: CAVEATS
content:
Updating TeX Live can be resource-intensive, requiring a stable internet connection and potentially significant disk space for downloads and backups. Large updates can take a considerable amount of time. It's often recommended to run <b>tlmgr</b> commands that modify the system (like <b>update</b>) with administrator privileges (e.g., using <b>sudo</b> on Linux/macOS or as an administrator on Windows) if TeX Live was installed system-wide. Always ensure a reliable power source, especially on laptops, during critical updates.


title: DEFAULT REPOSITORY CONFIGURATION
content:
By default, <b>tlmgr</b> uses the repository configured during the initial TeX Live installation, which usually points to a nearby CTAN mirror. This configuration is stored in files within your TeX Live installation (e.g., in <b>texmf-dist/web2c/tlmgr.conf</b> or an environment variable). You can view the current repository with <b>tlmgr conf repository</b> or change it permanently with <b>tlmgr option repository <I>URL</I></b>.


title: AUTOMATIC BACKUPS AND ROLLBACK
content:
Unless <b>--no-auto-backup</b> is used, <b>tlmgr update</b> automatically creates backups of old package versions before installing new ones. These backups are stored in a designated backup directory (e.g., <b>/usr/local/texlive/YYYY/tlpkg/backup</b>). This allows you to revert to a previous package version if an update causes issues using the <b>tlmgr restore</b> command.


title: HISTORY
content:
The TeX Live Manager, <b>tlmgr</b>, was introduced with TeX Live 2008, replacing earlier, more rudimentary update scripts (such as <b>install-tl-update</b>). Its development marked a significant improvement in the ease of managing and maintaining TeX Live installations, providing a unified command-line interface for package management, updates, and configuration. The <b>update</b> subcommand has been a core part of <b>tlmgr</b> since its inception, continually evolving with new options and robustness improvements alongside TeX Live's annual releases.


title: PARAMETERS
content:
<b><b>-s</b> <i>seconds</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the delay in seconds between updates. The default is 5 seconds.<br><br><b><b>-l</b> <i>min_load</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the lower bound for the load average scale on the graph. The default is 0.<br><br><b><b>-u</b> <i>max_load</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the upper bound for the load average scale on the graph. The default is 10.<br><br>


title: DESCRIPTION
content:
<i>tload</i> is a lightweight command-line utility for displaying a real-time, text-based graphical representation of the system load average. It provides a simple visual overview of how busy the system has been over a recent period, typically the last minute. By default, it updates every 5 seconds, plotting the 1-minute load average on a terminal-friendly ASCII graph. This tool is useful for a quick, at-a-glance check of system performance without needing a full-featured monitoring application. Its simplicity makes it ideal for quick diagnostics in remote SSH sessions or resource-constrained environments.


title: CAVEATS
content:
<b>Text-based Graphics</b>: The output is ASCII art, which can be less precise or visually appealing than GUI-based tools.<br><b>Limited Detail</b>: Only plots the 1-minute load average, providing a very high-level overview without breaking down CPU, I/O, or other specific metrics.<br><b>Fixed Scale</b>: While configurable with <i>-l</i> and <i>-u</i>, the graph's width is fixed to represent one minute of data, meaning older data scrolls off.


title: <I>OUTPUT INTERPRETATION</I>
content:
The <i>tload</i> output is a scrolling, character-based graph. The Y-axis represents the load average, scaled between the specified lower and upper bounds (default 0-10). The X-axis represents time, with the graph typically showing the last minute of data. Each asterisk (*) or similar character marks a data point, while vertical lines or other characters might indicate the scale or axes. As new data points are plotted on the right, the oldest points on the left scroll off the screen.


title: HISTORY
content:
<i>tload</i> is a long-standing utility included as part of the <i>procps</i> (or <i>procps-ng</i> on modern systems) package. The <i>procps</i> package provides a set of system utilities that gather information from the <i>/proc</i> filesystem, which is a virtual filesystem providing access to kernel data structures. <i>tload</i> has been a part of this suite for many years, offering a simple, text-based monitoring solution that pre-dates many graphical tools and remains useful in shell environments where minimal overhead and quick feedback are paramount.


title: PARAMETERS
content:
<b>-b</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Battery status and cycle count information.<br><br><b>-c</b><br>&nbsp;&nbsp;&nbsp;&nbsp;TLP configuration from /etc/default/tlp and active settings.<br><br><b>-d</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disk/drive parameters, including SATA ALPM and spin-down status.<br><br><b>-e</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Graphics card (AMD, Intel, Nvidia) power management details.<br><br><b>-g</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Global TLP settings and runtime information.<br><br><b>-h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display help message and exit.<br><br><b>-i</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Input/Output device power saving settings.<br><br><b>-l</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Kernel and system power management features and states.<br><br><b>-p</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Processor (CPU) frequency scaling, turbo boost, and idle states.<br><br><b>-r</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Radio devices (Bluetooth, Wi-Fi, WWAN) power states.<br><br><b>-s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Default) Shows a summary of essential power settings.<br><br><b>-t</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Temperatures, fan speeds, and thermal management.<br><br><b>-u</b><br>&nbsp;&nbsp;&nbsp;&nbsp;USB device power saving settings and status.<br><br><b>-w</b><br>&nbsp;&nbsp;&nbsp;&nbsp;PCI/PCIe device power management details.<br><br><b>-z</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Verbose output, showing more detailed information for selected sections.<br><br><b>--auto-mode</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays statistics specifically for TLP's automatic (AC/battery) mode switching.<br><br>


title: DESCRIPTION
content:
<i>tlp-stat</i> is a command-line utility that provides comprehensive information about the current power management settings and operational status configured by TLP, an advanced power management tool for Linux. It allows users to inspect various aspects of their system's power consumption and TLP's active optimizations.<br><br>This tool is essential for verifying TLP's proper functioning, troubleshooting power-related issues, and understanding how TLP influences hardware components to improve battery life and reduce power usage. It can display details for components like battery, CPU, disks, graphics, USB, Wi-Fi, and more.


title: CAVEATS
content:
<i>tlp-stat</i> requires TLP to be installed and running on the system to provide meaningful output. Some information, particularly system-wide statistics or hardware-level details, may require root privileges (e.g., via <b>sudo</b>) to be fully accessible and accurate. The output can be extensive, so piping to <b>less</b> or <b>grep</b> is often useful for filtering.


title: COMBINING OPTIONS
content:
Multiple options can be combined (e.g., <b>tlp-stat -b -c -p</b>) to display information from different sections simultaneously, providing a comprehensive overview tailored to your needs.


title: TROUBLESHOOTING
content:
The output of <b>tlp-stat -s</b> or <b>tlp-stat -g</b> is often requested when reporting issues with TLP, as it provides a quick overview of the active configuration and system state, which is crucial for diagnosis.


title: ROOT PRIVILEGES
content:
For full and accurate system information, especially concerning low-level hardware states or kernel settings, running <b>sudo tlp-stat</b> is highly recommended to bypass permission restrictions.


title: HISTORY
content:
TLP (Linux Advanced Power Management) was initially released around 2011 to address power consumption and battery life issues on Linux laptops. <i>tlp-stat</i> has been an integral part of the TLP suite from its early versions, providing the primary means for users to inspect the effects of TLP's configurations and the actual power states of various hardware components. Its evolution mirrors TLP's growth in supporting more hardware and advanced power-saving techniques.


title: PARAMETERS
content:
<b><b>--generate</b>, <b>-g</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a new temporary email address. This is often the default action if no other command is specified.<br><br><b><b>--list</b>, <b>-l</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all emails received at the current temporary address, showing sender, subject, and message ID.<br><br><b><b>--read</b> <i>&lt;ID&gt;</i>, <b>-r</b> <i>&lt;ID&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads the content of a specific email message identified by its <i>ID</i>. The ID is usually obtained from the <b>--list</b> command.<br><br><b><b>--delete</b> <i>&lt;ID&gt;</i>, <b>-d</b> <i>&lt;ID&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deletes a specific email message identified by its <i>ID</i> from the temporary mailbox.<br><br><b><b>--delete-address</b>, <b>-D</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deletes the currently active temporary email address and all associated messages.<br><br><b><b>--address</b> <i>&lt;ADDRESS&gt;</i>, <b>-a</b> <i>&lt;ADDRESS&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses a pre-existing temporary email <i>ADDRESS</i> instead of generating a new one. Useful for continuing a session.<br><br><b><b>--domain</b> <i>&lt;DOMAIN&gt;</i>, <b>-m</b> <i>&lt;DOMAIN&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a custom <i>DOMAIN</i> to use when generating a new temporary email address. E.g., 'example.com'.<br><br><b><b>--check</b> <i>&lt;INTERVAL&gt;</i>, <b>-c</b> <i>&lt;INTERVAL&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Periodically checks for new emails at the specified <i>INTERVAL</i> (in seconds).<br><br><b><b>--wait</b>, <b>-w</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Waits indefinitely for new emails to arrive, checking periodically.<br><br><b><b>--no-browser</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents opening a web browser when reading email content (e.g., for HTML emails).<br><br><b><b>--output</b> <i>&lt;FORMAT&gt;</i>, <b>-o</b> <i>&lt;FORMAT&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output <i>FORMAT</i> for data, such as 'json' for programmatic use.<br><br><b><b>--auto-open</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Automatically opens new emails (e.g., in browser if content is HTML) as they arrive when checking.<br><br><b><b>--no-color</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables colored output in the terminal.<br><br><b><b>--version</b>, <b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the <b>tmpmail</b> version information.<br><br><b><b>--help</b>, <b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the command's help message and exits.<br><br>


title: DESCRIPTION
content:
The <b>tmpmail</b> command-line utility provides a simple and efficient way to interact with temporary email services directly from your terminal. It allows users to quickly generate disposable email addresses, list incoming messages, read email content, and manage (delete) both individual messages and the temporary address itself. This is particularly useful for anonymously signing up for services, testing applications, or avoiding spam by providing a temporary address instead of your primary one. <i>tmpmail</i> streamlines the process of managing ephemeral mailboxes without requiring a web browser or a full-fledged email client, making it a valuable tool for developers, privacy-conscious users, and anyone needing a quick, throwaway email address.


title: CAVEATS
content:
<b>tmpmail</b> relies on external temporary email services. The reliability, longevity, and privacy guarantees are dependent on the chosen backend service. Emails received via these services are generally public and unencrypted. It is <i>not recommended</i> for sensitive communications or long-term email storage. Addresses and messages are typically ephemeral and may be automatically purged after a short period. Users should be aware of the potential for service downtime or changes in API behavior.


title: TYPICAL USAGE WORKFLOW
content:
A common workflow involves: <br>1. Generating an address: <b>tmpmail --generate</b><br>2. Using the address for registration.<br>3. Listing emails: <b>tmpmail --list</b><br>4. Reading a specific email: <b>tmpmail --read <i>&lt;ID&gt;</i></b><br>5. Optionally, deleting messages or the address when done: <b>tmpmail --delete <i>&lt;ID&gt;</i></b> or <b>tmpmail --delete-address</b>.


title: PRIVACY AND SECURITY
content:
It's crucial to understand that temporary email services, by their nature, are <i>not secure or private</i>. They are designed for convenience and anonymity in registration, not for confidential communication. Anyone can potentially view messages sent to a public temporary address if they know the address or can guess it. Therefore, <b>never use tmpmail for sensitive information, personal accounts, or anything you wouldn't want publicly accessible.</b>


title: HISTORY
content:
While specific official history for <b>tmpmail</b> as a standalone project can vary (as there might be multiple implementations, e.g., Python-based scripts), the concept of temporary email services (like Mailinator, Mail.tm, Guerrilla Mail) has existed for many years to combat spam and provide disposable addresses. Command-line wrappers like <i>tmpmail</i> emerged to provide a more direct, terminal-centric interface to these web services, fitting into the Unix philosophy of chaining tools. Its development typically focuses on ease of use and integration with popular temporary mail APIs, evolving with the underlying services it connects to.


title: SYNOPSIS
content:
tmsu <b>[GLOBAL_OPTIONS]</b> <b><COMMAND></b> <b>[OPTIONS]</b> <b>[ARGUMENTS]</b><br><br>Common commands include:<br><i>tmsu tag</i> <b>[OPTIONS]</b> <I>FILE...</I> <I>TAG...</I> &nbsp;&nbsp;&nbsp;&nbsp;<i># Add tags to files</i><br><i>tmsu untag</i> <b>[OPTIONS]</b> <I>FILE...</I> <I>TAG...</I> &nbsp;&nbsp;<i># Remove tags from files</i><br><i>tmsu mount</i> <b>[OPTIONS]</b> <I>[MOUNTPOINT]</I> &nbsp;&nbsp;<i># Mount the FUSE filesystem</i><br><i>tmsu files</i> <b>[OPTIONS]</b> <I>[QUERY]</I> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<i># List files matching a tag query</i><br><i>tmsu tags</i> <b>[OPTIONS]</b> <I>[QUERY]</I> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<i># List tags</i>


title: PARAMETERS
content:
<b>--config <FILE></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Specify an alternative configuration file.</b><br>Defaults to <I>~/.tmsu/tmsu.conf</I>.<br><br><b>--database <FILE></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Specify an alternative database file.</b><br>Defaults to <I>~/.tmsu/db.sqlite3</I>.<br><br><b>--force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Force an operation that would otherwise require confirmation.</b><br><br><b>--no-confirm</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Do not ask for confirmation for destructive operations.</b><br><br><b>--quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Suppress output messages.</b><br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Display version information and exit.</b><br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Display help information and exit.</b><br><br>


title: DESCRIPTION
content:
<i>tmsu</i> is a powerful command-line utility for tagging files and directories. Instead of relying on rigid directory structures, <i>tmsu</i> allows you to attach arbitrary keywords (tags) to your files, providing a flexible and dynamic way to organize and retrieve them. It stores these tags in a lightweight <I>SQLite</I> database. One of its most distinctive features is the ability to <b>mount a FUSE filesystem</b>, which presents a virtual view of your files organized by their tags. For instance, you can navigate to a directory like <I>~/tmsu/mount/photos+vacation</I> to see all files tagged with both "photos" and "vacation". This enables powerful multi-dimensional searching and browsing without duplicating or moving your original files. <i>tmsu</i> supports operations like adding, removing, renaming, and listing tags, as well as complex tag queries.


title: CAVEATS
content:
<i>tmsu</i> relies on the <b>FUSE (Filesystem in Userspace)</b> kernel module for its virtual filesystem capabilities. This means FUSE must be installed and properly configured on your system.<br>The performance of the virtual filesystem might be less than native filesystems, especially with very large numbers of files or complex tag queries, as it involves database lookups and FUSE overhead.<br><i>tmsu</i>'s database (<I>db.sqlite3</I>) is crucial; damaging or corrupting it can lead to loss of tag information. Regular backups are recommended.<br>The FUSE mount presents a <b>symbolic view</b> of your files. Operations like deleting files via the <I>tmsu</I> mount will typically remove the file from your actual filesystem, not just its tags. Be cautious.


title: DATABASE LOCATION
content:
By default, <i>tmsu</i> stores its tag database in <b><I>~/.tmsu/db.sqlite3</I></b>. It is important to back up this file regularly to prevent loss of your tagging information.


title: TAG QUERY LANGUAGE
content:
<i>tmsu</i> supports a simple yet powerful query language for retrieving files. Tags can be combined using <b>Boolean operators</b> such as <I>AND</I> (implicit space), <I>OR</I> (<I>|</I>), and <I>NOT</I> (<I>-</I> or <I>!</I>). Parentheses can be used for grouping. For example, <I>"photos and (vacation or travel) -europe"</I> would find photos from vacations or travel that are not from Europe.


title: AUTOMATIC TAGGING
content:
While not a core feature, <i>tmsu</i> can be integrated with scripts to automatically tag files based on their content, metadata, or other criteria, expanding its utility beyond manual tagging.


title: HISTORY
content:
<i>tmsu</i> was created by Paul H., with initial public releases and development activity around <b>2013-2014</b>. It's written in <b>C++</b> and designed to be fast and robust, leveraging <I>SQLite</I> for its backend. While development activity has seen periods of varying intensity, it remains a stable and functional tool, prized by users who prefer command-line interfaces and highly customizable file organization.


title: SEE ALSO
content:
find(1): Traditional command for finding files based on name, type, size, modification time, etc., locate(1): Fast database-driven file lookup, primarily by name., etik(1): Another command-line file tagging utility.


title: SYNOPSIS
content:
<b>tmt</b> [<i>GLOBAL_OPTIONS</i>] <<i>COMMAND</i>> [<i>COMMAND_OPTIONS</i>] [<i>ARGUMENTS</i>...]<br><br>Common commands include:<br>  <b>tmt init</b>: Initialize a new tmt project.<br>  <b>tmt run</b>: Run tests according to a plan.<br>  <b>tmt test</b>: Manage test cases.<br>  <b>tmt plan</b>: Manage test plans.<br>  <b>tmt story</b>: Manage user stories.<br>  <b>tmt results</b>: Display and manage test results.


title: PARAMETERS
content:
<b><i>--debug</i>, <i>-d</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable debug output for detailed information.<br><br><b><i>--verbose</i>, <i>-v</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output for more information during execution.<br><br><b><i>--force</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the operation, typically overriding existing files or ignoring certain warnings.<br><br><b><i>--dry-run</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Simulate the operation without making any actual changes to the system or project.<br><br><b><i>--path <i>PATH</i></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the working directory or project root for the command. Defaults to current directory.<br><br><b><i>--yes</i>, <i>-y</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assume 'yes' to all prompts and run non-interactively.<br><br><b><i>--help</i>, <i>-h</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show help message and exit. Can be used with subcommands (e.g., <b>tmt run --help</b>).<br><br>


title: DESCRIPTION
content:
<b>tmt</b>, which stands for Test Management Tool, is a comprehensive framework for designing, executing, and analyzing tests on Linux systems, particularly focused on Fedora, CentOS, and Red Hat Enterprise Linux. It's a Python-based, open-source solution that allows users to define test plans, create test cases, execute them across various environments (local, virtual machines, containers), and gather results. <br><br>It aims to streamline the testing workflow from development to deployment, integrating with various tools and platforms. <b>tmt</b> provides a flexible and declarative way to describe tests, enabling repeatable and robust testing strategies for projects and distributions.


title: CAVEATS
content:
<b>tmt</b> is not a standard, built-in Linux utility. It needs to be installed separately, typically via a package manager (e.g., <i>dnf install tmt</i> on Fedora/RHEL). Its primary use-case is focused on test management and quality assurance workflows for software projects, making it less of a general-purpose command-line tool.


title: KEY FEATURES
content:
<b>tmt</b> offers declarative test definition using YAML, support for flexible test environments (local, virtual machines, containers), comprehensive result reporting, seamless integration with Continuous Integration/Continuous Delivery (CI/CD) pipelines, and a modular, extensible design that allows for custom extensions and plugins.


title: TYPICAL WORKFLOW
content:
Users typically define test cases and test plans within their project's repository using YAML files. The <b>tmt init</b> command sets up the project structure. Tests are then executed using <b>tmt run</b>, which can provision environments, execute tests, and collect results. Results can then be reviewed using <b>tmt results</b> or integrated with external reporting tools.


title: HISTORY
content:
<b>tmt</b> was developed by Red Hat as an open-source project to address the growing need for robust and scalable test management within their development and quality assurance processes, especially for Fedora and Red Hat Enterprise Linux. It has evolved into a comprehensive framework with a strong community backing, aiming to simplify and standardize the testing of complex software stacks and distributions. Its development emphasizes flexibility, extensibility, and integration with modern CI/CD pipelines.


title: SYNOPSIS
content:
<B>tmt run</B> [<I>OPTIONS</I>] [<I>COMMANDS</I>...]<br><B>tmt run</B> <I>discover</I> [<I>discover_options</I>] <I>execute</I> [<I>execute_options</I>] <I>report</I> [<I>report_options</I>]<br><B>tmt run</B> <I>plan</I> <I>--name</I> <I>/path/to/plan</I> [<I>plan_options</I>]<br>The <B>tmt run</B> command itself initiates a test run, often followed by specific <I>sub-commands</I> like <I>discover</I>, <I>provision</I>, <I>prepare</I>, <I>execute</I>, <I>report</I>, and <I>finish</I>, which represent stages of the test execution lifecycle. Options before sub-commands apply to the entire run, while options after sub-commands apply only to that specific stage.


title: PARAMETERS
content:
<b>--id <ID></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Reuse</I> an existing test run identified by its unique <B>ID</B>, allowing continuation or re-evaluation.<br><br><b>--scratch</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Start the test run <I>from scratch</I>, clearing any previous artifacts or cached data for a clean slate.<br><br><b>--dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform a <I>simulated run</I> without actually executing tests or making changes, showing what would happen.<br><br><b>--force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Force</I> the operation, overriding certain checks or previous states that might otherwise prevent the run.<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increase the <I>verbosity</I> of the output, providing more detailed information about the execution process.<br><br><b>--debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable <I>debug</I> level output, providing maximum detail for troubleshooting.<br><br><b>--guest <GUEST></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify one or more <I>guest systems</I> or virtual environments on which to run the tests.<br><br><b>--plan <PLAN></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Directly specify the <I>test plan</I> to be executed, typically a path to an FMF plan file.<br><br><b>--context <KEY=VALUE></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set <I>key-value pairs</I> for the test run context, influencing how tests or plans behave.<br><br>


title: DESCRIPTION
content:
<I>tmt-run</I> is the core command for executing test plans defined within the <B>Test Management Tool (TMT)</B> framework. It orchestrates the entire test lifecycle, from discovering tests to provisioning environments, preparing them, executing the tests, and finally generating reports.<br><br>It acts as the central control point for running tests, supporting various environments like local machines, virtual machines (via <I>libvirt</I>, <I>Vagrant</I>), and containers (<I>Podman</I>, <I>Docker</I>). Users define their test plans, tests, and stories using <B>Flexible Metadata Format (FMF)</B> files, and <I>tmt-run</I> interprets these definitions to automate the testing process, making it efficient and repeatable.


title: CAVEATS
content:
Successful execution with <I>tmt-run</I> relies heavily on a <B>correctly structured TMT project</B> and well-defined <B>FMF metadata</B> files. Issues with test plan syntax, missing dependencies (e.g., specific provisioning tools like <I>libvirt</I> or <I>Podman</I>), or environment misconfigurations can lead to failures. Users should be familiar with the TMT lifecycle and debugging output to diagnose problems effectively. Complex test setups might require significant system resources.


title: TEST LIFECYCLE STAGES
content:
The <I>tmt-run</I> command orchestrates a defined sequence of stages: <B>discover</B> (find tests), <B>provision</B> (prepare testing environment), <B>prepare</B> (install dependencies), <B>execute</B> (run tests), <B>report</B> (generate results), and <B>finish</B> (clean up). Users can run specific stages or the entire pipeline.


title: FLEXIBLE METADATA FORMAT (FMF)
content:
<I>tmt-run</I> critically depends on test, plan, and story definitions written in <B>FMF</B>, a YAML-based format. This declarative approach allows for version-controlled, human-readable test specifications.


title: HISTORY
content:
<B>TMT (Test Management Tool)</B>, and by extension <I>tmt-run</I>, was developed by <B>Red Hat</B> as an open-source solution for managing and executing Linux test suites. Its development began in the late 2010s, aiming to provide a modern, declarative, and scalable approach to test automation for Fedora and other Linux distributions. <I>tmt-run</I> has evolved to integrate with various provisioning backends and reporting formats, becoming a robust tool for continuous integration and testing workflows in the Linux ecosystem.


title: PARAMETERS
content:
<b>[<I>PLAN</I>...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more paths to FMF-defined test plans to execute. If omitted, <I>tmt</I> searches for plans in the current directory.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message and exits, showing available options and their usage.<br><br><b>--id <I>ID</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a unique run <I>ID</I> of a previous <I>tmt</I> run to resume or re-run.<br><br><b>--last</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Re-runs the most recently executed <I>tmt</I> run, useful for quick iterations.<br><br><b>--filter <I>FILTER</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes tests matching the provided FMF filter expression (e.g., 'tier:1', 'tags:smoke').<br><br><b>--exclude <I>EXCLUDE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Excludes tests matching the provided FMF filter expression.<br><br><b>--scratch</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes the run in a <I>clean, isolated, temporary work directory</I> that is deleted afterwards.<br><br><b>--remove</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ensures the work directory is <I>removed</I> upon completion, regardless of success or failure.<br><br><b>--keep</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ensures the work directory is <I>retained</I> upon completion, useful for post-run inspection and debugging.<br><br><b>--dry</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a <I>dry run</I>, showing planned actions and selected tests without actual execution.<br><br><b>--rerun</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Re-executes <I>only tests that previously failed</I> within the specified (or last) run.<br><br><b>--reboot</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows the <I>system under test to reboot</I> during test execution if a test requires it.<br><br><b>--resume</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Resumes an interrupted or failed <I>tmt</I> run from its last recorded state.<br><br><b>--force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces execution, ignoring some warnings or previous failures, useful for overcoming minor issues.<br><br><b>--report</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a <I>test report</I> in various formats (e.g., HTML, JUnit XML) upon completion.<br><br><b>--environment <I>KEY=VALUE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets one or more <I>environment variables</I> for the test execution environment.<br><br><b>--work-dir <I>DIR</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a <I>custom directory</I> where <I>tmt</I> will store run-specific working files and results.<br><br><b>--until <I>STAGE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes the test plan only <I>up to and including</I> the specified lifecycle stage (e.g., 'execute', 'report').<br><br><b>--since <I>STAGE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes the test plan <I>starting from and including</I> the specified lifecycle stage (e.g., 'prepare', 'execute').<br><br><b>--verbose, --debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases the verbosity of output messages, providing more detailed information for troubleshooting.<br><br>


title: DESCRIPTION
content:
The <I>tmt-try</I> command (typically invoked as <B>tmt try</B>) is a core component of the Test Management Tool (<I>tmt</I>) suite. It enables developers and testers to easily run, debug, and iterate on test plans and individual tests, primarily in local or temporary environments.<br><br>Unlike full-scale CI/CD orchestrations, <B>tmt try</B> focuses on providing a quick and flexible way to execute selected parts of a test plan, specific tests, or stages of the test lifecycle. This makes it invaluable for:<br><ul><li><I>Local development:</I> Quickly verifying changes before committing.</li><li><I>Debugging:</I> Re-running failed tests, inspecting work directories, or executing up to a specific stage.</li><li><I>Ad-hoc testing:</I> Running a subset of tests with custom parameters.</li></ul><br>It leverages <I>tmt</I>'s Flexible Metadata Format (FMF) to discover and execute tests, providing options to filter, exclude, resume, or force execution, granting fine-grained control over the testing process.


title: CAVEATS
content:
The command requires the <I>tmt</I> package to be installed on the system. Proper FMF test plans and metadata must be defined for <B>tmt try</B> to discover and execute tests correctly. Running tests that require specific provisioning (e.g., remote virtual machines) may necessitate additional setup and dependencies (e.g., <I>tmt-provision-container</I> or <I>tmt-provision-virtual</I> plugins).


title: FMF (FLEXIBLE METADATA FORMAT)
content:
<B>tmt try</B> relies heavily on FMF to define test plans, tests, stories, and other metadata. FMF is a hierarchical YAML-based format that allows for flexible organization and discovery of test artifacts.


title: EXECUTION STAGES
content:
<B>tmt try</B> orchestrates tests through a series of well-defined stages: <I>Discover</I> (find tests), <I>Provision</I> (set up environment), <I>Prepare</I> (install dependencies), <I>Execute</I> (run tests), <I>Report</I> (generate results), and <I>Finish</I> (clean up). The <I>--until</I> and <I>--since</I> options allow targeting specific stages for focused execution or debugging.


title: HISTORY
content:
<I>tmt</I> (Test Management Tool) was developed by Red Hat and Fedora infrastructure teams to standardize and simplify test execution across various environments, from local development to large-scale CI/CD pipelines. <B>tmt try</B> emerged as a crucial component to address the interactive and debugging needs of developers, providing a focused interface for quick test iterations and deep analysis of failures, a common requirement in agile development workflows.


title: PARAMETERS
content:
<b><b>-2</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force 256-colour terminal mode, overriding any terminfo capabilities to ensure richer color support.<br><br><b><b>-8</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force 88-colour terminal mode, overriding any terminfo capabilities. Less common than <b>-2</b>.<br><br><b><b>-c</b> <i>shell-command</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an alternative shell command to be used for new windows and panes, overriding the default shell.<br><br><b><b>-f</b> <i>file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an alternative configuration file to load instead of the default <i>~/.tmux.conf</i>. Useful for custom setups.<br><br><b><b>-L</b> <i>socket-name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a different socket name for the server. This allows running multiple independent <i>tmux</i> servers concurrently.<br><br><b><b>-S</b> <i>socket-path</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a full path to the server socket. This option overrides <b>-L</b> for precise socket control.<br><br><b><b>-l</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable the creation of a login shell for new windows and panes, affecting environment variable loading.<br><br><b><b>-r</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force a refresh of the client. Useful for resolving display issues or redrawing the terminal content.<br><br><b><b>-u</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Unbind all key bindings when starting <i>tmux</i>. Primarily used for debugging configuration issues.<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose logging to standard error. Provides detailed output for troubleshooting.<br><br>


title: DESCRIPTION
content:
<i>tmux</i> (Terminal MUltipleXer) is a powerful utility that allows users to create, manage, and switch between multiple independent terminal sessions from a single window. It operates on a client-server model, enabling sessions to persist even after the user disconnects or the network connection drops. This persistence makes it invaluable for long-running processes on remote servers or during unstable network conditions, as you can detach from a session and reattach later from the same or a different terminal.<br><br>Beyond persistence, <i>tmux</i> facilitates an efficient workflow by allowing the division of a single terminal into multiple 'windows' and 'panes'. Windows can host different applications or tasks, while panes further subdivide a window for simultaneous viewing of command outputs, logs, or code. Sessions can also be shared, allowing multiple users to attach to and interact with the same terminal environment, making it a great tool for collaboration and pair programming.


title: CAVEATS
content:
Mastering <i>tmux</i> typically involves a learning curve, particularly for its default keybindings and the syntax of its configuration file (<i>~/.tmux.conf</i>). While highly flexible, complex configurations can sometimes interact unexpectedly with specific terminal emulators or other applications. It's crucial to remember that detaching from a <i>tmux</i> session does not terminate the processes running within it; they continue in the background until the session is explicitly killed or the <i>tmux</i> server stops.


title: KEY CONCEPTS
content:
<i>tmux</i> operates with a hierarchical structure: a <b>server</b> hosts multiple <b>sessions</b>. Each session can contain multiple <b>windows</b>, and each window can be further divided into multiple rectangular <b>panes</b>. Users interact with these components using <i>tmux</i> commands.


title: PREFIX KEY
content:
Most <i>tmux</i> commands are initiated by pressing a 'prefix key' combination, followed by another key. The default prefix key is <b>C-b</b> (Control + b). For example, to create a new window, you would type <b>C-b c</b>; to split a pane vertically, <b>C-b %</b>.


title: CONFIGURATION FILE
content:
<i>tmux</i> is highly customizable through its configuration file, which is typically located at <i>~/.tmux.conf</i>. This file allows users to remap keybindings, set options for sessions, windows, and panes, and automate common tasks using shell commands or scripts.


title: COMMON SUBCOMMANDS
content:
Beyond the top-level options, <i>tmux</i> provides numerous subcommands for daily use:<br><i>new-session</i> (or <i>new</i>): Create and attach to a new session.<br><i>attach-session</i> (or <i>attach</i>): Attach to an existing session.<br><i>list-sessions</i> (or <i>ls</i>): List all active sessions.<br><i>kill-session</i>: Terminate a specific session.<br><i>kill-server</i>: Terminate all <i>tmux</i> sessions and the server.


title: HISTORY
content:
<i>tmux</i> was created by Nicholas Marriott and first released in 2007. It rapidly gained popularity as a more modern, open-source alternative to GNU Screen, aiming to provide a cleaner codebase, a more robust client-server architecture, and enhanced extensibility. Over the years, <i>tmux</i> has benefited from active development, focusing on performance, flexibility, and a rich set of features, cementing its position as a preferred terminal multiplexer for developers and system administrators.


title: SYNOPSIS
content:
<b>tmuxinator</b> <I>command</I> [<I>args</I>]<br><i>Common commands include:</i><br><b>tmuxinator</b> <I>start</I> <I>project_name</I> [<I>args</I>]<br><b>tmuxinator</b> <I>new</I> <I>project_name</I><br><b>tmuxinator</b> <I>edit</I> <I>project_name</I><br><b>tmuxinator</b> <I>list</I>


title: PARAMETERS
content:
<b>start <name> [args]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Starts or attaches to a tmux session for the specified project. Additional arguments are passed directly to `tmux`.</i><br><br><b>new <name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Creates a new project configuration file (e.g., `~/.config/tmuxinator/<name>.yml`) and opens it for editing in the `$EDITOR`.</i><br><br><b>edit | open | config <name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Opens the configuration file for the specified project in `$EDITOR`. These are aliases for the same functionality.</i><br><br><b>list | ls</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Lists all available tmuxinator projects that have configuration files.</i><br><br><b>delete | rm <name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Deletes the specified project's configuration file.</i><br><br><b>stop <name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Stops the `tmux` session associated with the project, if it is currently running.</i><br><br><b>local [name]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Creates a `.tmuxinator.yml` file in the current directory. This is useful for project-specific configurations that live with the codebase. An optional `name` can be provided for this local project.</i><br><br><b>debug <name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Outputs the processed project configuration, including resolved paths and variables. This is very useful for troubleshooting issues with project startup.</i><br><br><b>doctor</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Diagnoses potential issues with the tmuxinator installation, `tmux` setup, and environment variables.</i><br><br><b>implode</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Deletes all tmuxinator project configuration files from the default configuration directory. Use with caution.</i><br><br><b>version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Displays the installed tmuxinator version.</i><br><br><b>help [command]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Shows help information for a specific command or for `tmuxinator` itself if no command is specified.</i><br><br>


title: DESCRIPTION
content:
<i>tmuxinator</i> is a powerful command-line tool that simplifies the management of `tmux` sessions. It allows users to define complex `tmux` window, pane, and command layouts for specific projects using simple YAML configuration files. Instead of manually creating windows and splitting panes every time you start a project, <i>tmuxinator</i> automates this process.<br><br>Users create a `.tmuxinator.yml` file for each project, specifying the project's root directory, environment variables, pre-window/pane commands, and the layout of windows and their respective panes, including commands to run within each. When <b>tmuxinator start &lt;project_name&gt;</b> is executed, it reads this configuration and launches a new or attaches to an existing `tmux` session with the predefined setup. This greatly enhances productivity for developers and users who frequently work on multiple projects, each requiring a specific terminal environment. It integrates seamlessly with `tmux`, providing a streamlined workflow for reproducible development environments.


title: CAVEATS
content:
<i>tmuxinator</i> requires `tmux` to be installed and accessible in the system's PATH. Project configuration relies on YAML syntax, which can be sensitive to indentation and formatting; errors in the YAML file can prevent a session from starting correctly. Environmental variables and shell specifics (e.g., sourcing `~/.bashrc`) might need careful handling within the YAML configuration for commands to execute as expected. While <i>tmuxinator</i> handles session creation and management, users still need basic `tmux` knowledge to navigate within the session once it's launched.


title: CONFIGURATION FILES
content:
<i>tmuxinator</i> projects are defined in YAML files. Global projects are typically stored in `~/.config/tmuxinator/` (or `~/.tmuxinator/` for older versions), while local, project-specific configurations can be named `.tmuxinator.yml` in the project's root directory. These files specify the project's root path, environment variables, pre-session commands, windows, panes, and commands to run within each.


title: INTEGRATION WITH SHELLS
content:
Users often integrate <i>tmuxinator</i> into their shell dotfiles (e.g., `.bashrc`, `.zshrc`) to set up aliases or custom functions for quick project launching, further streamlining their workflow. This allows for commands like `<b>p project_name</b>` to launch a full development environment.


title: HISTORY
content:
<i>tmuxinator</i> was created by Christopher White and is primarily developed in Ruby, distributed as a Ruby gem. Its development began to address the need for easily reproducible `tmux` session configurations for development projects, allowing users to define complex window and pane layouts with associated commands in a declarative manner. Since its inception, it has become a widely adopted tool in the developer community for enhancing productivity within terminal environments, providing a structured approach to managing diverse project workspaces.


title: SEE ALSO
content:
tmux(1): <i>Terminal multiplexer, the core tool `tmuxinator` manages and automates.</i>, byobu(1): <i>Another text-based window manager that uses `tmux` or `screen` as its backend, offering a higher-level abstraction.</i>, screen(1): <i>GNU Screen, an older terminal multiplexer with similar functionality to `tmux`.</i>, yaml(7): <i>YAML Ain't Markup Language, the data serialization format used for `tmuxinator` project configurations.</i>


title: SYNOPSIS
content:
Not applicable for a standard Linux command.<br><br> The syntax for a custom 'tod' command would depend entirely on its script or program definition, as it is not part of the standard set of Linux utilities.


title: PARAMETERS
content:
<b>N/A</b><br>&nbsp;&nbsp;&nbsp;&nbsp;No standard parameters exist for 'tod'. Any parameters would be defined by the custom script's implementation on a given system.<br><br>


title: DESCRIPTION
content:
The command <b>tod</b> is <br><b>not a standard Linux command</b><br> found in common Linux distributions. Unlike widely recognized utilities such as <i>ls</i>, <i>grep</i>, or <i>date</i>, there is no official man page or universally documented functionality for a command explicitly named 'tod' within the core Linux ecosystem. <br><br> If 'tod' exists on a particular system, it is almost certainly a <br><b>custom script</b><br> or <br><b>alias</b><br> created by a user or system administrator, or it might be part of a highly specialized, niche application that is not universally distributed. <br><br> The acronym 'TOD' commonly stands for 'Time Of Day' in various computing contexts (e.g., NTP, time synchronization protocols), suggesting that a custom 'tod' command, if present, might be related to displaying, setting, or manipulating time-related information. However, its exact behavior, purpose, and available options would be <br><b>entirely dependent on its specific implementation</b><br> on that particular system.


title: CAVEATS
content:
Since <b>tod</b> is not a standard command, its usage and behavior are not universally defined and carry several important caveats:<br><br><b><i>Undefined Behavior</i></b>: The functionality of a 'tod' command is entirely dependent on its local implementation. Without inspecting the script or program, its actions are unpredictable.<br><br><b><i>Security Risk</i></b>: Executing unknown scripts, especially those found online or from unverified sources, can pose significant security risks, including the potential for malicious code execution or system compromise.<br><br><b><i>Lack of Documentation</i></b>: There is no universal documentation (such as man pages) for 'tod'. Any understanding of its purpose and options requires local documentation or direct examination of the script's code.<br><br><b><i>Portability Issues</i></b>: A custom 'tod' script present on one system will almost certainly not exist or behave identically on another, leading to portability challenges in scripts or workflows.


title: IDENTIFYING A LOCAL 'TOD' COMMAND
content:
If 'tod' exists and is executable on your system, it is likely a custom script or alias defined in your shell's configuration (e.g., .bashrc) or an executable located within your system's PATH. To identify its source, you can use:<br><i>type tod</i><br>or<br><i>which tod</i><br>Once located, you can inspect its content (e.g., '<i>cat $(which tod)</i>') to understand its functionality and any specific options it supports. Alternatively, consult your system administrator or relevant project documentation for details specific to your local environment.


title: HISTORY
content:
There is <br><b>no documented historical development</b><br> for a standard 'tod' Linux command, as it does not exist as a core utility in common distributions. Any 'history' would pertain to specific, localized implementations of custom scripts or tools.


title: PARAMETERS
content:
<b>add "Task description"</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a new task to your todo list. Quotes are recommended for tasks with spaces.<br><br><b>ls [filter]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists tasks. Can be filtered by keywords, projects, or contexts (e.g., <b>ls +work @home</b>).<br><br><b>do <item#></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Marks a task as done. The task is moved from <i>todo.txt</i> to <i>done.txt</i>.<br><br><b>del <item#></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deletes a task from the todo list.<br><br><b>pri <item#> <A|B|C></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets or changes the priority of a task. 'A' is the highest priority.<br><br><b>archive</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Moves all completed tasks from <i>todo.txt</i> to <i>done.txt</i>, if not already moved by 'do'.<br><br><b>listall</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all tasks, including those marked as done in <i>done.txt</i>.<br><br><b>report</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays statistics about your todo list, such as task counts.<br><br><b>help [action]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows help for the command or a specific action.<br><br>


title: DESCRIPTION
content:
The <b>todo</b> command, commonly implemented as the <i>todo.sh</i> script, is a lightweight, portable, and extensible command-line tool for managing your tasks using a simple, human-readable plain text file format known as <i>todo.txt</i>.<br><br>It enables users to quickly add, list, prioritize, mark as complete, and archive tasks directly from the terminal, without the need for complex databases or graphical interfaces. Its strength lies in its simplicity and reliance on standard text files, making task lists easily accessible, editable with any text editor, and seamlessly integrable with version control systems or cloud synchronization services. The <i>todo.txt</i> format itself allows for projects (prefixed with '+') and contexts (prefixed with '@'), providing basic categorization capabilities. This utility is ideal for users who prefer a minimalist, keyboard-driven workflow for personal task management.


title: CAVEATS
content:
The 'todo' command is <i>not</i> a standard, pre-installed utility on most Linux distributions. It typically refers to a third-party script, most notably <i>todo.sh</i> by ginat, which needs to be downloaded and configured by the user. Therefore, its availability and exact behavior can vary depending on the specific script version or custom implementations. It relies on plain text files, which, while simple, might not scale well for extremely large task lists or scenarios requiring robust multi-user access and synchronization without external tools.


title: FILE FORMAT AND LOCATION
content:
The <b>todo</b> command primarily operates on two files: <i>todo.txt</i> (for active tasks) and <i>done.txt</i> (for completed tasks). By default, these files are usually expected in the user's home directory (<i>~/todo.txt</i> and <i>~/done.txt</i>), though their location can often be configured via environment variables.


title: EXTENSIBILITY
content:
<i>todo.sh</i> is highly extensible through an add-on system, allowing users to create or install custom scripts to add new functionalities or integrate with other tools. This makes it very flexible for tailored workflows.


title: SYNCHRONIZATION
content:
Due to its plain text nature, <b>todo</b> lists can be easily synchronized across devices using standard file synchronization services like Dropbox, Google Drive, or version control systems like Git, without any special software.


title: HISTORY
content:
The concept of managing tasks using plain text files gained significant traction with the introduction of the <i>todo.txt</i> format by Gina Trapani in 2006. She proposed a simple, human-readable convention for task entries, including priority, creation date, completion date, projects, and contexts. The <i>todo.sh</i> script emerged as the official and most widely adopted command-line interface to interact with these <i>todo.txt</i> files, embodying the philosophy of simplicity, portability, and independence from complex software. Its development has focused on maintaining a minimal footprint while providing essential task management features, making it a popular choice for command-line enthusiasts.


title: SYNOPSIS
content:
<b>todo.sh</b> <i>[GLOBAL_OPTIONS]</i> <i>ACTION</i> <i>[ARGUMENTS]</i><br><br>Examples:<br><b>todo.sh add</b> <i>"Buy milk +groceries @shop"</i><br><b>todo.sh ls</b><br><b>todo.sh do</b> <i>1</i><br><b>todo.sh mv</b> <i>1 2</i>


title: PARAMETERS
content:
<b><b>-a</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Act on all todo.txt files across configured directories.<br><br><b><b>-d</b> <i>DIR</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an alternative directory for todo.txt files.<br><br><b><b>-f</b> <i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an alternative todo.txt file.<br><br><b><b>-p</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the path to the current todo.txt file.<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the script version.<br><br><b><b>add</b> <i>TEXT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a new task to the todo list. Supports contexts (<i>@context</i>) and projects (<i>+project</i>).<br><br><b><b>addm</b> <i>TEXT1 TEXT2 ...</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds multiple tasks at once.<br><br><b><b>ls</b> <i>[TERMS]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists tasks. Can filter by keywords, contexts, or projects.<br><br><b><b>do</b> <i>ITEM# [TEXT]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Marks a task as done and moves it to <i>done.txt</i>. Optional text is appended to the completed task.<br><br><b><b>rm</b> <i>ITEM#</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes a task from the todo list (typically moves it to <i>done.txt</i>).<br><br><b><b>prio</b> <i>ITEM# PRIORITY</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets or changes a task's priority (e.g., A, B, C).<br><br><b><b>dp</b> <i>ITEM#</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes a task's priority.<br><br><b><b>app</b> <i>ITEM# TEXT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Appends text to an existing task.<br><br><b><b>prep</b> <i>ITEM# TEXT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prepends text to an existing task.<br><br><b><b>replace</b> <i>ITEM# TEXT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Replaces an existing task with new text.<br><br><b><b>archive</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Moves all completed tasks from <i>todo.txt</i> to <i>done.txt</i>.<br><br><b><b>listall</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all tasks in both <i>todo.txt</i> and <i>done.txt</i>.<br><br><b><b>report</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows a summary of tasks by project and context.<br><br><b><b>help</b> <i>[ACTION]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays general help or specific help for an action.<br><br>


title: DESCRIPTION
content:
<b>todo.sh</b> is a minimalist, command-line interface (CLI) todo list manager that operates directly on plain text files. It adheres to the <b>todo.txt</b> philosophy, where tasks are stored in a simple, human-readable text file (typically <i>todo.txt</i> and <i>done.txt</i>). This approach emphasizes flexibility, portability, and independence from complex database systems or proprietary formats.<br><br>Users can quickly add, list, prioritize, complete, and archive tasks using a straightforward set of commands. Its strength lies in its simplicity and reliance on standard Unix tools, making it highly scriptable and easy to integrate with other command-line workflows. It's often favored by developers, system administrators, and anyone who prefers a lightweight, keyboard-driven productivity tool. Its plain text format also ensures future compatibility and easy syncing across devices.


title: CAVEATS
content:
<b>todo.sh</b> is a shell script, typically depending on standard Unix utilities (e.g., <i>grep</i>, <i>sed</i>, <i>awk</i>).<br><br>It manages tasks in a plain text file, which means it doesn't offer advanced features like reminders, recurring tasks, or complex sorting beyond what can be scripted or manually managed. Its lack of a graphical user interface (GUI) might be a limitation for some users. While highly portable, ensuring consistent setup across different systems requires manual configuration of the script and its environment variables.


title: CONFIGURATION
content:
The behavior of <b>todo.sh</b> can be customized via a configuration file, typically located at <i>$HOME/.todo/config</i> or <i>/etc/todo/config</i>. This file allows setting default directories, custom actions, and various display options.


title: FILE FORMAT (TODO.TXT)
content:
Tasks are stored one per line in <i>todo.txt</i>. Completed tasks are moved to <i>done.txt</i>. Priorities are indicated by <i>(A)</i>, <i>(B)</i>, etc. at the beginning of a line. Projects start with <i>+project</i> and contexts with <i>@context</i>. This simple, human-readable format is central to its portability and extensibility.


title: HISTORY
content:
The <b>todo.sh</b> script is the command-line interface implementation of the <b>todo.txt</b> philosophy, which was conceived by Gina Trapani around 2006. The core idea was to create a simple, portable, and future-proof way to manage tasks using nothing more than a plain text file.<br><br>The project gained popularity in the GTD (Getting Things Done) community for its minimalist approach. While there isn't a single 'official' historical development for the <b>todo.sh</b> script itself (as it's often a community-maintained or self-adapted tool), its continuous development and widespread usage are rooted in the open-source spirit and the enduring appeal of the <b>todo.txt</b> format. It has been refined over the years by various contributors, adhering to the original principles of simplicity and plain text.


title: SEE ALSO
content:
<b>grep(1)</b>: For searching text patterns, similar to how <b>todo.sh</b> filters tasks., <b>sed(1)</b>: Stream editor, often used for text manipulation, which <b>todo.sh</b> might use internally., <b>awk(1)</b>: Pattern scanning and processing language, another common internal tool., <b>vim(1)</b> / <b>nano(1)</b> / <b>emacs(1)</b>: Text editors, directly usable for managing <i>todo.txt</i> files., Other CLI todo managers (e.g., <i>taskwarrior</i>, <i>pal</i>): Offer similar or more advanced task management from the command line.


title: SYNOPSIS
content:
<br><b>todoist</b> [<i>OPTIONS</i>] <i>COMMAND</i> [<i>ARGS</i>]...<br><br><b>Common Commands:</b><br> <i>add</i> &lt;<i>content</i>&gt; [<i>OPTIONS</i>] - Add a new task.<br> <i>list</i> [<i>OPTIONS</i>] - List tasks.<br> <i>show</i> &lt;<i>task_id</i>&gt; - Show details of a specific task.<br> <i>done</i> &lt;<i>task_id</i>&gt;... - Mark tasks as complete.<br> <i>edit</i> &lt;<i>task_id</i>&gt; [<i>OPTIONS</i>] - Edit an existing task.<br> <i>projects</i> - List all projects.<br> <i>labels</i> - List all labels.<br> <i>sync</i> - Synchronize local data with Todoist.


title: PARAMETERS
content:
<b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the installed version of todoist-cli and exit.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display help message for the todoist command or a specific subcommand.<br><br><b>--config <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an alternative path for the configuration file (default: ~/.config/todoist/config.ini).<br><br><b>--no-sync</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevent automatic synchronization with the Todoist API before executing the command.<br><br><b><content></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The text content for a new task when using the 'add' subcommand.<br><br><b>--project <name_or_id></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the project for a new or existing task by name or ID. Used with 'add' or 'edit'.<br><br><b>--due <string></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set a due date for a task (e.g., 'today', 'tomorrow', 'next monday', 'every 2 weeks'). Used with 'add' or 'edit'.<br><br><b>--label <name_or_id></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assign a label to a task by name or ID. Can be used multiple times. Used with 'add' or 'edit'.<br><br><b>--priority <number></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set task priority (1: highest, 4: lowest). Used with 'add' or 'edit'.<br><br><b>--filter <string></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filter tasks based on Todoist query syntax (e.g., 'today & p1'). Used with 'list'.<br><br><b>--show-completed</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Include completed tasks in the listing. Used with 'list'.<br><br>


title: DESCRIPTION
content:
The <i>todoist</i> command, primarily referring to the community-developed <br><i>todoist-cli</i> Python package, provides a powerful and lightweight command-line interface for interacting with the Todoist task management service directly from your Linux terminal. It allows users to manage their tasks, projects, labels, and filters without needing to open the web application or a dedicated desktop client. This tool is invaluable for users who prefer terminal-centric workflows, wish to integrate task management into scripts, or need quick access to their Todoist data. It supports core functionalities like adding new tasks, listing existing tasks with various filters, marking tasks as complete, and managing task properties such as due dates, priorities, and assigned projects. The <i>todoist</i> command communicates with the official Todoist API, requiring an API token for authentication, and it includes features for local data synchronization to enhance performance and offline access. Its modular design, based on a series of subcommands, makes it versatile for a wide range of task management operations.


title: CAVEATS
content:
The <i>todoist</i> command is typically implemented by the community-developed <br><i>todoist-cli</i> package, not an official Todoist product. It requires Python and <br><i>pip</i> for installation. Users must obtain a personal API token from their Todoist account settings for authentication, as the command interacts directly with the Todoist API. Be aware of Todoist API rate limits, though typical usage is unlikely to hit them. While comprehensive, this CLI client might not support every niche feature of the Todoist web or mobile applications, as its functionality is dependent on the public Todoist API and the developer's implementation.


title: AUTHENTICATION
content:
To use the <i>todoist</i> command, you need to set up authentication. Obtain your Todoist API token from your Todoist account settings (Integrations -> Developer). Then, run <b>todoist config</b> and paste your token when prompted. This token is stored in <br><i>~/.config/todoist/config.ini</i>.


title: SYNCHRONIZATION
content:
The command maintains a local cache of your Todoist data for faster access. Before most commands, it automatically performs a synchronization with the Todoist API. You can manually force a sync using the <b>todoist sync</b> command. To prevent automatic sync for a specific command, use the <br><i>--no-sync</i> global option.


title: HISTORY
content:
The <i>todoist-cli</i>, which is the most common implementation of the <i>todoist</i> command on Linux, was primarily developed by Sean Schaaf (schaabs) and released as an open-source project on GitHub. Its development began in the mid-to-late 2010s, providing a much-requested command-line interface for Todoist users. Since its inception, it has seen continuous development, adapting to changes in the Todoist API and incorporating features based on community feedback and contributions. It has become a de facto standard for command-line Todoist interaction due to its robustness and active maintenance.


title: SYNOPSIS
content:
<b>todoman</b> <i>[GLOBAL OPTIONS] COMMAND [COMMAND OPTIONS] [ARGUMENTS]</i><br><br>Common Commands:<br><b>todoman</b> <b>list</b> <i>[OPTIONS] [FILTER]</i><br><b>todoman</b> <b>add</b> <i>[OPTIONS] [DESCRIPTION]</i><br><b>todoman</b> <b>show</b> <i>&lt;UID&gt;</i><br><b>todoman</b> <b>edit</b> <i>&lt;UID&gt;</i><br><b>todoman</b> <b>done</b> <i>&lt;UID&gt;...</i><br><b>todoman</b> <b>delete</b> <i>&lt;UID&gt;...</i><br><b>todoman</b> <b>priority</b> <i>&lt;UID&gt; &lt;PRIORITY&gt;</i>


title: PARAMETERS
content:
<b><b>Global Options:</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;These options affect the overall behavior of the <b>todoman</b> command, regardless of the subcommand used.<br><br><b><b>--config</b> <i>&lt;FILE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an alternative configuration file to use instead of the default.<br><br><b><b>--color</b> <i>{always,auto,never}</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Control whether the output uses ANSI color codes. 'auto' enables colors only if the output is a TTY.<br><br><b><b>--humanize</b> <i>{yes,no}</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Toggle human-readable output for dates and times (e.g., 'tomorrow', '3 days ago').<br><br><b><b>--status</b> <i>{ANY,NEEDS-ACTION,COMPLETED,CANCELLED}</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filter todos by their completion status across all commands that list todos.<br><br><b><b>Subcommands & Their Common Options:</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Each subcommand performs a specific action. Many subcommands accept specific options to modify their behavior.<br><br><b><b>list</b> <i>[OPTIONS] [FILTER]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists existing todos. Filters can be applied using project names, contexts, or keywords found in the description. Common options include <b>--sort</b> <i>FIELD</i> (e.g., <i>due</i>, <i>priority</i>), <b>--due</b> <i>DATE</i> (filter by due date), <b>--project</b> <i>PROJECT</i>, <b>--context</b> <i>CONTEXT</i>, or <b>--urgent</b> (only show urgent todos).<br><br><b><b>add</b> <i>[OPTIONS] [DESCRIPTION]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a new todo. The description can be provided directly or interactively. Options allow setting properties like <b>--due</b> <i>DATE</i>, <b>--priority</b> <i>PRIORITY</i> (e.g., A, B, C), <b>--start</b> <i>DATE</i>, <b>--project</b> <i>PROJECT</i>, and <b>--context</b> <i>CONTEXT</i>.<br><br><b><b>show</b> <i>&lt;UID&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the full details of a specific todo, identified by its unique ID (UID).<br><br><b><b>edit</b> <i>&lt;UID&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens the specified todo in a text editor for modification. This command requires an editor to be configured via the <i>VISUAL</i> or <i>EDITOR</i> environment variables.<br><br><b><b>done</b> <i>&lt;UID&gt;...</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Marks one or more todos, identified by their UIDs, as completed. Multiple UIDs can be provided separated by spaces.<br><br><b><b>delete</b> <i>&lt;UID&gt;...</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deletes one or more todos specified by their UIDs. This action is usually permanent.<br><br><b><b>priority</b> <i>&lt;UID&gt; &lt;PRIORITY&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets or changes the priority of a todo. Priorities are typically single uppercase letters (e.g., A, B, C), where 'A' is the highest.<br><br><b><b>UID (Unique ID):</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A short, unique identifier assigned to each todo within a specific todo directory. It's used to reference individual todos for commands like <b>show</b>, <b>edit</b>, <b>done</b>, and <b>delete</b>.<br><br>


title: DESCRIPTION
content:
<b>todoman</b> is a simple, lightweight, and standard-compliant command-line task manager. It allows users to manage their todo lists directly from the terminal. It supports two primary formats: the plain-text <i>todo.txt</i> format and the more structured <i>iCalendar</i> (specifically VTODO components) format, making it compatible with various calendaring and syncing tools.<br><br>Key features include adding, listing, editing, deleting, and completing tasks. Users can filter tasks by projects, contexts, due dates, and status, as well as prioritize them. <b>todoman</b> is designed to be highly customizable and often integrates seamlessly with synchronization tools like <i>vdirsyncer</i> to keep tasks in sync with CalDAV servers or other devices. Its focus is on efficiency and adherence to open standards, providing a robust yet straightforward solution for personal task management.


title: CAVEATS
content:
<ul><li><b>Configuration Dependency</b>: <b>todoman</b> relies heavily on a configuration file (typically <i>~/.config/todoman/config.py</i>) for defining task directories, default behaviors, and display settings. Without proper configuration, the command might not function as expected.</li><li><b>External Editor Requirement</b>: The <b>edit</b> command requires an external text editor to be configured via the <i>VISUAL</i> or <i>EDITOR</i> environment variables. If not set, this functionality will be limited.</li><li><b>No Built-in Sync</b>: <b>todoman</b> itself does not provide syncing capabilities. It is designed to work in conjunction with external tools like <i>vdirsyncer</i> for synchronizing tasks with CalDAV servers or other devices.</li><li><b>Local UID Scope</b>: The UIDs (Unique IDs) are often short and unique only within the context of the currently specified todo directory, not globally unique across all tasks or systems.</li></ul>


title: CONFIGURATION FILE
content:
<b>todoman</b> uses a Python-based configuration file, typically located at <i>~/.config/todoman/config.py</i>. This file allows users to specify task directories (where todo files are stored), default filters for listing, and various display options. Advanced users often customize this file extensively to tailor the tool to their specific workflow.


title: ICALENDAR (VTODO) SUPPORT
content:
A key strength of <b>todoman</b> is its robust support for the <i>iCalendar</i> (VTODO) component standard. This means it can interact seamlessly with a wide range of CalDAV servers and other calendar applications that adhere to this open standard. This makes <b>todoman</b> a powerful tool for users who want to manage tasks across multiple devices or services while keeping their data in an interoperable format.


title: HISTORY
content:
<b>todoman</b> was created to provide a simpler, more standards-compliant alternative to other command-line todo managers. Its development focuses on adhering to <i>RFC 5545</i> (iCalendar) for robust interoperability. It gained popularity among users who prefer minimalist CLI tools and those who sync their data using <i>vdirsyncer</i> for decentralized task management. It is actively maintained and forms a core part of the larger <i>vdirsyncer</i> ecosystem, emphasizing plain-text and open-standard approaches to personal information management.


title: PARAMETERS
content:
<b><b>-a</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists <i>all</i> entries found in the <b>terminfo</b> database, including those with incomplete capabilities, not just fully capable ones.<br><br><b><b>-s</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides a <i>short list</i>, showing only the first alias for each terminal entry. This makes the output more concise and easier to read.<br><br><b><b>-u</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a <i>usage summary</i> for the command, providing information on its syntax and available options.<br><br><b><b>[dir...]</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies one or more <i>directory paths</i> to search for <b>terminfo</b> entries. These directories are searched in addition to the standard system paths, allowing for custom or temporary <b>terminfo</b> definitions.<br><br>


title: DESCRIPTION
content:
The <i>toe</i> command, part of the <b>ncurses</b> library, is a utility designed to list the available <i>terminal descriptions</i>, also known as <b>terminfo entries</b>, installed on a Linux system. These entries are crucial for text-based applications to correctly interact with various terminal types by describing their capabilities (e.g., cursor movement, color support). <i>toe</i> helps system administrators and developers identify which terminal types are supported and can be invaluable for debugging terminal-related issues or configuring the <I>TERM</I> environment variable.<br><br>It provides a snapshot of the terminal environments that the system understands, drawing information from default system paths or user-specified directories. While not a daily command for most users, its role in managing terminal capabilities is fundamental for consistent application behavior across diverse terminal emulators and physical terminals.


title: CAVEATS
content:
The <i>toe</i> command is distributed as part of the <b>ncurses-bin</b> or similar package and might not be pre-installed by default on all minimal Linux distributions.<br>Its primary use case is for developers and system administrators debugging terminal-related issues or managing <b>terminfo</b> databases, rather than general user interaction.<br>Without options, the output can be very extensive, listing hundreds of terminal types.


title: TERMINFO DATABASE EXPLAINED
content:
The <b>terminfo</b> database is a sophisticated system that stores detailed descriptions of various character-cell terminals. It enables screen-oriented applications to function correctly by providing machine-readable information about a terminal's capabilities, such as how to move the cursor, change colors, or interpret special key sequences. Each entry is a compiled binary file representing a specific terminal type (e.g., <i>xterm-256color</i>, <i>vt220</i>).


title: ROLE OF THE TERM ENVIRONMENT VARIABLE
content:
Most applications that interact with the terminal rely on the <I>TERM</I> environment variable to determine the current terminal's type. For instance, if <I>TERM</I> is set to <i>xterm</i>, applications will look up the <i>xterm</i> entry in the <b>terminfo</b> database to understand the terminal's features. <i>toe</i> is useful for verifying which <I>TERM</I> values correspond to available <b>terminfo</b> descriptions on a system.


title: HISTORY
content:
The <i>toe</i> command is an integral part of the <b>ncurses</b> project, which is a free software implementation of the venerable <b>curses</b> library, originally developed in the 1970s. <b>ncurses</b> itself emerged as a replacement for System V Release 4.0 curses. <i>toe</i> likely originated as a practical tool to inspect and verify the installed terminal capabilities as the <b>terminfo</b> database became the standard, superseding the older <b>termcap</b> system. Its evolution is closely linked to the development and maintenance of <b>ncurses</b> and the continuous need for robust terminal description management tools.


title: PARAMETERS
content:
<b><b>-f</b> <I>pattern</I>, <b>--filter</b> <I>pattern</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes lines that match the specified <I>pattern</I>. Supports regular expressions.<br><br><b><b>-e</b> <I>pattern</I>, <b>--exclude</b> <I>pattern</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Excludes lines that match the specified <I>pattern</I>. Supports regular expressions.<br><br><b><b>-p</b> <I>format</I>, <b>--prettify</b> <I>format</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reformats the output based on the specified <I>format</I>, e.g., 'json', 'csv', or custom templates.<br><br><b><b>-i</b>, <b>--ignore-case</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs case-insensitive matching for filters and exclusions.<br><br><b><b>-c</b> <I>color</I>, <b>--color</b> <I>color</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Highlights matched patterns in the specified <I>color</I> (e.g., 'red', 'green', 'blue').<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message and exits.<br><br>


title: DESCRIPTION
content:
The 'tofu' command is a <I>hypothetical</I> utility designed to simplify and make raw text output more digestible. It would act as a versatile filter and formatter for standard input or files, allowing users to extract specific information, reformat lines, or highlight patterns. Imagine piping complex log files or verbose command outputs through <I>tofu</I> to get a clean, concise summary. Its primary goal is to transform overwhelming data into an easily understandable format, much like tofu can be prepared in various simple, palatable ways. While 'tofu' is <I>not</I> a standard Linux utility, this description illustrates its potential utility in data analysis and system administration, offering a flexible way to manage information overload. It aims to reduce cognitive load by presenting only relevant data, formatted for optimal readability, making debugging, monitoring, and reporting tasks more efficient. Users could define rules for inclusion, exclusion, reordering, or color-coding, adapting <I>tofu</I> to diverse analytical needs without complex scripting.


title: CAVEATS
content:
Important: The 'tofu' command is <I>not</I> a standard utility found in common Linux distributions or manual pages. This analysis describes a <B>hypothetical</B> command designed to illustrate potential functionality for data filtering and formatting on the command line. As such, it does not exist as a pre-installed executable and cannot be run.


title: CONCEPTUAL USAGE EXAMPLES
content:
Although hypothetical, <I>tofu</I> would ideally be used by piping output from other commands or processing log files directly. The following examples illustrate its potential application:<br><br><b>Example 1: Filter system logs for errors</b><br><I>tail -f /var/log/syslog | tofu -f 'ERROR|FAIL' -c red</I><br>This would continuously show only lines containing 'ERROR' or 'FAIL' from the syslog, with those patterns highlighted in red.<br><br><b>Example 2: Prettify and simplify API JSON output</b><br><I>curl -s https://api.example.com/data | tofu --prettify json -e 'debug_info'</I><br>This would take raw JSON output from an API call, format it nicely for readability, and exclude any lines containing 'debug_info'.


title: HISTORY
content:
As a hypothetical command, 'tofu' has no real development history. Its conceptual design is inspired by the ongoing need for more intuitive and flexible text processing tools beyond the traditional <I>grep</I>, <I>awk</I>, and <I>sed</I>. It aims for a more user-friendly interface for common data transformation tasks in system administration and data analysis workflows, representing a potential evolution in how users interact with raw text data on the command line.


title: PARAMETERS
content:
<b>[NAME]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Optional) The name of a specific output value to retrieve. If omitted, all output values will be displayed.<br><br><b>-json</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output the result in JSON format, suitable for programmatic parsing.<br><br><b>-state=PATH</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the state file. Defaults to "tofu.tfstate" in the current working directory if not specified.<br><br><b>-no-color</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable colored output.<br><br><b>-compact</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display output in a compact form, typically used with single output values.<br><br><b>-raw</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display raw output, without any formatting or quotes, useful for pipes.<br><br>


title: DESCRIPTION
content:
The <i>tofu-output</i> command is designed to extract and display the output values defined within a <I>tofu</I> configuration's state file. In the context of Infrastructure as Code (IaC) using <I>tofu</I> (an open-source project similar to Terraform), "outputs" are named values that are exposed by a root module. These outputs can represent anything from public IP addresses of deployed instances, database connection strings, S3 bucket names, or any other piece of information generated by the infrastructure deployment that needs to be consumed by other systems, modules, or users.<br><br>This command is crucial for interacting with deployed infrastructure, enabling scripting, automation, or simply providing a summary of important deployment artifacts. It reads the current state (either locally or from a remote backend) and presents the values in a user-friendly format, or in a machine-readable JSON format for programmatic use.


title: CAVEATS
content:
<b>Sensitive Data:</b> Output values can sometimes contain sensitive information (e.g., passwords, API keys). While <i>tofu</i> attempts to redact sensitive outputs in logs, direct retrieval via <i>tofu-output</i> will expose the raw values. Always handle outputs containing sensitive data with extreme care.<br><b>State File Dependency:</b> The command relies entirely on the integrity and accessibility of the <i>tofu</i> state file. If the state file is corrupted, inaccessible, or out of sync with the actual infrastructure, the displayed outputs may be inaccurate or unavailable.<br><b>Uninitialized Backend:</b> If a remote backend is configured but not initialized, <i>tofu-output</i> may fail to retrieve the state, requiring an initial `tofu init` command.<br><b>No Output Defined:</b> If no output values are defined in the configuration, or if the specified `NAME` does not correspond to an existing output, the command will return an empty result or an error.


title: USAGE EXAMPLES
content:
<I>Retrieve all outputs:</I><br>`tofu-output`<br><br><I>Retrieve a specific output named "web_app_url":</I><br>`tofu-output web_app_url`<br><br><I>Retrieve a specific output in JSON format:</I><br>`tofu-output -json database_connection_string`<br><br><I>Pipe raw output to another command:</I><br>`tofu-output -raw instance_ip | ssh -i mykey.pem ec2-user@$(cat)`


title: OUTPUTTING SENSITIVE INFORMATION
content:
While `sensitive = true` can be set for an output in the <I>tofu</I> configuration to prevent its display in plan/apply logs, it does not prevent `tofu-output` from displaying the value directly. Users must be aware of this and ensure appropriate access controls are in place for systems that can execute `tofu-output` or store its results.


title: HISTORY
content:
The concept of explicitly defined outputs emerged early in the development of Infrastructure as Code (IaC) tools like Terraform, which <I>tofu</I> is a direct successor or alternative to. As IaC matured, the need to programmatically access information about deployed resources became paramount for integration with CI/CD pipelines, monitoring systems, and other automation tools. The `output` command, therefore, became a core utility, allowing users to extract key deployment artifacts without directly querying the cloud provider APIs. Its design evolved to support various formats (e.g., human-readable, JSON) to cater to both manual inspection and automated consumption. The "tofu-output" command represents this fundamental utility within the <I>tofu</I> ecosystem, emphasizing the importance of discoverable and reusable infrastructure data.


title: PARAMETERS
content:
<b><b>DIR</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to a directory containing OpenTofu configuration files. Defaults to the current working directory.<br><br><b><b>PLAN_FILE</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to a previously saved plan file (generated with <b>-out</b>) that should be inspected or applied later.<br><br><b><b>-compact-warnings</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show warnings in a more concise form, suppressing details for common warnings.<br><br><b><b>-destroy</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a plan to destroy all OpenTofu-managed infrastructure. <i>Use with extreme caution.</i><br><br><b><b>-detail-exitcode</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Return a detailed exit code: 0 for no changes, 1 for error, 2 for changes detected (when used without <b>-out</b>).<br><br><b><b>-input=true|false</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ask for input if variables are not otherwise satisfied. Defaults to <b>true</b> in interactive sessions.<br><br><b><b>-json</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output the plan in a machine-readable JSON format, useful for programmatic analysis.<br><br><b><b>-lock=true|false</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lock the state file during the planning operation to prevent concurrent modifications. Defaults to <b>true</b>.<br><br><b><b>-lock-timeout=DURATION</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Duration to retry acquiring a state lock. Format like '30s' or '5m'.<br><br><b><b>-no-color</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable colored output from the plan, useful for logging or non-TTY environments.<br><br><b><b>-out=PATH</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Save the generated execution plan to a specified file path. This plan can then be applied with <b>tofu apply PATH</b>.<br><br><b><b>-parallelism=N</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limit the number of concurrent operations OpenTofu can perform while planning.<br><br><b><b>-refresh=true|false</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Update the state file with the current real-world infrastructure before planning. Defaults to <b>true</b>.<br><br><b><b>-state=PATH</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the state file to use for the plan. Defaults to <b>terraform.tfstate</b> in the working directory.<br><br><b><b>-target=RESOURCE</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Target a specific resource or module for planning. Can be specified multiple times. <i>Use with caution as it can lead to state drift.</i><br><br><b><b>-var 'key=value'</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set a variable value directly. Can be specified multiple times.<br><br><b><b>-var-file=PATH</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Load variable definitions from a specified file. Can be specified multiple times.<br><br>


title: DESCRIPTION
content:
The command <b>tofu plan</b> is a core component of <i>OpenTofu</i>, an open-source infrastructure as code (IaC) tool. It creates an <i>execution plan</i>, which outlines the actions OpenTofu will take to reconcile your infrastructure with the desired state defined in your <b>.tf</b> configuration files.<br><br>Before applying any changes, <b>tofu plan</b> performs a 'dry run' by comparing the current state of your managed infrastructure (stored in the state file) against your configuration. The output details exactly which resources will be <b>added</b> (<B>+</B>), <b>changed</b> (<B>~</B>), or <b>destroyed</b> (<B>-</B>), along with specific attribute modifications.<br><br>This command is crucial for reviewing potential infrastructure changes, preventing unintended modifications, and ensuring that the proposed operations align with your expectations. It does <b>not</b> modify any real infrastructure; its purpose is solely to generate and display the proposed changes. The generated plan can optionally be saved to a file for later application using <b>tofu apply</b>.


title: CAVEATS
content:
<b>Not a Standard Linux Command:</b> <b>tofu plan</b> is a subcommand of the <b>tofu</b> executable, which is an application-specific command for <i>OpenTofu</i>, not a general-purpose Linux utility like <b>ls</b> or <b>grep</b>.<br><br><b>Requires Initialization:</b> The working directory must be initialized with <b>tofu init</b> before running <b>tofu plan</b>.<br><br><b>State Drift:</b> A saved plan reflects the state at the time of its creation. If external changes occur to your infrastructure or configuration between plan generation and application, the saved plan might become outdated, leading to unexpected results.<br><br><b>'-destroy' Irreversible:</b> The <b>-destroy</b> option generates a plan to tear down all infrastructure. Applying such a plan is largely irreversible and should be used with extreme care.


title: PLAN OUTPUT INTERPRETATION
content:
The output of <b>tofu plan</b> uses specific symbols to indicate actions: <b>+</b> for creation, <b>~</b> for in-place updates, and <b>-</b> for destruction. Detailed descriptions for attribute changes, such as <i>(forces replacement)</i> or <i>(changes in-place)</i>, are also provided to give a clear understanding of the impact of each change.


title: IDEMPOTENCY
content:
One of OpenTofu's core principles is idempotency. Running <b>tofu plan</b> multiple times with the same configuration against the same state should produce an identical plan (or no changes) as long as no external modifications occur to the infrastructure. This consistency ensures predictable outcomes.


title: CI/CD INTEGRATION
content:
<b>tofu plan</b> is frequently integrated into Continuous Integration/Continuous Delivery (CI/CD) pipelines. This allows automated 'dry runs' of infrastructure changes on every code commit, providing early feedback and requiring explicit approval before changes are applied to production environments, thus enhancing reliability and security.


title: HISTORY
content:
The <b>plan</b> command has been a foundational element of <i>Terraform</i> since its inception, providing a critical preview step in Infrastructure as Code (IaC) workflows. <i>OpenTofu</i> emerged in August 2023 as a community-driven, open-source fork of Terraform, specifically maintaining the Apache 2.0 license after HashiCorp changed Terraform's license. The <b>tofu plan</b> command in OpenTofu retains full feature and behavioral parity with its Terraform counterpart, ensuring a seamless transition and continuity for users. Its development continues under the Linux Foundation's governance, focusing on stability, community contributions, and vendor neutrality.


title: SYNOPSIS
content:
<code><B>togglesebool</B> [<i>OPTION</i>...] <<i>BOOLEAN_NAME</i>> [<i>STATE</i>]</code><br><code><B>togglesebool</B> [<i>OPTION</i>...] -l | --list</code>


title: PARAMETERS
content:
<b><I>BOOLEAN_NAME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the SELinux boolean to toggle. This is a mandatory argument unless listing all booleans.<br><br><b><I>STATE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The desired state for the boolean: <I>on</I>, <I>off</I>, <I>true</I>, <I>false</I>, <I>1</I>, or <I>0</I>. If omitted, the command would conceptually toggle the current state of the boolean.<br><br><b>-P, --persistent</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Make the change persistent across reboots by writing the new state to the SELinux policy configuration file.<br><br><b>-l, --list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;List all available SELinux booleans along with their current and default states.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br>


title: DESCRIPTION
content:
The <b>togglesebool</b> command is a <I>hypothetical</I> utility conceptualized to simplify the management of SELinux booleans. SELinux booleans are configurable options within the SELinux policy that allow administrators to enable or disable specific SELinux features or behaviors without recompiling the entire policy. If this command existed, it would provide a straightforward way to change the state of these booleans, either temporarily for the current session or persistently across reboots. This would involve interacting with the SELinux kernel module and potentially updating the policy on disk. Its purpose would be to abstract the complexities of direct SELinux policy manipulation, offering a user-friendly interface for common administrative tasks related to security contexts, thereby streamlining the process of adjusting system security behavior.


title: CAVEATS
content:
It is important to note that <B>togglesebool</B> is a <I>hypothetical</I> command and does not exist as a standard Linux utility. Users should instead rely on official SELinux tools like <B>setsebool</B> and <B>getsebool</B> for managing SELinux booleans. Attempting to execute <B>togglesebool</B> on a Linux system will result in a 'command not found' error.


title: SECURITY IMPLICATIONS
content:
Modifying SELinux booleans can have significant security implications. Incorrectly enabling or disabling booleans might weaken the system's security posture or inadvertently break applications and services. Always understand the purpose and impact of an SELinux boolean before changing its state.


title: HISTORY
content:
As a hypothetical command, <B>togglesebool</B> has no real history of development or usage. Its name is derived from 'toggle' and 'sebool' (short for SELinux boolean), reflecting the desired functionality of enabling or disabling specific SELinux policy rules. The concept behind such a command aims to simplify the interface for SELinux boolean management, which is currently handled by existing, more granular tools.


title: PARAMETERS
content:
<b><b>-f</b>, <b>--font</b> <i>&lt;fontfile&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the font file to use. Fonts are usually found in <i>/usr/share/toilet/fonts/</i> or <i>/usr/share/figlet/fonts/</i>.<br><br><b><b>-F</b>, <b>--filter</b> <i>&lt;filters&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies one or more special effects to the output. Common filters include <i>metal</i>, <i>rainbow</i>, <i>crop</i>, <i>flip</i>, <i>flop</i>, and <i>gay</i> (a rainbow effect).<br><br><b><b>-E</b>, <b>--export</b> <i>&lt;format&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exports the output in a specified format. Supported formats include <i>html</i>, <i>ansi</i>, <i>utf8</i>, <i>svg</i>, <i>tga</i>, <i>irc</i>, and <i>json</i>.<br><br><b><b>-o</b>, <b>--output</b> <i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the generated output to the specified file instead of printing to standard output.<br><br><b><b>-W</b>, <b>--width</b> <i>&lt;width&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum width of the output in characters. This is useful for fitting text within specific terminal dimensions.<br><br><b><b>-C</b>, <b>--color</b> <i>&lt;colors&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines custom colors for the output. Can be a single color name, RGB values (e.g., <i>r,g,b</i>), or a comma-separated list for gradients.<br><br><b><b>-t</b>, <b>--truecolor</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables 24-bit true color output, allowing for a much wider range of colors if the terminal supports it.<br><br><b><b>-L</b>, <b>--loop</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables an animation loop for dynamic filters like <i>rain</i>, continuously updating the display.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message with available options and exits.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the version information of the <b>toilet</b> command and exits.<br><br>


title: DESCRIPTION
content:
The <b>toilet</b> command (TOIlet - The Other Internet Text) is a powerful and versatile console utility designed to render large, stylized text using characters. It serves as a feature-rich successor to the popular <b>figlet</b> command, significantly expanding upon its capabilities.<br><br>Unlike <b>figlet</b>, <b>toilet</b> natively supports a wide array of features including different colors (including 24-bit true colors), various artistic filters (such as <i>metal</i>, <i>rainbow</i>, <i>crop</i>), and multiple export formats (like HTML, SVG, ANSI, and UTF-8). It can utilize both standard fonts and existing Figlet fonts, offering immense flexibility for text art generation.<br><br>Commonly used for creating impressive terminal banners, artistic text displays, or decorative output in scripts, <b>toilet</b> transforms plain text into visually striking ASCII or Unicode art, making it an excellent tool for enhancing command-line interfaces and creative projects.


title: CAVEATS
content:
Output quality, especially color and special effects, heavily depends on the capabilities of the terminal emulator being used. Older terminals or those with limited color support may not display <b>toilet</b>'s full range of features accurately. Complex filters or very large text inputs can be resource-intensive, potentially causing delays or high CPU usage.


title: FONTS AND FILTERS
content:
<b>toilet</b>'s strength lies in its extensive collection of fonts and filters. Users can discover available fonts by listing files in <i>/usr/share/toilet/fonts/</i> and experiment with different filter combinations to achieve unique visual effects. Running <i>toilet --filter list</i> will show all available filters.


title: HISTORY
content:
<b>toilet</b> was created as a modern and more feature-rich alternative to the traditional <b>figlet</b> program. While <b>figlet</b> popularized ASCII art text generation, it lacked support for colors, advanced filters, and diverse output formats. <b>toilet</b> was developed to address these limitations, providing native capabilities for colorful and dynamic text rendering, making it a popular choice for contemporary terminal art and scripting.


title: DESCRIPTION
content:
The command <i>toipe</i> does not appear to be a standard or commonly recognized utility in most mainstream Linux distributions. It is possible that this is a typo, an alias defined in a user's shell configuration, or a custom script developed for a specific environment. Without further context or an installation of a specialized package, detailed information regarding its functionality, options, and usage cannot be provided.


title: CAVEATS
content:
As <i>toipe</i> is not a standard Linux command, attempting to execute it on a typical system will likely result in a 'command not found' error. Users should verify if it's an alias, a typo for another command (e.g., 'type', 'top'), or if it belongs to a specific, non-standard software package.


title: POSSIBLE ALTERNATIVES/TYPO CONSIDERATIONS
content:
If you intended to inquire about a command related to displaying type information, consider <i><b>type</b>(1)</i>. For process monitoring, <i><b>top</b>(1)</i> or <i><b>htop</b>(1)</i> are common. Please double-check the spelling of the command you are looking for.


title: HISTORY
content:
No historical development or usage information is available for <i>toipe</i> as it is not a standard Linux command.


title: SYNOPSIS
content:
<b>tokei</b> [<I>OPTIONS</I>] [<I>PATH</I>...]<br><b>tokei</b> <I>diff</I> [<I>OPTIONS</I>] [<I>REF1</I>] [<I>REF2</I>]


title: PARAMETERS
content:
<b>-l, --languages <I>LANG...</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filter results to include only specified programming languages.<br><br><b>-e, --exclude <I>EXCLUDE...</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exclude files or directories matching the given patterns.<br><br><b>-f, --files <I>FILES...</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only count statistics for the specified file paths.<br><br><b>-t, --type <I>TYPE...</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filter statistics by line type: <i>code</i>, <i>comment</i>, or <i>blank</i>.<br><br><b>-o, --output <I>FORMAT</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the output format (e.g., <i>json</i>, <i>yaml</i>, <i>csv</i>, <i>markdown</i>, <i>plain</i>).<br><br><b>-s, --sort <I>SORT_ORDER</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sort the output by a specific column or order (e.g., <i>files</i>, <i>lines</i>, <i>name</i>).<br><br><b>--hidden</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Include hidden files and directories in the analysis.<br><br><b>--no-ignore</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not respect <i>.gitignore</i> files.<br><br><b>--no-ignore-vcs</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not respect version control system (VCS) ignore files (e.g., <i>.git/info/exclude</i>).<br><br><b>--git</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force <b>tokei</b> to only count files tracked by Git.<br><br><b>--color <I>WHEN</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Control color output (e.g., <i>always</i>, <i>auto</i>, <i>never</i>).<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output, showing more details during processing.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display help message and exit.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display version information and exit.<br><br>


title: DESCRIPTION
content:
<b>tokei</b> is a highly efficient and versatile command-line program, written in Rust, designed for quickly counting lines of code, comments, blank lines, and files across a multitude of programming languages.<br><br>It offers detailed statistics for over 150 languages, providing insights into the size and composition of a codebase. Users can generate reports in various formats, including plain text, JSON, YAML, CSV, and Markdown, facilitating integration with other tools or documentation.<br><br><b>tokei</b> supports advanced filtering to include or exclude specific files, directories, or languages, and can even analyze code changes between Git revisions. Its multi-threaded architecture ensures exceptional speed, making it an ideal choice for analyzing large-scale projects where performance is crucial. It helps developers, project managers, and quality assurance teams gain a comprehensive overview of their software projects.


title: CAVEATS
content:
<b>tokei</b> is not a standard pre-installed Linux command; it needs to be installed separately, typically via a package manager (like <i>cargo</i>, <i>brew</i>, or specific distribution packages) or by compiling from source.<br><br>While highly optimized, performance can still be influenced by extremely large codebases on systems with limited resources, especially when parsing numerous files with complex language structures. It may also occasionally misidentify or lack support for very obscure or highly domain-specific language dialects.


title: THE 'DIFF' SUBCOMMAND
content:
The <b>tokei diff</b> subcommand allows users to analyze the differences in lines of code, comments, and blank lines between two Git revisions or branches. This is particularly useful for tracking codebase evolution, assessing the impact of changes, or reviewing pull requests. It can compare the current working directory with a specific commit, or two different commits within the repository.<br><br>Usage examples include <b>tokei diff HEAD~1 HEAD</b> to see changes from the previous commit, or <b>tokei diff main develop</b> to compare two branches.


title: HISTORY
content:
<b>tokei</b> was created by <i>XAMPPRocky</i> and first released around 2018. It was developed in <i>Rust</i> with a primary focus on speed and accuracy, aiming to be a faster and more feature-rich alternative to existing code counters like <b>cloc</b>. Its multi-threaded design and broad language support quickly contributed to its popularity among developers. Development is ongoing, with regular updates introducing new features, language support, and performance improvements.


title: SYNOPSIS
content:
<b>tomb</b> <I>action</I> [<I>options</I>] [<I>tomb_file</I>] [<I>key_file</I>]<br><b>tomb</b> <I>list</I><br><b>tomb</b> <I>-h</I> | <I>--help</I><br><b>tomb</b> <I>-v</I> | <I>--version</I>


title: PARAMETERS
content:
<b><b>dig</b> <I>tomb_file</I> [<I>key_file</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a new encrypted tomb file and its associated key file.<br><br><b><b>open</b> <I>tomb_file</I> [<I>key_file</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens an existing tomb and mounts it as a directory, typically at <I>/mnt/.tomb/&lt;tomb_name&gt;</I>.<br><br><b><b>close</b> <I>tomb_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Closes (unmounts) an opened tomb, making its contents inaccessible.<br><br><b><b>bury</b> <I>key_file</I> <I>carrier_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Hides the <I>key_file</I> inside a <I>carrier_file</I> (e.g., an image) using steganography.<br><br><b><b>forge</b> <I>tomb_file</I> [<I>key_file</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a new key file for an existing tomb, prompting for the existing tomb's passphrase.<br><br><b><b>graft</b> <I>tomb_file</I> <I>new_key_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attaches a <I>new_key_file</I> to an existing tomb, allowing it to be opened with this new key.<br><br><b><b>lock</b> <I>tomb_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Locks an open tomb, preventing accidental closure. Requires <b>unlock</b> to close.<br><br><b><b>unlock</b> <I>tomb_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Unlocks a previously locked tomb, allowing it to be closed.<br><br><b><b>chmould</b> <I>tomb_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows changing properties of a tomb, such as its size or underlying cryptographic settings. Can be used to resize.<br><br><b><b>resize</b> <I>tomb_file</I> [<I>new_size</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Resizes an existing tomb to a <I>new_size</I> (e.g., 100M, 2G). Requires the tomb to be closed.<br><br><b><b>gkeys</b> <I>tomb_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a new set of keys for an existing tomb, replacing the old ones.<br><br><b><b>list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all currently open <i>tomb</i> volumes on the system.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief help message for the <i>tomb</i> command or a specific action.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the current version of the <i>Tomb</i> tool.<br><br><b><b>-s</b> <I>size</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the size for <b>dig</b> or <b>chmould</b> operations (e.g., <I>500M</I>, <I>2G</I>).<br><br><b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces an operation, overriding prompts or warnings that might otherwise stop it.<br><br><b><b>-n</b>, <b>--no-password</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Proceeds without requiring a password prompt for key generation or usage (use with extreme caution).<br><br><b><b>-k</b> <I>key_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly specifies the key file to use for an operation, if not the default.<br><br><b><b>-c</b> <I>config_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses an alternative configuration file instead of the default <i>~/.tomb/config</i>.<br><br>


title: DESCRIPTION
content:
<i>Tomb</i> is a free and open source command-line tool that allows users to create and manage encrypted volumes, also known as "tombs". It leverages Linux's <b>dm-crypt</b> and <b>cryptsetup</b> to provide strong encryption for sensitive data. A tomb is essentially an encrypted file that acts as a secure container. Users can <b>dig</b> a new tomb, <b>open</b> it to access its contents as a mounted directory, and <b>close</b> it to unmount and secure the data. <i>Tomb</i> is designed with plausible deniability in mind, allowing for hidden tombs where keys can be buried within other files using steganography, or by using a key file that is itself a GPG encrypted message. It streamlines the complex process of setting up and managing encrypted file systems, making it accessible for protecting privacy and sensitive information. Its features include resizing tombs, key management, and secure deletion of keys.


title: CAVEATS
content:
<i>Tomb</i> operations, especially opening and closing, typically require <b>root</b> privileges. <br>The security of a tomb depends entirely on the strength of its passphrase and the secrecy of its key file. <br>While <i>Tomb</i> offers features for plausible deniability (e.g., hidden keys), these are obfuscation techniques and not foolproof against determined forensic analysis. <br>Improper usage or system crashes during operations can lead to data loss or corruption if not handled carefully.


title: PLAUSIBLE DENIABILITY
content:
<i>Tomb</i> incorporates features for plausible deniability, allowing users to conceal the existence of encrypted volumes. This includes the ability to embed key files within innocuous carrier files (like images) using steganography, and support for multiple keys, where one key might reveal a decoy volume while another reveals the true sensitive data.


title: DEPENDENCIES
content:
<i>Tomb</i> relies on several core Linux utilities and kernel modules. Essential dependencies include <b>cryptsetup</b> for disk encryption, <b>dm-crypt</b> kernel module, <b>losetup</b> for loop devices, and <b>mount</b> for filesystem operations. Optional dependencies for advanced features include <b>gnupg</b> for key encryption and <b>steg_hide</b> (from <I>steghide</I> package) for burying keys in other files.


title: DEFAULT MOUNT POINT AND SWAP PROTECTION
content:
By default, <i>Tomb</i> volumes are mounted under <I>/mnt/.tomb/</I> in a directory named after the tomb file. To enhance security and prevent sensitive data from being written to unencrypted swap space, <i>Tomb</i> automatically creates and uses a temporary encrypted swap file inside the opened tomb itself, mitigating potential data leaks.


title: HISTORY
content:
<i>Tomb</i> was originally created by Jaromil, a developer associated with the Dyne.org Foundation, known for its focus on free software and digital privacy. It emerged as a user-friendly wrapper around complex Linux cryptographic tools like <b>dm-crypt</b> and <b>cryptsetup</b>, aiming to simplify the process of creating and managing encrypted volumes. Its development has consistently focused on providing robust security features, including plausible deniability options, while maintaining a transparent and auditable codebase. Over the years, it has become a popular choice for privacy-conscious users seeking secure data storage on Linux systems.


title: PARAMETERS
content:
<b><b>-n</b>, <b>--new-note</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a new, untitled note.<br><br><b><b>-o</b>, <b>--open-note=<i>URI|FILENAME</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens a specific note identified by its URI or filename.<br><br><b><b>-t</b>, <b>--note-title=<i>TITLE</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the title for a new note created with <b>--new-note</b>.<br><br><b><b>-s</b>, <b>--search=<i>SEARCHTERM</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Launches <i>Tomboy</i> and performs a search for notes containing the specified search term.<br><br><b><b>-p</b>, <b>--print-note=<i>URI|FILENAME</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the content of a specified note to the default printer.<br><br><b><b>-e</b>, <b>--export-note=<i>URI|FILENAME</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exports a specified note to a file or standard output, typically in HTML format.<br><br><b><b>-i</b>, <b>--import-note=<i>FILE</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Imports a note from a specified file.<br><br><b><b>-d</b>, <b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs <i>Tomboy</i> in debug mode, providing more verbose output for troubleshooting.<br><br><b><b>--status-icon</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ensures the <i>Tomboy</i> status icon is always visible in the notification area.<br><br><b><b>--no-status-icon</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents the <i>Tomboy</i> status icon from appearing in the notification area.<br><br><b><b>--sync</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Initiates a synchronization process with all configured note synchronization services.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information of the <i>Tomboy</i> application.<br><br><b><b>-?</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows a help message detailing command-line options.<br><br>


title: DESCRIPTION
content:
<i>Tomboy</i> is a free and open-source desktop note-taking application primarily for Unix-like operating systems. It is renowned for its <b>wiki-like linking system</b>, which enables users to effortlessly connect notes, effectively building a personal knowledge base. Notes are stored as straightforward XML files, ensuring accessibility and readability. The application supports basic text formatting, including <b>bold</b>, <i>italic</i>, strikethrough, and highlighting, alongside features like undo/redo and spell checking. <br><br>Key functionalities include automatic linking of web and email addresses, and robust synchronization capabilities with various services like WebDAV. <i>Tomboy</i> is designed for rapid capture of ideas, thoughts, and important information, making it a valuable tool for organizing personal data. Although it features a comprehensive graphical user interface, its command-line interface is primarily used to interact with a running instance or to initiate specific actions.


title: CAVEATS
content:
Development of <i>Tomboy</i> has significantly slowed, and it may not be actively maintained or readily available on all modern Linux distributions. It is primarily a <b>graphical application</b>, and its command-line interface is mostly for controlling its GUI instance or performing specific actions rather than full text-based interaction. Users seeking a more actively developed alternative might consider its fork, <i>Gnote</i>.


title: NOTE STORAGE
content:
<i>Tomboy</i> stores all notes as individual <b>plain XML files</b> within the <i>~/.local/share/tomboy/notes/</i> directory. This approach makes the notes highly accessible, human-readable, and easily manageable even outside the application itself.


title: PLUGINS
content:
The functionality of <i>Tomboy</i> can be extended significantly through a variety of <b>plugins</b>. These include features like linking to Evolution emails, Bugzilla entries, providing fixed-width text formatting, and enabling export to HTML, among others, enhancing its versatility.


title: SYNCHRONIZATION
content:
<i>Tomboy</i> offers built-in support for synchronizing notes across multiple devices or services. It supports protocols such as <b>WebDAV</b> and <b>SSH</b>. Historically, it also supported <i>Ubuntu One</i> and <i>Tomboy Online</i>, though these services are now largely defunct or integrated into other platforms.


title: HISTORY
content:
<i>Tomboy</i> was originally developed by Alex Graveley and first released in <b>2005</b>. It was written in <b>C#</b> using the Mono framework and GTK#. Initially integrated into the GNOME desktop environment, it later transitioned to an independent project. Its design was inspired by the simplicity and linking capabilities of wiki-like systems, aiming to provide a lightweight and intuitive note-taking experience. <br><br><i>Tomboy</i> quickly gained popularity for its ease of use and unique note-linking feature. However, its development largely stalled after <b>2017</b>, leading to the creation of forks like <i>Gnote</i> (a C++ rewrite) to address maintenance and dependency challenges.


title: SYNOPSIS
content:
toolbox [GLOBAL OPTIONS] COMMAND [OPTIONS] [ARGUMENTS...]<br><br><i>Common Commands:</i><br><b>toolbox create</b> [OPTIONS]: Create a new toolbox container.<br><b>toolbox enter</b> [OPTIONS] [COMMAND [ARGUMENTS...]]: Enter an existing toolbox container.<br><b>toolbox list</b>: List existing toolbox containers.<br><b>toolbox rm</b> [OPTIONS] CONTAINER: Remove a toolbox container.<br><b>toolbox run</b> [OPTIONS] COMMAND [ARGUMENTS...]: Run a command inside a toolbox container.<br><b>toolbox init</b>: Initialize a toolbox container (usually implicitly done).


title: PARAMETERS
content:
<b><b>--container</b> <i>NAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the container name to operate on. If omitted, a default will be used or prompted.<br><br><b><b>--distro</b> <i>NAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the operating system distribution for a new container (e.g., fedora, centos, debian).<br><br><b><b>--release</b> <i>VERSION</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the release version of the distribution for a new container (e.g., 38 for Fedora).<br><br><b><b>--image</b> <i>IMAGE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a custom container image to use for creating a new toolbox container.<br><br><b><b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force an operation, e.g., to remove a running container without confirmation.<br><br>


title: DESCRIPTION
content:
The <b>toolbox</b> command provides a simple and convenient way to create, manage, and interact with containerized command-line environments. It's designed primarily for developers and users of immutable Linux operating systems, such as Fedora Silverblue and Kinoite, allowing them to install and use development tools, libraries, and utilities without modifying the host system.<br><br>Under the hood, <b>toolbox</b> leverages <i>Podman</i> (or <i>Docker</i>) to create <i>OCI</i> (Open Container Initiative) compliant containers that are tightly integrated with the host user's home directory, devices, and even the <i>D-Bus</i>. This integration makes the container feel like a natural extension of the host, providing a familiar workflow while keeping the host system clean and stable.


title: CAVEATS
content:
While <b>toolbox</b> provides excellent isolation for developer tools, it's not a strong security sandbox for untrusted applications, as containers have significant access to the host's user home directory and certain system resources. It relies on <i>Podman</i> (or <i>Docker</i>) being installed and properly configured on the host system.<br><br>Containers can consume significant disk space, especially if many are created or large packages are installed within them. Network connectivity issues might arise if the underlying container engine configuration is not optimal.


title: PERSISTENT ENVIRONMENTS
content:
Toolbox containers are persistent. Once created, they retain their state, installed software, and configurations across reboots, offering a consistent development environment.


title: HOST INTEGRATION
content:
Toolbox containers are designed for deep integration with the host user. They automatically mount the user's home directory, provide access to devices (like GPUs), and allow seamless interaction with the host's <i>D-Bus</i> for graphical applications or system services.


title: NO ROOT REQUIRED
content:
By leveraging <i>Podman</i>'s rootless mode, users can create and manage toolbox containers without requiring <i>sudo</i> privileges, enhancing security and ease of use.


title: HISTORY
content:
The <b>toolbox</b> utility was developed by the <i>Fedora Project</i> team, primarily to cater to the needs of users on atomic and immutable operating systems like <i>Fedora Silverblue</i> and <i>Fedora Kinoite</i>. These operating systems aim for high stability and security by making the root filesystem immutable.<br><br><b>toolbox</b> emerged as a user-friendly solution to allow developers to install and manage their preferred development tools and environments in a mutable, containerized space without compromising the integrity of the host OS. Its development closely tracks the evolution of <i>Podman</i> and <i>Buildah</i>, which form its underlying technology stack.


title: SYNOPSIS
content:
<b>toolbox create</b> [<I>options</I>]<br><br><b>toolbox create</b> <I>[--container NAME] [--distro NAME] [--image IMAGE] [--release RELEASE] [--enforce-release] [--description DESCRIPTION]</I>


title: PARAMETERS
content:
<b><b>--container</b> <I>NAME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a custom name for the new toolbox container. If not provided, a default name will be generated.<br><br><b><b>--distro</b> <I>NAME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the host distribution name to use for picking the default image. Useful when the host's distribution cannot be reliably detected.<br><br><b><b>--image</b> <I>IMAGE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the container image to use for creating the toolbox (e.g., <i>fedora-toolbox:39</i>, <i>registry.fedoraproject.org/fedora-toolbox:latest</i>). This overrides <b>--distro</b> and <b>--release</b>.<br><br><b><b>--release</b> <I>RELEASE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the release of the distribution to use for the image. For example, '39' for Fedora 39.<br><br><b><b>--enforce-release</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Causes <b>toolbox-create</b> to fail if a specific host release cannot be mapped to an image, instead of falling back to a default.<br><br><b><b>--description</b> <I>DESCRIPTION</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides a short, human-readable description for the toolbox, which can be viewed with <b>toolbox list</b>.<br><br>


title: DESCRIPTION
content:
The <b>toolbox-create</b> command is a subcommand of the <b>toolbox</b> utility, designed to set up isolated Linux container environments for development and debugging.<br><br>These "toolboxes" provide a consistent and clean workspace where developers can install libraries, tools, and dependencies without affecting the host operating system. It leverages container runtimes like Podman or Docker to create unprivileged containers that seamlessly integrate with the host's user home directory, network interfaces, and devices. This allows for a smooth development workflow while maintaining a high degree of isolation for project-specific requirements.<br><br>When creating a toolbox, users can specify the desired container image, the distribution, and even a specific release. If not specified, <b>toolbox-create</b> intelligently attempts to match the host system's distribution and release to ensure compatibility and a familiar environment.


title: CAVEATS
content:
Toolboxes rely on an OCI container engine (like <b>Podman</b> or <b>Docker</b>) being installed and running on the host system. Without it, <b>toolbox-create</b> will fail.<br><br>As unprivileged containers, toolboxes have certain limitations; for instance, they cannot directly run system services or perform operations requiring root privileges on the host without specific workarounds.<br><br>While toolboxes integrate seamlessly with the host's home directory, care must be taken with file permissions, especially when interacting with files created by different user IDs inside and outside the container.


title: <B>DEFAULT IMAGE SELECTION</B>
content:
When <b>--image</b> is not specified, <b>toolbox-create</b> attempts to automatically select a suitable container image. It prioritizes matching the host system's distribution and release version (e.g., Fedora 39, RHEL 9) to provide a familiar and compatible environment. If a direct match isn't found, it might fall back to a generic or latest available image for the detected distribution.


title: <B>HOST INTEGRATION</B>
content:
A key feature of toolboxes created with <b>toolbox-create</b> is their deep integration with the host system. The user's home directory (<i>/home/$USER</i>) is automatically mounted into the container, allowing seamless access to personal files and projects. Furthermore, critical devices and network interfaces are shared, making the toolbox feel like a natural extension of the host, rather than a completely isolated virtual machine.


title: HISTORY
content:
The <b>toolbox</b> utility, including <b>toolbox-create</b>, originated from the <i>fedora-toolbox</i> project, which was initially specific to Fedora Linux. Its primary aim was to provide a robust, isolated environment for developers to install various development tools and libraries without cluttering the host operating system.<br><br>Over time, the project evolved, becoming distribution-agnostic and being renamed simply to <b>toolbox</b>. This allowed it to be adopted and used more broadly across other Linux distributions like RHEL, CentOS Stream, and even community-driven efforts for Ubuntu. The command's development has consistently focused on simplifying containerized development workflows by leveraging the capabilities of OCI-compliant container runtimes such as Podman and Docker, making isolated environments easily accessible to end-users.


title: SEE ALSO
content:
<b>toolbox</b>(1), <b>toolbox enter</b>(1), <b>toolbox list</b>(1), <b>toolbox rm</b>(1), <b>podman</b>(1), <b>docker</b>(1)


title: SYNOPSIS
content:
<b>toolbox enter</b> [<I>CONTAINER_NAME</I>] [<I>OPTIONS</I>]<br><b>toolbox enter</b> --container <I>NAME</I> [<I>OPTIONS</I>]


title: PARAMETERS
content:
<b><I>CONTAINER_NAME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the container to enter. If omitted, <b>toolbox</b> will try to enter a default container, typically 'fedora-toolbox-<I>VERSION</I>'.<br><br><b>--container <I>NAME</I>, -c <I>NAME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly specify the name of the container to enter. This is an alternative to the positional argument.<br><br><b>--distro <I>NAME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When implicitly creating a new default toolbox on the fly, this specifies the distribution for the new toolbox (e.g., 'fedora', 'debian').<br><br><b>--release <I>NAME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When implicitly creating a new default toolbox, specifies the release version of the distribution (e.g., '38' for Fedora).<br><br><b>--preserve-home</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Mount the host system's home directory into the container. This is often the default behavior for toolbox containers.<br><br><b>--shell <I>SHELL</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an alternative shell to execute inside the container, instead of the default shell configured for the user (e.g., '--shell /bin/zsh').<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display verbose output, showing more details about the operations being performed. Useful for debugging.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the version information of the <b>toolbox</b> utility and exit.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print a help message summarizing usage and options, then exit.<br><br>


title: DESCRIPTION
content:
<b>toolbox enter</b> is a command-line utility used to enter an existing <i>Toolbox</i> container. A Toolbox container provides a reproducible, isolated, and consistent command-line environment for developers, built on top of OCI containers (specifically using Podman). When you <b>enter</b> a toolbox, you are essentially launching a shell session inside that container. This allows you to install development tools, libraries, and dependencies without cluttering your host operating system. The <b>toolbox</b> utility aims to bridge the gap between containerization and a traditional development workstation, making containerized environments feel like a natural extension of the host system, with shared home directories and access to host D-Bus, network, etc. It's particularly popular on Fedora CoreOS, Silverblue, and Kinoite, but can be used on any system with Podman.


title: CAVEATS
content:
<b>toolbox enter</b> relies on <b>Podman</b> for container management and <b>runc</b> for container execution; these must be installed and properly configured on the host system.<br>Toolbox containers are designed for interactive development and testing, not for running long-lived services or critical production applications.<br>While <b>toolbox</b> aims for seamless integration, there might be subtle differences in environment variables or paths compared to the host system.<br>It is primarily developed for and best integrated with Fedora and its derivatives (e.g., Fedora Silverblue, Kinoite), though it can be installed on other Linux distributions.


title: SHARED ENVIRONMENT
content:
When entering a toolbox, it often shares the user's home directory from the host, allowing seamless access to user files. It also integrates with the host's D-Bus system, enabling containerized applications to interact with graphical applications or system services on the host. Network access is also shared by default.


title: DEVELOPMENT FOCUS
content:
The primary design goal of <b>toolbox</b> is to provide a clean and isolated environment for installing development tools, compilers, language runtimes, and libraries without polluting the host's root file system. This allows developers to experiment with different toolchains or work on projects requiring specific dependency versions without conflicts.


title: HISTORY
content:
The <b>toolbox</b> project originated as part of Fedora's efforts to provide a more robust and flexible developer experience, especially for immutable operating systems like Fedora Silverblue. It leverages <b>Podman</b> (developed by Red Hat) as its backend, building upon existing container technologies to simplify the process of setting up development environments. Its development has focused on creating a user-friendly abstraction over containers, making them feel like a natural part of the desktop workflow rather than a separate virtual machine or complex Docker setup.


title: PARAMETERS
content:
<b><i>COMMAND</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of a <i>toolbox</i> subcommand (e.g., <b>create</b>, <b>enter</b>, <b>list</b>) for which to display detailed help.<br>If omitted, general help for <i>toolbox</i> is shown.<br><br>


title: DESCRIPTION
content:
The <i>toolbox help</i> command is used to display help information for the <i>toolbox</i> utility as a whole, or for any of its specific subcommands.<br>When invoked without arguments, it provides a general overview of the <i>toolbox</i> command, its available subcommands, and common usage patterns.<br>When followed by a <b>COMMAND</b> argument, it displays detailed help specific to that particular <i>toolbox</i> subcommand, explaining its purpose, options, and arguments.<br>This is an essential command for users to understand how to effectively use the <i>toolbox</i> environment, allowing them to quickly look up syntax and functionality without needing to consult external documentation.<br>It ensures that the necessary information is readily available directly from the command line, enhancing user self-sufficiency.


title: CAVEATS
content:
The <i>toolbox help</i> command itself does not have a separate manual page; its functionality is covered within the <i>toolbox(1)</i> manual page.<br>The level of detail provided by <i>toolbox help</i> for each subcommand might vary depending on the specific subcommand and the <i>toolbox</i> version.<br>Requires the <i>toolbox</i> utility to be installed on the system.


title: PURPOSE OF TOOLBOX
content:
<i>toolbox</i> is designed to provide a mutable, user-friendly environment on immutable host operating systems like Fedora CoreOS, ostree-based Fedora Workstation, or Silverblue.<br>It allows users to install development tools and libraries within a container without modifying the host system.


title: INTEGRATION
content:
<i>toolbox</i> integrates closely with the host system, allowing access to the user's home directory, devices, and network, making the containerized environment feel like a native one.


title: HISTORY
content:
The <i>toolbox</i> utility itself originated as part of Project Atomic and Fedora CoreOS efforts to provide a simple, unprivileged way for developers to get a full development environment on immutable operating systems.<br>It leverages <i>podman</i> for container management.<br>The <i>help</i> subcommand has been an integral part of <i>toolbox</i> since its early days, providing on-demand documentation for its users.<br>Its development tracks closely with the <i>toolbox</i> project's evolution, aiming to simplify the user experience for containerized workflows on Linux.


title: PARAMETERS
content:
<b>--skip-user</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Skips setting up the user account inside the container, including uid/gid matching and home directory creation.</i><br><br><b>--skip-setup-bash</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Prevents the command from configuring Bash, such as setting up shell profiles and aliases for the user.</i><br><br><b>--skip-setup-ssh</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Disables the setup of SSH, which typically involves configuring SSH agent forwarding from the host into the container.</i><br><br><b>--skip-setup-env-vars</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Omits the process of setting up essential environment variables within the container's shell environment.</i><br><br><b>--setup-gpg-agent-forwarding</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Explicitly enables the setup of GPG agent forwarding, allowing GPG operations inside the container to use the host's GPG agent.</i><br><br><b>--distro-name <i>&lt;name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies the name of the Linux distribution within the container, used for distribution-specific configurations.</i><br><br><b>--distro-version <i>&lt;version&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies the version of the Linux distribution within the container, complementing --distro-name for specific setups.</i><br><br><b>--home-path <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies the absolute path to the user's home directory inside the container, overriding the default.</i><br><br>


title: DESCRIPTION
content:
<i>toolbox-init-container</i> is an internal helper command crucial for setting up and configuring new or rebased <i>toolbox</i> containers. It runs automatically inside the container when it's first created or after certain operations by the <i>toolbox</i> utility. Its main purpose is to prepare the user's environment, ensuring the container is ready for development. This includes creating and configuring the user account to match the host, setting up essential shell environments like Bash, configuring SSH for seamless forwarding, managing environment variables, and optionally enabling GPG agent forwarding. This command is not intended for direct manual execution by users; rather, it's an essential component of the <i>toolbox</i> ecosystem, abstracting away the complexities of container environment setup.


title: CAVEATS
content:
<i>This command is an internal helper and is not intended for direct manual invocation by users. It is automatically executed by the <code>toolbox</code> utility.</i><br><i>Misusing or manually running this command with incorrect parameters can lead to an improperly configured or broken <code>toolbox</code> container environment.</i>


title: INTERNAL OPERATION
content:
<i>This command is invoked by the <code>toolbox</code> parent command, usually via <code>podman run</code>, to perform initial setup steps inside a new container instance. It ensures that the user inside the container matches the host user, and that essential development tools and configurations are in place before the user is given a shell.</i>


title: ENVIRONMENT SYNCHRONIZATION
content:
<i>A key function of <code>toolbox-init-container</code> is to synchronize aspects of the container's environment with the host system, such as user IDs, home directory paths, and SSH agent forwarding. This seamless integration allows developers to use their familiar tools and configurations from the host inside the container.</i>


title: HISTORY
content:
<i><code>toolbox-init-container</code> is an integral part of the <code>containers/toolbox</code> project, primarily developed for Red Hat's containerized operating systems like Fedora CoreOS and Silverblue. It was introduced early in the <code>toolbox</code> project's lifecycle to automate the complex and often error-prone task of setting up a consistent and usable development environment within isolated OCI containers. Its development as a Go program reflects the project's preference for robust, self-contained binaries for internal utilities.</i>


title: PARAMETERS
content:
<b>-i, --image</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the name of the container image.<br><br><b>-n, --name</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the container's name (often the default behavior).<br><br><b>-q, --quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress headers and only display container names, useful for scripting.<br><br><b>-s, --short</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provide a shorter, less verbose output format.<br><br><b>-t, --table</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the output in a formatted table (this is the default output format).<br><br><b>-l, --latest</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show only the most recently created container.<br><br><b>--no-trunc</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not truncate any of the output fields, showing full names and IDs.<br><br>


title: DESCRIPTION
content:
<b>toolbox list</b> is a fundamental command within the <i>Toolbox</i> utility, designed to manage isolated command-line environments on Linux systems, particularly useful for immutable operating systems like Fedora Silverblue.<br><br>This command provides a comprehensive overview of all existing <i>Toolbox</i> containers created by the user. It displays crucial information such as the container's unique <i>name</i>, the <i>image</i> it was built from, its current <i>status</i> (e.g., running, exited), and the <i>time of creation</i>.<br><br>By listing these development environments, users can quickly identify, inspect, and manage their various workspaces, making it an essential tool for developers and system administrators working with containerized workflows.


title: CAVEATS
content:
The <b>toolbox list</b> command only displays containers created and managed by the <i>Toolbox</i> utility, not general <i>podman</i> or <i>docker</i> containers. It requires the <i>Toolbox</i> package to be installed and operational on the system.


title: HISTORY
content:
The <i>Toolbox</i> project, including its <b>list</b> command, emerged primarily with the rise of immutable Linux operating systems like Fedora Silverblue and Fedora CoreOS. Its development aimed to provide a convenient and robust way for developers to create mutable, containerized environments on an otherwise read-only host filesystem. Leveraging <i>Podman</i> as its container engine, <b>toolbox list</b> has been a core command since the early days, essential for users to keep track of their various development environments and workspaces.


title: PARAMETERS
content:
<b><I>CONTAINER_NAME</I>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify one or more names of the toolbox containers to be removed.<br><br><b>-a, --all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remove all existing toolbox containers.<br><br><b>-f, --force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the removal of a running toolbox container without confirmation.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print verbose output during the removal process.<br><br>


title: DESCRIPTION
content:
<I>toolbox-rm</I> is a utility command used to remove one or more existing <B>Toolbox</B> containers. A <B>Toolbox</B> container provides a reproducible development environment, especially useful on immutable operating systems like Fedora Silverblue or CoreOS.<br><br>When you remove a toolbox container, all its contents, including files, installed applications, and configuration, are permanently deleted. This operation is irreversible and frees up disk space.<br><br>By default, <I>toolbox-rm</I> will not remove a running container unless the <B>--force</B> option is used. It's crucial to ensure you have backed up any necessary data before proceeding with the removal.


title: CAVEATS
content:
All data stored within the removed toolbox container will be permanently lost. This operation is irreversible.<br><br>Removing a running container requires the <B>--force</B> (<B>-f</B>) option. Without it, the command will fail or prompt for confirmation.<br><br>Using the <B>--all</B> (<B>-a</B>) option will delete every toolbox container on your system, so use with extreme caution.


title: INTERACTIVE CONFIRMATION
content:
By default, <I>toolbox-rm</I> will prompt for confirmation before deleting a container, unless the <B>--force</B> option is specified or standard input is not a TTY.


title: DATA PERSISTENCE CONSIDERATION
content:
Toolbox containers are designed for development environments, and while you can mount external directories, their internal state is ephemeral. Ensure critical data is synchronized or backed up outside the container before removal.


title: HISTORY
content:
The <B>Toolbox</B> project was initiated to facilitate development on immutable Linux distributions, such as Fedora Silverblue and CoreOS, where the root filesystem is read-only. <I>toolbox-rm</I> is an integral part of managing these development environments, allowing users to clean up or reset their containerized workspaces. It evolved from similar concepts within the atomic host ecosystem.


title: PARAMETERS
content:
<b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the removal of a running Toolbox container. Without this option, attempts to remove a container that is currently running will fail, preventing accidental deletion of active development environments.<br><br>


title: DESCRIPTION
content:
<code>toolbox-rmi</code> (more accurately invoked as <code>toolbox rmi</code>) is a specialized command used to remove one or more existing Toolbox containers. Toolbox containers provide a consistent and mutable Linux environment for development and debugging, isolated from the host operating system. This command serves a similar purpose to <code>podman rm</code> or <code>docker rm</code>, but it is specifically tailored for containers created and managed by the <code>toolbox</code> utility. When a Toolbox container is removed, all its contents, including installed applications, user data, and configuration files within that container, are permanently deleted. It is crucial to ensure that any important data has been backed up or moved out of the container before proceeding with its removal. The command allows identifying containers by their name or a partial/full ID. Removing a running container requires the use of the <code>--force</code> option.


title: CAVEATS
content:
<b>Irreversible Data Loss</b>:<br>Removing a Toolbox container permanently deletes all data, applications, and configurations stored within it. There is no undo mechanism, so ensure all critical data is backed up before proceeding.<br><b>Running Containers</b>:<br>A running container cannot be removed unless the <b>-f</b> or <b>--force</b> option is used. This is a safety measure to prevent disruption of ongoing work.<br><b>Subcommand Context</b>:<br>While often referred to as "toolbox-rmi" for brevity, this functionality is invoked as a subcommand of the main <code>toolbox</code> command: <code>toolbox rmi</code>. This means <code>toolbox</code> must be installed and the <code>rmi</code> subcommand used.


title: CONTAINER VS. IMAGE REMOVAL
content:
It is important to distinguish that <code>toolbox rmi</code> removes a specific <i>container instance</i>, which is a running or stopped environment based on an image. It does <i>not</i> remove the underlying container <i>image</i> itself. To manage container images, tools like <code>podman rmi</code> are typically used.


title: UNDERLYING TECHNOLOGY
content:
<code>toolbox</code> is built on top of <code>podman</code>. When you execute <code>toolbox rmi</code>, <code>toolbox</code> internally translates this into a <code>podman rm</code> command tailored to the specific Toolbox container it manages. This leverages the robust capabilities of Podman while providing a simplified interface for Toolbox users.


title: HISTORY
content:
The <code>toolbox</code> utility was developed by Red Hat as part of the Fedora CoreOS and Silverblue initiatives, aiming to provide a flexible and mutable development environment on immutable host operating systems. It was first officially released around 2019. The <code>rmi</code> subcommand, for removing containers, has been a core feature since the early versions of <code>toolbox</code>, providing essential lifecycle management for these specialized development environments. Its design is heavily influenced by <code>podman</code>'s command-line interface.


title: PARAMETERS
content:
<b><b>-c</b>, <b>--container</b> <i>NAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the name of the Toolbox container to execute the command within. If omitted, the default container (e.g., <i>fedora-toolbox-38</i>) is used.<br><br><b><b>-i</b>, <b>--image</b> <i>IMAGE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the container image to base the Toolbox on. This option is primarily relevant if the specified container does not exist and <i>toolbox-run</i> attempts to create it implicitly.<br><br><b><b>-r</b>, <b>--release</b> <i>RELEASE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the release of the container, such as <i>38</i> for Fedora 38. This helps identify or create the correct container if multiple releases are available.<br><br><b><b>--distro</b> <i>DISTRO</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the distribution of the container, for example <i>fedora</i> or <i>rhel</i>. This works in conjunction with <i>--release</i>.<br><br><b><b>-R</b>, <b>--root</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes the command inside the container with root privileges. By default, commands run as the current user.<br><br><b><b>--log-level</b> <i>LEVEL</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the logging verbosity level for <i>toolbox-run</i> itself. Common levels include <i>debug</i>, <i>info</i>, <i>warn</i>, <i>error</i>.<br><br><b><b>--log-file</b> <i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Directs logging output to the specified file path instead of standard error.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information of the <i>toolbox-run</i> command and exits.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows a help message and exits.<br><br>


title: DESCRIPTION
content:
<i>toolbox-run</i> is a powerful utility within the <i>toolbox</i> ecosystem, designed to execute a specified command directly inside an existing Toolbox container. Unlike <i>toolbox enter</i>, which provides an interactive shell session, <i>toolbox-run</i> is ideal for non-interactive tasks, scripting, and automation. It allows developers to leverage the isolated and customizable environment of their Toolbox containers for single-shot operations like compiling code, running tests, or performing system administration tasks without manually entering and exiting the container. By simply specifying the container name (or using the default) and the command, users can seamlessly run their tools and applications within a consistent and controlled environment, mirroring the experience of executing commands on a traditional Linux system while benefiting from container isolation. This capability significantly streamlines workflows for immutable operating systems and container-centric development.


title: CAVEATS
content:
<i>toolbox-run</i> relies on the <i>toolbox</i> environment being correctly set up and requires <i>podman</i> as its underlying container engine.<br>While <i>toolbox-run</i> can implicitly create a container if it doesn't exist (when <i>--image</i> or related options are used), it's generally recommended to explicitly create containers using <i>toolbox create</i> first for better control.<br>The command executes in an isolated environment; changes made inside the container, such as installing packages, persist within that container but do not affect the host system directly.<br>The standard input, output, and error streams of the command executed inside the container are connected to <i>toolbox-run</i>'s streams, enabling seamless interaction or scripting.


title: DEFAULT BEHAVIOR
content:
When no <i>CONTAINER</i> name is specified, <i>toolbox-run</i> intelligently selects the default Toolbox container, typically the one corresponding to the host's operating system release (e.g., <i>fedora-toolbox-38</i>).


title: EXIT STATUS PROPAGATION
content:
<i>toolbox-run</i> faithfully propagates the exit status of the command executed inside the container. This feature is vital for scripting, allowing external scripts to react appropriately to the success or failure of the containerized operation.


title: USER CONTEXT
content:
By default, commands are run as the current user inside the container, matching the user ID and home directory from the host system for a consistent experience, unless the <b>--root</b> option is used.


title: HISTORY
content:
The <i>toolbox</i> project emerged from the need for a robust and mutable development environment on immutable Linux distributions like Fedora Silverblue. Initially known as <i>podman-toolbox</i>, the tool provided a consistent way to run developer tools and build systems within containers without altering the host operating system. <i>toolbox-run</i> was introduced as a key component to facilitate non-interactive execution of commands, complementing <i>toolbox-enter</i> for interactive sessions. This design decision empowers users to seamlessly integrate containerized development workflows into scripts and automation, significantly enhancing productivity and maintaining host system integrity.


title: PARAMETERS
content:
<b>-b</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts <b>top</b> in batch mode, sending output to stdout without interactive commands. Useful for scripting.<br><br><b>-d <delay></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the delay time (in seconds) between screen updates. Default is 3 seconds.<br><br><b>-n <iterations></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the maximum number of iterations (updates) <b>top</b> should produce before exiting.<br><br><b>-p <pid></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Monitors only the specific process IDs (PIDs) provided. Multiple PIDs can be separated by commas.<br><br><b>-u <user></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Monitors processes owned by a specific user or effective UID. Can be a username or UID.<br><br><b>-H</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows individual threads rather than grouping them under their parent process.<br><br><b>-i</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Does not show idle or zombie processes in the process list, focusing on active processes.<br><br><b>-s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts <b>top</b> in secure mode, disabling potentially dangerous interactive commands like 'k' (kill) and 'r' (renice).<br><br><b>-c</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Toggles the display of the full command line for processes instead of just the command name.<br><br><b>-S</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts <b>top</b> in cumulative mode, where each process reports its CPU time to include that of its dead children.<br><br>


title: DESCRIPTION
content:
<b>top</b> provides a dynamic, real-time view of a running Linux system.<br>It displays system summary information at the top, including uptime, load averages, tasks, CPU states, and memory/swap usage.<br>Below the summary, it lists processes or threads currently being managed by the kernel, ordered by CPU usage by default. Users can interact with <b>top</b> to sort processes by different criteria (e.g., memory, PID), kill processes, renice them, or change the refresh interval.<br>It's an indispensable tool for system monitoring, performance analysis, and troubleshooting, offering a snapshot of resource consumption and process behavior.


title: CAVEATS
content:
While powerful, <b>top</b> itself can consume CPU, especially with short refresh intervals or when monitoring a very large number of processes.<br>Its default display and interactive commands can be overwhelming for novice users.<br>It's designed for real-time snapshots, not for long-term historical data logging, for which tools like <i>sar</i> or specific monitoring daemons are better suited.


title: KEY INTERACTIVE COMMANDS
content:
Once <b>top</b> is running, users can press various keys for interactive actions:<br><b><I>k</I></b>: Kill a process (prompts for PID).<br><b><I>r</I></b>: Renice a process (change its priority).<br><b><I>d</I></b> or <b><I>s</I></b>: Change the delay time between updates.<br><b><I>u</I></b>: Filter processes by user.<br><b><I>P</I></b>: Sort processes by CPU usage (default).<br><b><I>M</I></b>: Sort processes by resident memory usage (%MEM).<br><b><I>T</I></b>: Sort processes by time or cumulative time.<br><b><I>1</I></b>: Toggle display of individual CPU cores.<br><b><I>q</I></b>: Quit <b>top</b>.


title: UNDERSTANDING OUTPUT COLUMNS
content:
The process list in <b>top</b> displays various columns:<br><b><I>PID</I></b>: Process ID.<br><b><I>USER</I></b>: Owning user name.<br><b><I>PR</I></b>: Priority of the task.<br><b><I>NI</I></b>: Nice value of the task.<br><b><I>VIRT</I></b>: Virtual memory used by the process.<br><b><I>RES</I></b>: Resident (physical) memory used.<br><b><I>SHR</I></b>: Shared memory used.<br><b><I>S</I></b>: Process status (e.g., R=running, S=sleeping, Z=zombie).<br><b><I>%CPU</I></b>: CPU usage since last update.<br><b><I>%MEM</I></b>: Physical memory usage.<br><b><I>TIME+</I></b>: Total CPU time used by the task.<br><b><I>COMMAND</I></b>: Command name or full command line.


title: HISTORY
content:
<b>top</b> has been a fundamental system monitoring utility in Unix-like operating systems for decades, with its origins tracing back to BSD systems. The version commonly found on Linux distributions is part of the <i>procps-ng</i> suite of utilities, which continues to be actively maintained and enhanced. It has evolved significantly over time, adding features like multi-CPU core monitoring and improved interactive capabilities, making it a cornerstone for system administrators and developers.


title: PARAMETERS
content:
<b><i>interval</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the time in seconds between screen updates. The default is 2 seconds.<br><br><b><i>count</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the number of updates to display before exiting. If not specified, <b>topas</b> runs indefinitely.<br><br><b><b>-C</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays detailed CPU statistics. This is often the default view.<br><br><b><b>-D</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays detailed disk I/O statistics, including I/O rate, transfer rate, and busy percentage per disk.<br><br><b><b>-M</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays detailed memory statistics, including physical memory, paging space, and filesystem cache usage.<br><br><b><b>-N</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays detailed network I/O statistics, showing data rates, packets, and errors per network adapter.<br><br><b><b>-P</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays detailed process statistics, similar to <b>top</b>, showing CPU usage, memory, and command names for individual processes.<br><br><b><b>-L</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays Logical Partition (LPAR) statistics, useful in virtualized AIX environments.<br><br>


title: DESCRIPTION
content:
<b>topas</b> is a powerful and interactive real-time performance monitoring utility, primarily associated with IBM's AIX operating system. While <b>topas</b> is <i>not a native Linux command</i>, it serves a similar purpose to tools like <b>top</b>, <b>htop</b>, <b>nmon</b>, or <b>perf</b> on Linux, providing a comprehensive overview of system resource utilization.<br><br>It displays various performance metrics including CPU usage, memory consumption, disk I/O, network activity, and process statistics, often presented with ASCII graphical representations. Users can navigate through different views (e.g., processes, disks, networks) to drill down into specific areas of interest. <b>topas</b> is designed for system administrators to quickly identify performance bottlenecks and understand system behavior in a dynamic environment. Its ability to display historical data via <b>topasrec</b> further enhances its diagnostic capabilities.


title: CAVEATS
content:
<b>topas</b> is a standard performance monitoring utility <i>specific to IBM AIX</i> and is <i>not a native or commonly available command</i> on most Linux distributions. Linux users seeking similar comprehensive monitoring tools should consider <b>nmon</b> (which has a Linux port and provides similar capabilities), <b>htop</b>, <b>perf</b>, or a combination of standard utilities like <b>top</b>, <b>vmstat</b>, <b>iostat</b>, and <b>sar</b>.


title: HISTORICAL DATA LOGGING
content:
<b>topas</b> integrates with the <b>topasrec</b> utility (on AIX) to record system performance data into binary files. These files can later be analyzed using tools like <b>topasout</b> or imported into graphical analysis tools, allowing for post-mortem analysis and trend identification of system performance over time.


title: HISTORY
content:
The <b>topas</b> utility originated as a core performance monitoring tool within IBM's AIX operating system. It was developed to provide system administrators with a real-time, interactive view of system resources, similar to <b>top</b> on Unix-like systems but with a broader set of metrics and graphical capabilities.<br><br>Its design focuses on comprehensive data presentation, including CPU, memory, disk, and network I/O, alongside process details. Over the years, it has evolved within the AIX ecosystem to support newer hardware architectures and virtualization features, such as Logical Partitions (LPARs). While <b>topas</b> remains an AIX-specific utility, its comprehensive approach has influenced the development and adoption of similar tools like <b>nmon</b> in the broader Unix/Linux community.


title: PARAMETERS
content:
<b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information and exits.<br><br><b><b>-V</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints version information and exits.<br><br><b><b>-y</b>, <b>--yes</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assumes "yes" to all prompts, running non-interactively.<br><br><b><b>--no-self-update</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents <b>topgrade</b> from attempting to update itself.<br><br><b><b>--no-parallel</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables parallel execution of updaters, running them sequentially.<br><br><b><b>--disable <<i>UPDATER</i>></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables a specific updater (e.g., <b>apt</b>, <b>pip</b>). Can be specified multiple times.<br><br><b><b>--only <<i>UPDATER</i>></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs only the specified updater(s). Can be specified multiple times.<br><br><b><b>--print-commands</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the commands that would be run without actually executing them.<br><br><b><b>--config <<i>PATH</i>></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative configuration file path.<br><br>


title: DESCRIPTION
content:
<b>topgrade</b> is an intelligent, cross-platform command-line utility designed to streamline the process of updating various software components on your system. Instead of manually running `apt update && apt upgrade`, `dnf update`, `pacman -Syu`, `brew update && brew upgrade`, `pip install --upgrade`, `cargo update`, or specific updates for tools like `oh-my-zsh`, <b>topgrade</b> automates this entire sequence. <br><br>It acts as a meta-updater, orchestrating updates across a wide array of package managers (e.g., apt, dnf, pacman, Homebrew, Chocolatey, Nix), programming language environments (e.g., pip, cargo, npm, go), and other tools. This consolidation saves significant time and effort, ensuring your system, development tools, and applications are consistently up-to-date with a single command. <b>topgrade</b> is highly configurable via a `~/.config/topgrade.toml` file, allowing users to enable or disable specific updaters, add custom commands, and control its behavior.


title: CAVEATS
content:
<b>topgrade</b> relies on the underlying package managers and tools being correctly installed and configured. Issues with a specific package manager will manifest through <b>topgrade</b>.<br><br>Running with <b>--yes</b> can sometimes lead to unexpected behavior if an underlying update has critical prompts or requires manual intervention. It's generally safer to review updates before confirming.<br><br>While <b>topgrade</b> simplifies updates, it doesn't replace the need to understand how your system's primary package manager works or to review significant changes before applying them.


title: CONFIGURATION
content:
<b>topgrade</b> is highly customizable through its configuration file, typically located at <i>~/.config/topgrade.toml</i> (or <i>%APPDATA%\topgrade\topgrade.toml</i> on Windows). This TOML file allows users to: <br><ul><li>Enable or disable specific updaters.</li><li>Define custom commands to run before or after updates.</li><li>Override default command arguments for updaters.</li><li>Control parallel execution, confirmation prompts, and more.</li></ul>This flexibility makes <b>topgrade</b> adaptable to diverse system setups and personal preferences.


title: CROSS-PLATFORM SUPPORT
content:
One of <b>topgrade</b>'s most significant features is its broad cross-platform compatibility. It supports Linux distributions (Debian/Ubuntu, Fedora, Arch, NixOS, etc.), macOS (via Homebrew), and Windows (via WSL, Chocolatey, Scoop). This makes it an ideal tool for users who work across multiple operating systems or development environments, providing a consistent update experience regardless of the underlying platform.


title: HISTORY
content:
<b>topgrade</b> was created to address the common frustration of needing to run multiple update commands across various software ecosystems (system packages, programming language tools, dotfiles, etc.). It emerged as a solution to automate this fragmented update process, gaining popularity due to its simplicity, cross-platform compatibility, and extensive support for different updaters. Its development is community-driven, focusing on adding support for more tools and improving user experience through configuration options.


title: SYNOPSIS
content:
<b>topydo</b> [<b>-d</b> <i>DIRECTORY</i>] [<b>-f</b> <i>FILENAME</i>] <i>command</i> [<i>options</i>] [<i>arguments</i>]<br><br><b>Common Usage Examples:</b><br><b>topydo</b> <b>add</b> <i>"New task description"</i><br><b>topydo</b> <b>list</b> [<i>filter</i>]<br><b>topydo</b> <b>done</b> <i>ID</i><br><b>topydo</b> <b>archive</b>


title: PARAMETERS
content:
<b><b>-d</b> <i>DIRECTORY</i>, <b>--directory</b> <i>DIRECTORY</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the directory where the <i>todo.txt</i> file is located. If not specified, <i>topydo</i> looks in the current working directory or a default path.<br><br><b><b>-f</b> <i>FILENAME</i>, <b>--file</b> <i>FILENAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the name of the todo file to use (e.g., <i>mytasks.txt</i>). The default is <i>todo.txt</i>.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message for the <i>topydo</i> command or a specific subcommand and exits.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the program's version number and exits.<br><br>


title: DESCRIPTION
content:
<i>topydo</i> is a command-line interface (CLI) tool designed for managing hierarchical todo lists using plain text files. It offers a simple yet powerful way to organize tasks, inspired by tools like Emacs Org-mode and Topy.<br><br>Unlike database-backed task managers, <i>topydo</i> operates directly on human-readable text files, typically named <b>todo.txt</b>, making the data easily accessible, portable, and version-controllable (e.g., with Git). Users can create tasks, nest them under parent tasks to form a hierarchy, mark them as done, archive completed items, defer tasks to a later date, and assign priorities or tags. Its robust filtering and searching capabilities allow users to quickly find specific tasks based on various criteria, including status, tags, and keywords. <i>topydo</i> promotes a straightforward workflow, enabling efficient task management directly from the terminal without relying on complex configurations or external dependencies beyond Python. The tool stores all task information within a single or multiple plain text files, where indentation defines the hierarchy. This design philosophy emphasizes simplicity, longevity of data, and interoperability with other text-based tools. It's an excellent choice for those who prefer a minimalist, keyboard-driven approach to personal task management.


title: CAVEATS
content:
<i>topydo</i>, by design, relies on plain text files for data storage, which means it inherently lacks advanced features common in more complex task managers such as built-in reminders, recurring task generation, or sophisticated calendar integration. Synchronization across devices is not handled internally and requires external solutions like cloud storage or version control systems (e.g., Git). While powerful for command-line users, its plain-text nature and reliance on CLI interactions might present a steeper learning curve for users accustomed to graphical user interfaces.


title: FILE FORMAT AND HIERARCHY
content:
<i>topydo</i> stores tasks in a simple plain-text file. Each task occupies a line, and subtasks are created by indenting them with tabs or spaces. Tasks can include special syntax for metadata such as <b>@context</b> (e.g., <i>@home</i>), <b>+project</b> (e.g., <i>+work</i>), <b>(PRIORITY)</b> (e.g., <i>(A)</i>), and completion dates. Completed tasks are typically marked with an '<b>x</b>' prefix.


title: CONFIGURATION
content:
<i>topydo</i> can be customized through a <b>config.json</b> file, usually located in <b>~/.config/topydo/</b>. This file allows users to define default file paths, date formats, color schemes, and other display preferences. The <b>topydo config</b> subcommand provides an interactive way to view and modify these settings.


title: HISTORY
content:
<i>topydo</i> was developed to provide a modern, robust, and plain-text-centric command-line interface for managing hierarchical todo lists. Its architecture is deeply inspired by established systems like Emacs Org-mode for task organization and the Python-based 'Topy' utility, aiming to offer a similar powerful plain-text experience with a more streamlined CLI. The project is open-source and primarily hosted on GitHub, evolving with community contributions to maintain its focus on simplicity, portability, and efficient task management for terminal users.


title: SYNOPSIS
content:
<b>tor</b> [<i>OPTIONS</i>]<br>Most commonly, <b>tor</b> is run as a system service (e.g., using <b>systemctl start tor</b> or <b>service tor start</b>) and configured via its configuration file, typically <b>/etc/tor/torrc</b>. Command-line options can override or supplement the settings in the configuration file.


title: PARAMETERS
content:
<b><b>-f</b> <i>file</i>, <b>--torrc-file</b> <i>file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative configuration file to use instead of the default.<br><br><b><b>--hash-password</b> <i>password</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a hashed password suitable for use with configuration options like <i>HashedControlPassword</i>.<br><br><b><b>--run-as-daemon</b> <i>mode</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Configures Tor to run as a background daemon. Modes include <i>0</i> (foreground), <i>1</i> (daemonize), and <i>2</i> (daemonize, but don't exit if we fail).<br><br><b><b>--pid-file</b> <i>file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path where Tor should write its process ID (PID) file.<br><br><b><b>--data-directory</b> <i>directory</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the main data directory for Tor, where it stores keys, state, and other persistent data.<br><br><b><b>--socks-port</b> <i>port</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the port on which Tor's SOCKS proxy will listen for connections from applications. Multiple ports can be specified.<br><br><b><b>--control-port</b> <i>port</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the port on which Tor's control interface will listen for connections from controller applications (e.g., Stem or OnionShare).<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information of the Tor daemon and exits.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints a summary of command-line options and exits.<br><br><b><b>--dump-config</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the current Tor configuration, including default and overridden values, to standard output.<br><br>


title: DESCRIPTION
content:
The <b>tor</b> command runs the Tor daemon, which enables anonymous communication by routing Internet traffic through a worldwide volunteer overlay network. Tor, short for "The Onion Router," encrypts data and relays it through multiple servers (relays) to conceal the user's IP address and location, making it difficult to trace online activities. It acts as a SOCKS proxy, allowing applications configured to use it to send their traffic anonymously. While providing strong privacy, it is crucial to understand that Tor alone does not guarantee absolute anonymity and works best when used in conjunction with other security practices, such as HTTPS, and with applications specifically configured to proxy their traffic through it. It can also function as a relay or exit node for the network.


title: CAVEATS
content:
Using Tor effectively for anonymity requires careful consideration. It does <i>not</i> encrypt traffic between the exit node and the destination server, meaning unencrypted traffic (e.g., plain HTTP) can be monitored at the exit node. Tor also introduces latency, making it unsuitable for applications requiring high speed. While designed to protect against traffic analysis, sophisticated adversaries may still be able to correlate traffic. Always ensure your applications are correctly configured to use the Tor SOCKS proxy.


title: CONFIGURATION FILE
content:
The primary configuration for the <b>tor</b> daemon is handled through its configuration file, typically located at <b>/etc/tor/torrc</b>. This file contains directives for network configuration, relay settings, security features, and more. Command-line parameters provided to the <b>tor</b> command can override settings specified in this file.


title: SERVICE MANAGEMENT
content:
On most Linux distributions, <b>tor</b> is installed as a system service. It is commonly managed using <b>systemd</b> (e.g., <b>systemctl start tor</b>, <b>systemctl stop tor</b>, <b>systemctl enable tor</b>) or traditional <b>SysVinit</b> scripts (e.g., <b>service tor start</b>). Running <b>tor</b> directly from the command line is usually for testing or specific use cases, rather than continuous operation.


title: HISTORY
content:
The Tor project originated in the mid-1990s at the U.S. Naval Research Laboratory, initially developed for protecting U.S. intelligence communications. It was released under a free license in 2002. In 2006, The Tor Project, Inc. was founded as a non-profit organization to maintain and develop the software. Since then, Tor has evolved into a globally recognized tool for privacy, anti-censorship, and secure communication, used by activists, journalists, and everyday citizens worldwide.


title: SYNOPSIS
content:
tor-gencert <I>[OPTIONS]</I><br><br>This command generates a new Tor identity key and a self-signed certificate for that key.


title: PARAMETERS
content:
<b><b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information and exits.<br><br><b><b>-V</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows version information and exits.<br><br><b><b>-i</b> <I>identity_key_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path for the Tor identity key file to be generated or loaded.<br><br><b><b>-s</b> <I>signing_key_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path for the certificate signing key.<br><br><b><b>-r</b> <I>revocation_key_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path for the certificate revocation key.<br><br><b><b>-c</b> <I>certificate_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path where the generated certificate will be saved.<br><br><b><b>-t</b> <I>type</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the type of certificate to generate (e.g., "authority", "router"). Defaults to "authority".<br><br><b><b>-e</b> <I>expiration</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the expiration date/time for the certificate. Formats include "YYYY-MM-DD", "YYYY-MM-DD HH:MM:SS", or "N days".<br><br><b><b>-m</b> <I>min_lifetime</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the minimum lifetime of the certificate in days if it would otherwise expire too soon.<br><br><b><b>-f</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces overwriting of existing files without prompting.<br><br>


title: DESCRIPTION
content:
tor-gencert is a utility included with the Tor project used to generate cryptographic keys and self-signed certificates.<br><br>Its primary purpose is to create the long-term identity key and the corresponding certificate for a Tor relay, especially for directory authorities or bridge authorities. These generated files—typically an identity key (e.g., <I>authority_identity_key</I>) and a certificate (e.g., <I>authority_certificate</I>)—are fundamental for a Tor server to establish its unique identity and participate securely in the Tor network.<br><br>The command is usually run once when setting up a new Tor authority or a similar component that requires a persistent, verifiable identity. It ensures that the Tor instance can be identified and trusted by other nodes in the network.


title: CAVEATS
content:
Generating new identity keys and certificates is a sensitive operation. The generated files (especially the identity key) should be treated with extreme care and kept secure, as they represent the unforgeable identity of your Tor authority or relay. This command is typically run only once for a given Tor authority setup.


title: DEFAULT OUTPUT
content:
If no file paths are specified for the identity key or certificate, <I>tor-gencert</I> typically creates them in the current working directory or a predefined Tor data directory, using default filenames such as <I>authority_identity_key</I> and <I>authority_certificate</I>.


title: KEY MANAGEMENT
content:
The security of the generated identity key is paramount. Loss or compromise of this key could allow an attacker to impersonate your Tor authority, potentially disrupting network operations or trust. Ensure proper file permissions and storage security for all generated key files.


title: HISTORY
content:
The <I>tor-gencert</I> utility has been an integral part of the Tor project since its early days, specifically designed to facilitate the setup and operation of directory authorities and bridge authorities within the Tor network. Its core functionality of generating long-term identity keys and self-signed certificates has remained consistent, underscoring its foundational role in establishing trusted identities for critical Tor infrastructure components.


title: PARAMETERS
content:
<b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message and exits.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows version information and exits.<br><br><b><b>-s</b>, <b>--socks</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs <i>tor-resolve</i> to use the SOCKS <i>RESOLVE</i> command for name resolution. This is the default method when connecting to a SOCKS port (e.g., 9050).<br><br><b><b>-c</b>, <b>--controller</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs <i>tor-resolve</i> to use Tor's Control Protocol for name resolution. This is the default method when connecting to a Control Port (e.g., 9051) and can offer more robust control.<br><br><b><b>-p</b> <i>PORT</i>, <b>--port</b> <i>PORT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the port to connect to the Tor daemon. Defaults to <i>9050</i> for SOCKS connections and <i>9051</i> for Control Protocol connections.<br><br><b><b>-r</b>, <b>--reverse</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a reverse DNS lookup, querying for a PTR record for the given IP address.<br><br><b><b>-t</b> <i>TYPE</i>, <b>--type</b> <i>TYPE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the DNS query type to perform (e.g., A, AAAA, PTR, TXT, MX, NS). By default, it queries for A records (IPv4 addresses) or PTR records if <b>--reverse</b> is used.<br><br><b><b>-x</b>, <b>--exit-address</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the IP address of the Tor exit node that handled the DNS resolution, in addition to the resolved hostname or IP.<br><br>


title: DESCRIPTION
content:
<i>tor-resolve</i> is a command-line utility designed to perform DNS lookups through the Tor anonymity network. It acts as a specialized resolver, sending DNS queries (like A, AAAA, or PTR records) over an encrypted Tor circuit, thus helping to obscure the origin of the DNS request. This is particularly useful for privacy-conscious users or applications that need to resolve hostnames without revealing their direct IP address to DNS servers. It can operate by communicating with the Tor daemon's SOCKS proxy port or its Control Protocol port, providing flexibility in how it integrates with a running Tor instance. Unlike standard DNS resolvers, <i>tor-resolve</i> ensures that your DNS queries are routed through the Tor network, inheriting the privacy benefits of Tor.


title: CAVEATS
content:
<i>tor-resolve</i> requires a running Tor daemon to function. It sends DNS queries over Tor, but the final resolution happens at the exit node, which could potentially see the query. While it protects your identity from the DNS server, it does not magically make the queried domain disappear. Tor network speed can affect resolution times. Ensure your Tor daemon is configured to allow SOCKS or Control Port connections from where you run <i>tor-resolve</i>.


title: RESOLUTION METHODS
content:
<i>tor-resolve</i> can communicate with the Tor daemon in two primary ways: via the SOCKS proxy port or the Control Protocol port. <br>When using the <b>--socks</b> option (or connecting to the SOCKS port, typically 9050), it sends a SOCKS5 <i>RESOLVE</i> command. This is a simpler interface. <br>When using the <b>--controller</b> option (or connecting to the Control Port, typically 9051), it uses the Tor Control Protocol, which allows for more detailed interaction and potentially more robust resolution handling, especially for complex query types. The choice depends on how your Tor daemon is configured and what level of interaction is desired.


title: PRIVACY IMPLICATIONS
content:
By routing DNS queries through the Tor network, <i>tor-resolve</i> helps to prevent your Internet Service Provider (ISP) or local network observer from seeing your DNS requests and, consequently, which websites or services you are trying to reach. The DNS query is anonymized and exits from a random Tor exit node, making it difficult to link the query back to your original IP address. This is a vital component of maintaining anonymity while browsing or connecting through Tor.


title: HISTORY
content:
<i>tor-resolve</i> has been an integral part of the Tor project's suite of utilities since its early days. Its development paralleled the growth of the Tor network itself, providing a crucial tool for users to perform DNS lookups with the same anonymity and privacy assurances offered by Tor for regular network traffic. It was developed to address the specific need for secure and private name resolution, complementing tools like <i>torify</i> by handling DNS queries explicitly over Tor rather than relying on system-wide DNS configurations.


title: DESCRIPTION
content:
TorChat is a peer-to-peer instant messenger utilizing Tor hidden services for anonymous and decentralized communication. It enables users to chat securely without revealing their IP addresses, routing all traffic through the Tor network. Each user is identified by a unique Tor hidden service address (a .onion address). Running TorChat creates a local hidden service, allowing direct, encrypted message exchange with others via their .onion addresses, bypassing central servers. Designed for simplicity and privacy, it was a pioneering effort in anonymous messaging. However, its development has largely ceased, rendering it outdated and potentially insecure for current use. Despite its obsolescence, TorChat holds historical significance as an early and influential example of a truly anonymous messenger application.


title: CAVEATS
content:
TorChat is an unmaintained and outdated project, which may pose significant security risks due to unpatched vulnerabilities. It may not function correctly with modern Tor versions or operating systems without manual adjustments. As a graphical application, its utility from the command line is limited to launching the GUI. It relies entirely on the Tor network; Tor must be running and accessible for TorChat to function.


title: GUI APPLICATION
content:
TorChat functions primarily as a graphical user interface (GUI) application. Executing the command typically launches an interactive window rather than providing command-line output or functionality for scripting.


title: DEPENDENCIES
content:
Successful operation of TorChat requires the Tor daemon to be actively running and accessible on the system. It also depends on a compatible Python runtime environment.


title: HISTORY
content:
Developed by Bernd Ulmann in 2007, TorChat emerged as one of the first truly anonymous and decentralized instant messengers. Its appeal lay in its serverless design, simplicity, and reliance on Tor hidden services for privacy-preserving communication. Written primarily in Python, TorChat gained a user base among privacy advocates. However, active development largely ceased around 2014-2015, leading to its eventual deprecation. Lack of ongoing maintenance resulted in compatibility issues with newer Tor versions and unaddressed security flaws, making it obsolete. More modern and actively developed alternatives have since superseded it.


title: PARAMETERS
content:
<b><i>COMMAND</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The command or executable to be run, whose network traffic will be routed through Tor.<br><br><b><i>ARGUMENT</i>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Any arguments that need to be passed to the <i>COMMAND</i>.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the help message and exits.<br><br><b><b>-u</b>, <b>--unrestrict</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs <b>torsocks</b> to allow the specified command to use Tor, even if it is normally blacklisted in the configuration file. Useful for overriding default restrictions.<br><br><b><b>-i</b>, <b>--ignore</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ignores the <b>TORSOCKS_CONF_FILE</b> environment variable, forcing <b>torsocks</b> to use its default configuration file locations (e.g., <i>~/.torsocks.conf</i> or <i>/etc/torsocks.conf</i>).<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose logging output from <b>torsocks</b>, useful for debugging connection issues or understanding its behavior.<br><br><b><b>-l</b> <i>LIBRARY</i>, <b>--library</b> <i>LIBRARY</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative path to the <b>torsocks</b> shared library (e.g., <i>libtorsocks.so</i>) to be preloaded.<br><br><b><b>-C</b> <i>CONFIG_FILE</i>, <b>--conf</b> <i>CONFIG_FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses an alternative <b>torsocks</b> configuration file instead of the default ones. This allows for specific proxy settings or rules for a particular command.<br><br>


title: DESCRIPTION
content:
<b>torify</b> is a powerful command-line utility that simplifies routing the network traffic of almost any application through the Tor anonymity network. It acts as a convenient wrapper for the <b>torsocks</b> library, which transparently intercepts and redirects an application's outgoing TCP connections to a local Tor SOCKS proxy. This mechanism is crucial for enhancing privacy and anonymity by making it difficult to trace the origin of the network traffic.<br><br>It achieves this by leveraging the <b>LD_PRELOAD</b> environment variable to inject the <b>libtorsocks.so</b> shared library into the application's process. Consequently, most network-aware programs launched via <b>torify</b> will automatically attempt to route their connections through Tor, without requiring explicit SOCKS proxy configuration within the application itself.<br><br>While highly effective, users must be aware of potential limitations such as DNS leaks, especially if the application performs its own DNS resolution and <b>torsocks</b> is not properly configured to handle DNS requests via Tor. It is particularly valuable for command-line tools and scripts that lack built-in proxy support, providing an easy way to anonymize their network interactions.


title: CAVEATS
content:
<b>torify</b>, as a wrapper for <b>torsocks</b>, has several important caveats and limitations:<br><br><b>1. DNS Leaks:</b> While <b>torsocks</b> attempts to intercept DNS requests, some applications might perform their own DNS resolution in ways that bypass <b>torsocks</b>, leading to potential DNS leaks and revealing your real IP address.<br><b>2. UDP Traffic:</b> <b>torsocks</b> primarily handles TCP connections. UDP traffic is generally not routed through Tor and will likely leak.<br><b>3. Performance Impact:</b> Routing traffic through the Tor network inherently adds significant latency, which can slow down applications and transfers.<br><b>4. Not All Applications:</b> Highly complex applications or those using non-standard networking methods (e.g., raw sockets, specific kernel interfaces) may not function correctly or at all with <b>torify</b>.<br><b>5. SUID/SGID Binaries:</b> The <b>LD_PRELOAD</b> mechanism (which <b>torsocks</b> relies on) typically does not work with SUID or SGID binaries due to security restrictions.<br><b>6. Running Tor Daemon:</b> <b>torify</b> requires a running Tor daemon on the local system, accessible via its SOCKS proxy port (default 9050 or 9150 for Tor Browser bundle).


title: CONFIGURATION FILES
content:
<b>torsocks</b> (and thus <b>torify</b>) reads its configuration from specific files. The typical search order is: the file specified by the <b>TORSOCKS_CONF_FILE</b> environment variable, then <i>~/.torsocks.conf</i> in the user's home directory, and finally <i>/etc/torsocks.conf</i>. These files define the SOCKS proxy address, port, and rules for traffic routing.


title: HOW IT WORKS (LD_PRELOAD)
content:
<b>torify</b> works by setting the <b>LD_PRELOAD</b> environment variable to point to the <b>torsocks</b> shared library (e.g., <i>/usr/lib/libtorsocks.so</i>). When a program starts, the dynamic linker loads this library before any other, allowing <b>torsocks</b> to 'hook' or 'intercept' standard network functions. When the application tries to make a connection, <b>torsocks</b> redirects it through the Tor SOCKS proxy instead of directly to the internet.


title: HISTORY
content:
The concept behind <b>torify</b> and <b>torsocks</b> emerged from the need to easily anonymize network connections of existing applications without requiring them to have built-in SOCKS proxy support. <b>torsocks</b>, the underlying library, was developed to leverage the dynamic linker's <b>LD_PRELOAD</b> mechanism on Unix-like systems. This allows the interception of standard networking functions (like <i>connect()</i>, <i>getaddrinfo()</i>, etc.) and redirects them through a specified SOCKS proxy, typically Tor. <b>torify</b> was created as a simple shell script wrapper to make the invocation of <b>torsocks</b> more user-friendly, setting the necessary environment variables and directly executing the target command, thus simplifying its usage for anonymizing command-line tools.


title: SYNOPSIS
content:
<I>torsocks</I> [<B>options</B>] <I>command</I> [<I>command arguments</I>]<br>Example: <I>torsocks wget https://example.com</I>


title: PARAMETERS
content:
<b>--help, -h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display help information and exit.<br><br><b>--usage, -u</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a short usage message and exit.<br><br><b>--ignore-socks-errors, -i</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ignore SOCKS-related errors and allow connections to go direct if the proxy fails.<br><br><b>--quiet, -q</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress all <b>torsocks</b> messages, only displaying output from the wrapped command.<br><br><b>--verbose, -v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display verbose <b>torsocks</b> messages, useful for debugging.<br><br><b>--stream-isolation, -s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable stream isolation for the wrapped process. This forces new Tor circuits for all connections, preventing linkability.<br><br><b>--proxy-ip <ip>, -p <ip></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the SOCKS proxy IP address. Overrides configuration file settings.<br><br><b>--proxy-port <port>, -a <port></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the SOCKS proxy port. Overrides configuration file settings.<br><br><b>--proxy-username <username>, -d <username></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the username for SOCKS authentication.<br><br><b>--proxy-password <password>, -o <password></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the password for SOCKS authentication.<br><br><b>--resolve-host-remotely, -R</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Resolve hostnames remotely via the SOCKS proxy (SOCKS5 only). This is the default behavior when using Tor.<br><br><b>--no-resolve-host-remotely, -N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Resolve hostnames locally before sending the IP address to the SOCKS proxy.<br><br><b>--status, -S</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the status of the <b>torsocks</b> library and exit. Useful for checking if <b>torsocks</b> is properly configured.<br><br>


title: DESCRIPTION
content:
<b>torsocks</b> is a utility that allows applications to transparently use a SOCKS proxy, typically <I>Tor</I>, for their network connections.<br>It works by intercepting network-related system calls, such as <I>connect()</I> and <I>getaddrinfo()</I>, from the program it wraps. Instead of making direct connections to the Internet, <b>torsocks</b> redirects these calls through a configured SOCKS proxy, ensuring that the application's traffic is routed through the proxy.<br>This is particularly useful for applications that do not natively support SOCKS proxies, or for users who wish to enforce proxy usage for specific commands without altering their configuration.<br>By default, <b>torsocks</b> attempts to use <I>Tor</I> as its proxy, looking for its configuration in files like <I>/etc/torsocks.conf</I> or <I>~/.torsocks.conf</I>.<br>It supports both SOCKS4 and SOCKS5 protocols, providing a convenient way to enhance privacy and security for command-line tools and scripts.


title: CAVEATS
content:
<ul><li><b>torsocks</b> primarily handles TCP connections. UDP proxying is generally not reliable or fully supported.</li><li>It cannot safely proxy setuid/setgid binaries due to security implications and library preloading restrictions.</li><li>Not all network operations can be reliably intercepted. For example, some low-level ICMP or raw socket operations might bypass the proxy.</li><li><b>torsocks</b> relies on library preloading (<I>LD_PRELOAD</I>), which might conflict with other preloaded libraries or specific system configurations.</li></ul>


title: CONFIGURATION FILE
content:
<b>torsocks</b> uses a configuration file, typically <I>/etc/torsocks.conf</I> or <I>~/.torsocks.conf</I>, to define the SOCKS proxy details and other behaviors. This allows for persistent settings without needing to specify them on the command line every time.<br>The default configuration usually points to a Tor SOCKS proxy running on <I>127.0.0.1:9050</I> or <I>127.0.0.1:9150</I> (for Tor Browser bundle).


title: ENVIRONMENT VARIABLES
content:
Many <b>torsocks</b> behaviors and settings can also be controlled via environment variables, such as <I>TORSOCKS_CONF_FILE</I> (to specify a custom config file), <I>TORSOCKS_DEBUG</I>, <I>TORSOCKS_ALLOW_INBOUND</I>, and <I>TORSOCKS_ALLOW_UDP</I>. These provide flexible ways to modify <b>torsocks</b>'s operation for specific use cases or scripts.


title: SYNOPSIS
content:
<b>toshsat1800-irdasetup</b><br><i>This command is typically run without arguments to initiate the IrDA setup process.</i>


title: PARAMETERS
content:
<b><i>(No standard parameters)</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The script is typically executed without specific command-line options. Its configuration is often hardcoded or determined by system-wide IrDA settings, simplifying its use for end-users.<br><br>


title: DESCRIPTION
content:
<i><b>toshsat1800-irdasetup</b></i> is a specialized Linux utility or script designed to configure and enable the Infrared Data Association (IrDA) port on Toshiba Satellite 1800 series laptops. These machines, prominent in the early 2000s, featured an IrDA transceiver for short-range wireless communication, primarily for file transfer with mobile phones, PDAs, or other IrDA-enabled devices.<br><br>The script's primary function is to load necessary kernel modules (such as <i>irda</i>, <i>ircomm_tty</i>, <i>irlpt_client</i>, and potentially hardware-specific modules like <i>toshiba_acpi</i>) and set up the IrDA subsystem. This typically involves configuring the I/O base address and IRQ settings for the infrared port, allowing the operating system to communicate with the hardware. Given its highly specific hardware and era, this command is largely obsolete for modern systems but was crucial for enabling infrared connectivity on these particular legacy machines running Linux. It often served as a simplified wrapper around more complex <i>modprobe</i> and <i>setserial</i>-like commands for IrDA configuration.


title: CAVEATS
content:
<b>Legacy Hardware:</b> This command is specific to very old Toshiba Satellite 1800 series laptops, which are no longer common.<br><b>Obsolete Technology:</b> IrDA technology has largely been superseded by Wi-Fi and Bluetooth for wireless communication.<br><b>Kernel Module Dependencies:</b> Requires specific kernel modules (e.g., <i>irda</i>, <i>ircomm_tty</i>, <i>irlpt_client</i>) to be available and loadable, which may not be present in modern Linux kernels.<br><b>Root Privileges:</b> Typically requires root privileges to load kernel modules and configure hardware.<br><b>Security:</b> IrDA is an unencrypted, short-range communication method, offering limited security.


title: TYPICAL OPERATION
content:
When executed, <i><b>toshsat1800-irdasetup</b></i> typically performs a series of steps:<br><i>1. Checks for necessary kernel modules.<br>2. Loads IrDA-specific modules (<i>irda</i>, <i>ircomm_tty</i>, <i>irlpt_client</i>) and potentially hardware-specific modules like <i>toshiba_acpi</i> if required for power management or device enumeration.<br>3. Configures the IrDA port's I/O address and IRQ, often by passing parameters to kernel modules or using utilities like <i><b>irattach</b></i>.<br>4. Brings up the IrDA network interface, making the infrared port ready for communication.


title: TROUBLESHOOTING
content:
Issues with <i><b>toshsat1800-irdasetup</b></i> often stem from:<br><i>- Missing or incompatible kernel modules for the specific Linux kernel version.<br>- Incorrect I/O or IRQ settings, leading to hardware conflicts.<br>- BIOS settings disabling the IrDA port.<br>- The IrDA port being physically damaged or not correctly detected by the system.<br>Debugging usually involves checking <i><b>dmesg</b></i> output after attempting to run the script and manually verifying module loading with <i><b>lsmod</b></i>.


title: HISTORY
content:
IrDA (Infrared Data Association) technology was prominent in the late 1990s and early 2000s, providing short-range optical wireless communication. During this era, many laptops, including the Toshiba Satellite 1800 series, integrated IrDA transceivers. The <i><b>toshsat1800-irdasetup</b></i> script emerged as a solution for Linux users to configure these specific infrared ports, as standard kernel module loading and IrDA utility setup could be complex and hardware-dependent. It was likely a community-driven script or part of specific Linux distribution's hardware support packages tailored for these particular Toshiba models, predating the more plug-and-play nature of modern wireless technologies. Its usage declined rapidly with the advent of more ubiquitous and higher-bandwidth wireless standards like Wi-Fi and Bluetooth.


title: PARAMETERS
content:
<b><b>-brightness</b> <i>value</i> / <b>-brt</b> <i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the display brightness. <i>value</i> typically ranges from 0 to 7, or a percentage, depending on the specific Toshiba model and <i>toshset</i> version.<br><br><b><b>-fan</b> {<b>on</b>|<b>off</b>|<b>auto</b>} / <b>-fanon</b> / <b>-fanoff</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls the cooling fan operation. Options might include turning the fan <b>on</b>, <b>off</b>, or setting it to <b>auto</b>matic control, if supported by the hardware.<br><br><b><b>-lcd</b> {<b>on</b>|<b>off</b>}</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manages the state of the internal LCD panel, allowing it to be turned <b>on</b> or <b>off</b>.<br><br><b><b>-tv</b> {<b>on</b>|<b>off</b>}</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls the TV-out port, enabling or disabling external TV output.<br><br><b><b>-help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief help message and available options for the specific <i>toshset</i> version.<br><br>


title: DESCRIPTION
content:
<i>toshset</i> was a Linux command-line utility primarily designed for <b>Toshiba</b> laptop owners to interact with and configure hardware-specific settings. It leveraged ACPI (Advanced Configuration and Power Interface) to provide control over features unique to Toshiba's proprietary hardware. Users could employ <i>toshset</i> to adjust screen brightness, manage fan behavior (e.g., turn on/off), control the LCD panel, or manage external video outputs (like TV-out).<br><br>Developed during a period when Linux's generic hardware support was less mature, <i>toshset</i> served as an essential bridge, allowing users to fine-tune their Toshiba laptops' performance and power management beyond what the standard kernel modules offered. Its usage has significantly declined with advancements in generic ACPI support within the Linux kernel and the emergence of more universal hardware control tools.


title: CAVEATS
content:
<i>toshset</i> is a highly <b>vendor-specific</b> utility, designed exclusively for certain Toshiba laptop models. It is largely deprecated and may not function correctly, or at all, on modern Toshiba hardware or contemporary Linux distributions. Using it improperly could potentially lead to hardware malfunctions or unexpected system behavior. Users should exercise caution and ensure compatibility before attempting to use it.


title: VENDOR SPECIFICITY
content:
It is crucial to understand that <i>toshset</i> is not a generic Linux command. Its functionality is tied directly to the specific ACPI implementations found in certain Toshiba laptop BIOSes. This means its behavior, available options, and even its very existence can vary wildly between different Toshiba models and manufacturing years.


title: MODERN ALTERNATIVES
content:
For modern Linux systems and hardware, generic tools like <i>xbacklight</i> (for brightness), kernel modules (e.g., <i>snd_hda_intel</i> for audio, various <i>acpi_video</i> drivers), and direct ACPI interface files (e.g., in <i>/sys/class/backlight/</i> or <i>/proc/acpi/</i>) are typically used for hardware control instead of vendor-specific utilities like <i>toshset</i>.


title: HISTORY
content:
The <i>toshset</i> utility gained prominence in the early 2000s, especially among Linux users attempting to run distributions on Toshiba laptops. It was developed to address limitations in the Linux kernel's direct support for Toshiba's proprietary hardware features. As the Linux kernel matured and ACPI support became more robust and standardized across various hardware vendors, the necessity and relevance of <i>toshset</i> diminished. It is now rarely maintained or found in modern Linux repositories, being largely superseded by generic ACPI tools and better kernel integration.


title: PARAMETERS
content:
<b><b>--fullscreen</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Start playback in fullscreen mode.<br><br><b><b>--play-pause</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Toggle playback state (play/pause).<br><br><b><b>--next</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Play the next item in the current playlist.<br><br><b><b>--previous</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Play the previous item in the current playlist.<br><br><b><b>--mute</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Mute or unmute the audio output.<br><br><b><b>--volume</b> &lt;<i>level</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the playback volume from 0 to 10.<br><br><b><b>--seek</b> &lt;<i>seconds</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Seek to a specific time position in the current media, specified in seconds.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the Totem version information and exit.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show a comprehensive list of command-line options.<br><br>


title: DESCRIPTION
content:
Totem, officially known as "Videos" in recent GNOME versions, is the default media player for the GNOME desktop environment. It provides a simple, user-friendly interface for playing a wide variety of video and audio formats, thanks to its backend reliance on the powerful GStreamer multimedia framework. This robust foundation ensures broad compatibility with numerous codecs and container formats, from common MP4 and MKV videos to various audio streams. Key features include comprehensive playlist management, seamless fullscreen playback for an immersive viewing experience, and robust support for DVDs and VCDs. It also offers advanced subtitle display capabilities, allowing users to load external subtitle files and adjust their appearance. Furthermore, Totem has the ability to stream online content, making it a versatile tool for both local and network media. It integrates seamlessly with the GNOME desktop, leveraging features like thumbnail generation for video files in the file manager and supporting global media keys for convenient control. While primarily designed as a video player, it handles audio playback competently, making it a versatile general-purpose media application suitable for everyday use.


title: CAVEATS
content:
Totem is primarily designed for the GNOME desktop environment; its integration and functionality might be reduced in other desktop environments. Playback of certain media formats relies heavily on installed <I>GStreamer</I> plugins; users might need to install additional codec packages (e.g., <I>gstreamer-plugins-bad</I>, <I>gstreamer-plugins-ugly</I>) to ensure broad compatibility. The command-line interface provides only basic playback control, with most advanced features accessed via the graphical user interface.


title: HISTORY
content:
Totem was originally developed by Bastien Nocera and was first released around 2003 as part of the GNOME project. It quickly became the default movie player for GNOME, replacing previous players. Over the years, it has evolved significantly, particularly with the migration to the <I>GStreamer</I> multimedia framework for its backend, which allowed for extensive codec support and flexible plugin architecture. In more recent GNOME versions (starting with GNOME 3.10), it was rebranded to "Videos" to better reflect its primary function as the central application for managing and playing video content within the desktop environment, although the executable name <I>totem</I> remains. Its development continues as part of the broader GNOME ecosystem, focusing on integration, simplicity, and multimedia compatibility.


title: PARAMETERS
content:
<b>-s <I>SIZE</I>, --size=<I>SIZE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the maximum dimension (width or height) of the generated thumbnail in pixels. The aspect ratio is typically preserved, and the image will be scaled to fit within this size.<br><br><b>-t <I>TIME</I>, --time=<I>TIME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the time, in seconds, from the beginning of the video where the frame should be captured for the thumbnail. For example, a value of '10' would capture a frame 10 seconds into the video.<br><br><b>-a, --aspect-correction</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ensures the thumbnail maintains the video's original aspect ratio. If the specified size does not match the video's aspect, black bars (letterboxing or pillarboxing) will be added to fill the space.<br><br><b>-o <I>FILE</I>, --output-file=<I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path for the output thumbnail image file. This option is often redundant if the output file is provided as the second positional argument on the command line.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief help message, showing available options and usage examples, then exits.<br><br><b>-v, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the version information of the <b>totem-video-thumbnailer</b> utility and exits.<br><br>


title: DESCRIPTION
content:
<b>totem-video-thumbnailer</b> is a utility program designed to create static image thumbnails from video files. It's primarily used by desktop environments, such as GNOME's Nautilus file manager, to display visual previews of video content without opening the full player. The command takes an input video file, seeks to a specified time, captures a frame, and then scales it to a desired size before saving it as an output image file (commonly JPEG). It leverages the GStreamer multimedia framework for its decoding capabilities, supporting a wide range of video formats. This tool automates the process of generating rich visual cues for video collections, making it easier for users to identify and manage their video content at a glance without launching a full media player.


title: CAVEATS
content:
This command relies heavily on a properly configured GStreamer installation with all necessary video decoder plugins. Without the correct plugins for a given video format, thumbnail generation may fail or produce a blank image. It is typically invoked by desktop environments in the background via the XDG Thumbnailing Specification and is not commonly used directly by end-users for manual thumbnail creation. Performance can vary based on video complexity, resolution, and system hardware, potentially consuming significant CPU resources for high-resolution video processing.


title: USAGE CONTEXT
content:
While it's a command-line tool, <b>totem-video-thumbnailer</b> is primarily designed to be called by desktop environments or file managers (like Nautilus) for automatic thumbnail generation. It's part of the standard XDG Thumbnailing Specification, meaning it's invoked by a system-wide mechanism to create thumbnails on demand when a file manager requests them, rather than being a tool frequently executed manually by users.


title: HISTORY
content:
<b>totem-video-thumbnailer</b> has been an integral part of the GNOME desktop environment's multimedia capabilities since the early 2000s, evolving alongside the Totem video player (now GNOME Videos). Its development has consistently aimed to improve user experience by providing quick visual access to video content within file managers, reducing the need to open full video players just for previewing. It serves as a backend component conforming to the `Shared MIME-info` database's thumbnail specifications and the XDG Thumbnailing Specification.


title: SYNOPSIS
content:
<b>touch</b> [<i>OPTION</i>]... <i>FILE</i>...<br><i>OPTION</i>: Represents zero or more command-line options that modify <i>touch</i>'s behavior.<br><i>FILE</i>: Represents one or more file paths. If a file doesn't exist, <i>touch</i> creates it by default.


title: PARAMETERS
content:
<b>-a, --time=atime, --time=access, --time=use</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Changes only the <i>access</i> time (the time the file was last read).<br><br><b>-c, --no-create</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents <i>touch</i> from creating any files that do not already exist.<br><br><b>-d STRING, --date=STRING</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses the specified <i>STRING</i> as the timestamp instead of the current time. <i>STRING</i> can be in various formats (e.g., 'YYYY-MM-DD HH:MM:SS', 'yesterday').<br><br><b>-h, --no-dereference</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Affects symbolic links themselves rather than the files they point to. This option is only effective on systems that support changing timestamps of symbolic links.<br><br><b>-m, --time=mtime, --time=modify</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Changes only the <i>modification</i> time (the time the file's content was last changed).<br><br><b>-r FILE, --reference=FILE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses the access and modification times from the specified <i>FILE</i> as the new timestamps for the target files.<br><br><b>-t STAMP</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses the timestamp specified by <i>STAMP</i>, which must be in the format <code>[[CC]YY]MMDDhhmm[.ss]</code>.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message and exits.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays version information and exits.<br><br>


title: DESCRIPTION
content:
<i>touch</i> is a fundamental Unix/Linux command used to update the access and modification timestamps of files and directories. When executed without any options on an existing file, it sets both the access time (last read) and modification time (last content change) to the current system time. A key feature of <i>touch</i> is its ability to create new, empty files if the specified file does not already exist. This makes it an efficient way to quickly generate placeholder files or ensure a file's presence for subsequent operations. It is extensively employed in scripting and build systems (such as Make) to manage dependencies, often forcing recompilations or re-executions based on file age. Users have the flexibility to specify custom timestamps or use the timestamps of another reference file for more precise control.


title: CAVEATS
content:
<ul><li>The <code>--no-dereference</code> (<code>-h</code>) option's effectiveness on symbolic links depends on the underlying file system and operating system support; some systems do not allow direct modification of symlink timestamps.</li><li>When using <code>-d</code> or <code>-t</code>, ensure the timestamp format is correct; otherwise, <i>touch</i> may fail or produce unexpected results.</li><li>Modifying timestamps can impact build systems, caching mechanisms, or backup processes that rely on file ages.</li><li><i>touch</i> requires appropriate permissions to modify existing files or create new ones in a directory.</li></ul>


title: DEFAULT BEHAVIOR
content:
When <i>touch</i> is executed on an existing file without any options (like <code>-a</code> or <code>-m</code>), it updates <i>both</i> the access and modification times to the current system time. If the specified file does not exist, it is created as an empty file, and its timestamps are set to the current time.


title: TIMESTAMPS EXPLAINED
content:
<ul><li><i>Access Time (atime)</i>: The last time the file's data was read.</li><li><i>Modification Time (mtime)</i>: The last time the file's content was changed.</li><li><i>Change Time (ctime)</i>: The last time the file's metadata (e.g., permissions, owner, or link count) or content was changed. While <i>touch</i> directly modifies <i>atime</i> and <i>mtime</i>, <i>ctime</i> is automatically updated whenever <i>atime</i>, <i>mtime</i>, or other file metadata changes.</li></ul>


title: HISTORY
content:
The <i>touch</i> command has been a standard utility in Unix-like operating systems since their early development. It is a part of the POSIX standard, ensuring its consistent presence and behavior across various Unix and Linux distributions. Its fundamental simplicity and utility for file manipulation, particularly in conjunction with build tools like Makefiles and scripting for managing file dependencies, have solidified its continued relevance and widespread use in system administration, software development workflows, and automation tasks.


title: PARAMETERS
content:
<b>-t <theme></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a visual theme for the presentation.<br><br><b>-s <size></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the text size or layout for the slides.<br><br><b>-c</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Cycles through available themes or color schemes during the presentation.<br><br><b>--loop</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Automatically loops the presentation once all slides have been shown.<br><br><b>--list-themes</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a list of all available themes.<br><br><b>--list-sizes</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a list of all available sizes.<br><br><b>--slide <num></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts the presentation at a specific slide number.<br><br><b>--width <cols></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Overrides the detected terminal width in columns.<br><br><b>--height <rows></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Overrides the detected terminal height in rows.<br><br><b>--config <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a custom configuration file to use.<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output for debugging or detailed information.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the program's version information.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the help message and available options.<br><br>


title: DESCRIPTION
content:
<i>tpp</i> (Terminal Presentation Program) is a command-line utility designed to display text and Markdown files as interactive slide presentations directly within your terminal emulator. It's particularly useful for technical presentations, code walk-throughs, or simple information sharing without needing a graphical environment.<br><br>The program interprets a specified input file, typically using <b>---</b> (three hyphens) as a separator to delineate individual slides. It supports basic Markdown formatting, allowing users to include headings, lists, <b>bold</b>/<i>italic</i> text, and code blocks. <i>tpp</i> offers various customization options, including different themes and sizes, to control the appearance of the presentation. Users can navigate through slides using arrow keys, spacebar, or other defined keybindings. It's a lightweight alternative to graphical presentation software, emphasizing simplicity and efficiency for text-based content.


title: CAVEATS
content:
<i>tpp</i> is not a standard, built-in Linux command; it needs to be installed separately, typically from a package manager (e.g., AUR on Arch Linux, or compiled from source) or as part of a specific project. Its functionality is limited to text-based presentations and does not support embedded images, complex animations, or advanced multimedia typical of graphical presentation software. The exact features and available options may vary slightly depending on the specific version or distribution of the <i>tpp</i> program.


title: SLIDE SEPARATION
content:
Each slide in a <i>tpp</i> presentation is typically separated by a line containing only three hyphens (<b>---</b>). Any content between these separators constitutes a single slide.


title: KEYBINDINGS
content:
Users can navigate through slides using common keybindings like the spacebar, right arrow key (next slide), left arrow key (previous slide), and <b>q</b> to quit the presentation.


title: THEMING AND CUSTOMIZATION
content:
<i>tpp</i> supports various built-in themes and sizes for visual customization. Advanced users can often define custom themes or modify existing ones through configuration files, allowing for tailored aesthetics.


title: HISTORY
content:
The <i>tpp</i> (Terminal Presentation Program) referred to here was primarily developed by Martin Geisler (majewsky on GitHub). It emerged as a lightweight, open-source solution for delivering presentations directly from the command line, catering to developers, system administrators, and anyone who prefers a minimalist, text-centric workflow. Its development has focused on simplicity, broad terminal compatibility, and efficient rendering of Markdown content. While not part of the standard Linux utility set, it gained popularity within certain technical communities as a practical tool for code-centric talks and documentation review.


title: SYNOPSIS
content:
<b>tput</b> [<i>-T type</i>] <i>capname</i> [<i>parameters ...</i>]<br><b>tput</b> [<i>-T type</i>] <i>init</i><br><b>tput</b> [<i>-T type</i>] <i>reset</i><br><b>tput</b> [<i>-T type</i>] <i>longname</i><br><b>tput</b> <i>-S</i>


title: PARAMETERS
content:
<b><b>-T</b> <i>type</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the <i>type</i> of terminal. If omitted, the value of the <i>TERM</i> environment variable is used. This allows querying capabilities for a terminal other than the current one.<br><br><b><i>capname</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The symbolic name of a terminal capability as defined in the <i>terminfo</i> database. Examples include <i>clear</i> (clear screen), <i>bold</i> (start bold mode), <i>cols</i> (number of columns), <i>lines</i> (number of rows), <i>cup</i> (cursor position).<br><br><b><i>parameters ...</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Numeric parameters required by certain capabilities. For example, <i>cup</i> (cursor position) requires row and column parameters: <b>tput cup</b> <i>row col</i>.<br><br><b><b>init</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the terminal initialization strings. This is often used when a terminal session begins to set up terminal modes.<br><br><b><b>reset</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the terminal reset strings. This is useful for restoring the terminal to a default state, often after an application has left it in an undesirable mode.<br><br><b><b>longname</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the full verbose name for the current terminal type.<br><br><b><b>-S</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Standard mode. Allows reading multiple capability names from standard input, one per line. This is more efficient for batch processing multiple capabilities as it avoids re-initializing the <i>terminfo</i> database for each query.<br><br>


title: DESCRIPTION
content:
<b>tput</b> is a utility that allows shell scripts to interrogate the <i>terminfo</i> database and send setup strings to the terminal. It provides a portable way to perform terminal-dependent operations, such as clearing the screen, moving the cursor, changing text attributes (bold, underline, color), or querying terminal dimensions. Instead of embedding hardcoded escape sequences, scripts use <b>tput</b> with symbolic capability names (e.g., <i>clear</i>, <i>bold</i>, <i>cols</i>). <b>tput</b> looks up the corresponding escape sequence or value for the current terminal type (specified by the <i>TERM</i> environment variable or <b>-T</b> option) in the <i>terminfo</i> database and prints it to standard output. This makes scripts more robust and adaptable to different terminal emulators and configurations.


title: CAVEATS
content:
<b>tput</b> relies entirely on the <i>terminfo</i> database. If the database is incomplete or incorrect for a specific terminal type, <b>tput</b> may not behave as expected or may report unknown capabilities.<br>The output of <b>tput</b> is raw terminal escape sequences. It should not be displayed directly to the user but rather passed to the terminal for interpretation.<br>Exit codes: <b>tput</b> returns 0 on success, 1 for unknown capabilities, 2 for usage errors, and 3 for no information about the terminal type. Scripts should check these codes.


title: USING IN SHELL SCRIPTS
content:
<b>tput</b> is invaluable for making shell scripts portable across different terminal types. Instead of hardcoding escape sequences, scripts can use <b>tput</b> to get the correct sequence for the current terminal. For example, <I>BOLD=$(tput bold)</I>, <I>NORMAL=$(tput sgr0)</I>, <I>echo "${BOLD}This is bold.${NORMAL}"</I>.


title: EXIT STATUS
content:
The exit status of <b>tput</b> provides important feedback:<br><b>0</b>: The capability is valid and printed.<br><b>1</b>: The capability is invalid or not defined for the terminal.<br><b>2</b>: Usage error.<br><b>3</b>: No information about the terminal type (e.g., <i>TERM</i> not set or database entry missing).


title: HISTORY
content:
<b>tput</b> is part of the <I>ncurses</I> (new curses) project, which is an open-source reimplementation of the System V Release 4.0 (SVr4) curses library. The original <b>tput</b> command was available in System V Unix, providing a command-line interface to the <i>terminfo</i> database. Its development has mirrored that of <I>ncurses</I> itself, focusing on portability, robustness, and extending support for modern terminal features. It superseded older <i>termcap</i>-based utilities due to the more structured <i>terminfo</i> database.


title: SYNOPSIS
content:
<I>command_to_pipe_output</I> | <B>tqdm</B> <I>[options]</I><br><I><B>tqdm</B> [options] &lt; filename</I><br><I><B>tqdm</B> [options] --total N --unit 'item'</I>


title: PARAMETERS
content:
<b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show a help message and exit, detailing all available options.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the <I>tqdm</I> program's version number and exit.<br><br><b>--total N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manually set the total number of expected iterations or units. Essential if input size cannot be inferred.<br><br><b>--unit UNIT</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the string description of the unit (e.g., 'B' for bytes, 'it' for iterations).<br><br><b>--unit_scale</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable automatic scaling of the unit suffix (e.g., 'K', 'M', 'G' for bytes).<br><br><b>--bytes</b><br>&nbsp;&nbsp;&nbsp;&nbsp;A shortcut for `--unit B --unit_scale --unit_divisor 1024`, ideal for tracking byte streams.<br><br><b>--desc DESC</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add a string prefix to the progress bar, useful for identifying different progress bars.<br><br><b>--ascii</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the use of an ASCII-only progress bar, suitable for terminals that don't support Unicode characters.<br><br><b>--ncols N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the width of the entire output line for the progress bar. Auto-detected if not specified.<br><br><b>--colour COLOUR</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the color of the progress bar (e.g., 'red', 'green', or hex codes like '#00ff00').<br><br><b>--disable</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Completely disable the progress bar, useful for non-interactive scripts or when output needs to be clean.<br><br><b>--leave</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Keep the progress bar displayed on screen after completion, instead of clearing it.<br><br><b>--position N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the line offset to print the progress bar, useful for managing multiple or nested progress bars.<br><br>


title: DESCRIPTION
content:
<I>tqdm</I> is a fast, extensible, and highly customizable progress bar library. Primarily developed for Python, it also offers a convenient command-line interface, making it versatile for various scripting and data processing tasks. When used via the command line, <I>tqdm</I> wraps around other commands, displaying a live progress bar that tracks the flow of data through a pipeline or the processing of a file. It automatically estimates remaining time, throughput, and completion percentage, providing immediate visual feedback for long-running operations. The library is designed to have minimal overhead, ensuring it doesn't significantly impede the performance of the task it's monitoring. Its name, <I>tqdm</I>, is derived from the Arabic word "taqaddum" (تقدّم), meaning "progress."


title: CAVEATS
content:
While powerful, <I>tqdm</I>'s command-line interface is primarily a wrapper for its Python library. Its effectiveness depends on proper piping or explicit input (`--total`, `--file`). For extremely short-lived commands or very high iteration rates, the overhead of the progress bar might be noticeable. Additionally, <I>tqdm</I> outputs the progress bar to <I>stderr</I> by default, which can be unexpected for users assuming <I>stdout</I> for all output.


title: OUTPUT STREAM
content:
By design, <I>tqdm</I> prints the progress bar itself to the standard error stream (<I>stderr</I>). This allows the actual data or output from the piped command to flow through standard output (<I>stdout</I>) undisturbed, which is crucial for correct pipeline operation and redirection.


title: EXTENSIVE CUSTOMIZATION
content:
Beyond basic progress, <I>tqdm</I> offers deep customization options. Users can define custom bar formats, integrate their own metrics, and control every visual aspect from color to unit representation. This makes it highly adaptable for complex scenarios where specific information needs to be conveyed to the user about the ongoing process.


title: HISTORY
content:
<I>tqdm</I> was first introduced in 2014 by Noam Yorav-Raphael, quickly becoming a popular choice for displaying progress bars in Python applications due to its simplicity and rich feature set. Its development has been community-driven, leading to continuous enhancements in performance, customizability, and display options. The command-line utility, allowing <I>tqdm</I> to be used directly in shell pipelines, was added later, extending its utility beyond pure Python scripts and making it accessible to a wider range of users for general data processing tasks.


title: SYNOPSIS
content:
<I>trace-cmd</I> <I>command</I> [<I>options</I>] [<I>arguments</I>]<br><br><b>Examples:</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>trace-cmd</I> <I>record</I> -e <I>syscalls</I> -e <I>sched</I> <I>my_program</I><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>trace-cmd</I> <I>report</I><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>trace-cmd</I> <I>list</I> -e


title: PARAMETERS
content:
<b><I>record</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Records trace data based on specified events, functions, or plugins. Often used with a command to execute for tracing duration.<br><br><b><I>report</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Analyzes and displays recorded trace data from a <I>trace.dat</I> file. Offers various display options and filters.<br><br><b><I>list</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists available <I>ftrace</I> events, plugins, functions, or instances, providing an overview of what can be traced.<br><br><b><I>start</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts kernel tracing without executing a specific command. Trace data is written to the kernel's trace buffer.<br><br><b><I>stop</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stops ongoing kernel tracing. Use after <I>trace-cmd start</I>.<br><br><b><I>extract</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Extracts the contents of the kernel's trace buffer into a <I>trace.dat</I> file. Use after <I>trace-cmd stop</I>.<br><br><b><I>reset</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables all <I>ftrace</I> events and clears the kernel's trace buffer, effectively resetting the tracing system.<br><br><b><I>options</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays various <I>ftrace</I> options and their current status.<br><br><b><I>check</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs checks on the <I>ftrace</I> environment to ensure it's properly configured and available.<br><br><b><I>-v</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases verbosity of output. Can often be specified multiple times for more detailed information.<br><br><b><I>-d</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable debug mode for the trace-cmd command itself.<br><br><b><I>-h</I>, <I>--help</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message for the general command or a specific subcommand.<br><br>


title: DESCRIPTION
content:
<b>trace-cmd</b> is a powerful user-space utility that acts as a front-end for the Linux kernel's <I>ftrace</I> tracing framework. <br><br>It significantly simplifies the process of collecting, analyzing, and reporting kernel trace data, which can be invaluable for debugging performance issues, understanding kernel behavior, and developing new features. While <I>ftrace</I> itself exposes a complex set of files in <I>/sys/kernel/debug/tracing</I>, <b>trace-cmd</b> abstracts away much of this complexity, allowing users to specify events, start and stop tracing, and generate human-readable reports with simple commands. <br><br>It supports various tracing capabilities, including function tracing, event tracing (e.g., syscalls, scheduling, disk I/O), and specific plugins. The data is typically recorded into a binary file (defaulting to <I>trace.dat</I>) which can then be parsed and displayed in various formats.


title: CAVEATS
content:
<b>trace-cmd</b> typically requires root privileges to operate, as it interacts directly with kernel tracing facilities. <br><br>Tracing can introduce overhead, especially if a large number of events are enabled or if the trace buffer is small, potentially affecting system performance. <br><br>The size of the generated <I>trace.dat</I> files can grow very large quickly, requiring significant disk space.


title: TRACING EVENTS AND PLUGINS
content:
<b>trace-cmd</b> can trace a vast array of kernel events, which are categorized (e.g., <I>syscalls</I>, <I>sched</I>, <I>irq</I>, <I>block</I>, <I>net</I>). Users can enable specific events using the <I>-e</I> option with <I>trace-cmd record</I> (e.g., <I>-e syscalls -e sched:sched_switch</I>). Additionally, it supports various <I>ftrace</I> plugins like <I>function</I> (for tracing all kernel function calls), <I>function_graph</I> (for showing call graphs), and <I>printk</I>.


title: OUTPUT FILES AND FORMATS
content:
By default, <b>trace-cmd</b> saves recorded data to a binary file named <I>trace.dat</I> in the current directory. This file is highly optimized for storage and can be compressed. The <I>trace-cmd report</I> command then parses this binary file and presents the data in a human-readable text format. The <I>trace-cmd report</I> command itself has many options to filter, sort, and format the output, including options to display timestamps, process IDs, CPU numbers, and specific event fields.


title: KERNEL BUFFERS AND INSTANCES
content:
<b>trace-cmd</b> primarily interacts with the kernel's ring buffer for tracing data. When using <I>trace-cmd start/stop/extract</I>, it manages this buffer directly. For more complex tracing scenarios, <I>ftrace</I> supports tracing instances (separate ring buffers), which <b>trace-cmd</b> can also manage via specific options like <I>-i</I> or <I>-N</I> with some subcommands to specify an instance name or max buffer size.


title: HISTORY
content:
<b>trace-cmd</b> was developed by Steven Rostedt, a prominent Linux kernel developer and one of the primary maintainers of the <I>ftrace</I> kernel tracing infrastructure. It emerged as a necessary user-space tool to provide a more intuitive and feature-rich interface to <I>ftrace</I>, abstracting away the complexities of directly manipulating the <I>/sys/kernel/debug/tracing</I> filesystem. It's part of the <I>kernel-tools</I> package in most Linux distributions and has been widely adopted by developers and system administrators for kernel-level debugging and analysis.


title: PARAMETERS
content:
<b><i>DESTINATION</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The target hostname or IP address to trace.<br><br><b><b>-I</b>, <b>--icmp</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use ICMP ECHO for probes (requires root privileges).<br><br><b><b>-T</b>, <b>--tcp</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use TCP SYN for probes, to a specific port (requires root privileges).<br><br><b><b>-U</b>, <b>--udp</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use UDP datagrams for probes (default method).<br><br><b><b>-n</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not resolve IP addresses to hostnames (numeric output).<br><br><b><b>-p</b> <i>PORT</i>, <b>--port=</b><i>PORT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set destination port for UDP/TCP probes.<br><br><b><b>-m</b> <i>MAX_TTL</i>, <b>--max-hops=</b><i>MAX_TTL</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the maximum number of hops (TTL) to probe.<br><br><b><b>-w</b> <i>TIMEOUT</i>, <b>--wait=</b><i>TIMEOUT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the time in seconds to wait for a response to a probe.<br><br><b><b>-q</b> <i>NPROBES</i>, <b>--queries=</b><i>NPROBES</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the number of probes to send per hop.<br><br><b><b>-g</b> <i>GATEWAY</i>, <b>--gateway=</b><i>GATEWAY</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a loose source route gateway (for some networks).<br><br><b><b>-s</b> <i>SOURCE_IP</i>, <b>--source=</b><i>SOURCE_IP</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the source IP address.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print verbose output.<br><br>


title: DESCRIPTION
content:
<i><b>traceroute</b></i> is a network diagnostic utility that displays the route (path) and measures transit delays of packets across an Internet Protocol (IP) network. It achieves this by sending packets with progressively increasing Time-To-Live (TTL) values. When a packet's TTL reaches zero, an intermediate router sends an ICMP "Time Exceeded" message back to the source.<br><br>By analyzing these ICMP responses, <i><b>traceroute</b></i> maps out the sequence of routers (hops) traversed by the packets from the source to the destination. It typically sends three probes per TTL level, providing Round-Trip Times (RTTs) for each hop, which helps in identifying network latency and potential bottlenecks. It supports various probe types, including UDP (default), ICMP echo, and TCP SYN, to bypass firewalls or test specific service paths.


title: CAVEATS
content:
Certain <i><b>traceroute</b></i> options (like ICMP or TCP SYN probes) require root privileges because they use raw sockets.<br>Firewalls often block ICMP messages or specific UDP/TCP ports, which can cause <i><b>traceroute</b></i> to display asterisks (*) for hops that are actually reachable.<br>Network address translation (NAT), load balancers, and asymmetric routing can cause <i><b>traceroute</b></i> output to be misleading or show seemingly incorrect paths.<br>ICMP rate limiting on routers can also lead to incomplete or delayed responses.


title: HOW IT WORKS
content:
<i><b>traceroute</b></i> sends a series of packets to the destination, starting with a Time-To-Live (TTL) value of 1. Each router that forwards the packet decrements the TTL. When TTL reaches 0, the router discards the packet and sends an ICMP "Time Exceeded" message back to the source.<br><br>The next set of packets is sent with a TTL of 2, then 3, and so on. This process continues until the packets reach the destination, or the maximum TTL (max hops) is reached. For each hop, <i><b>traceroute</b></i> records the IP address of the router that sent the ICMP "Time Exceeded" message and the Round-Trip Time (RTT) for the probe to that router.


title: OUTPUT INTERPRETATION
content:
The output typically shows a numbered list of hops.<br>Each line represents a hop (a router or device on the path).<br>The first column is the hop number.<br>Subsequent columns show the RTT (in milliseconds) for each probe sent to that hop, along with the hostname (if resolved) and IP address of the responding device.<br>An asterisk (<b>*</b>) indicates that no response was received for a probe, which can be due to packet loss, firewall blocking, or the device not sending ICMP responses.<br>"!H" or "!N" indicates a host/network unreachable error, meaning the destination or network could not be reached beyond that point.


title: HISTORY
content:
<i><b>traceroute</b></i> was originally written by Van Jacobson at Lawrence Berkeley National Laboratory (LBL) in 1987. It quickly became an indispensable tool for network administrators and users to diagnose connectivity issues and visualize network paths. Its fundamental principle of using Time-To-Live (TTL) values remains the core of its operation, though various implementations and probe types (UDP, ICMP, TCP) have been added over time to enhance its utility in diverse network environments.


title: PARAMETERS
content:
<b><b>-I</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses ICMPv6 ECHO_REQUEST packets as probes. This is often the default probe type for IPv6 traceroute.<br><br><b><b>-U</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses UDP packets as probes. The destination port is usually incremented for each probe.<br><br><b><b>-T</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses TCP SYN packets as probes. This can be useful for tracing paths through firewalls that might block ICMPv6 or UDP.<br><br><b><b>-p</b> <i>port</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the destination port for UDP or TCP probes. Default is often 33434 for UDP.<br><br><b><b>-m</b> <i>max_hops</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum number of hops (IPv6 Hop Limit) to probe. Default is typically 30.<br><br><b><b>-q</b> <i>nqueries</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the number of probe packets to send for each hop. Default is 3.<br><br><b><b>-w</b> <i>waittime</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the time in seconds to wait for a response to a probe. Default is usually 5 seconds.<br><br><b><b>-n</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not resolve IP addresses to hostnames. This speeds up the process by avoiding DNS lookups.<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, providing more detailed information about the operation.<br><br><b><b>-s</b> <i>source_addr</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the source IPv6 address to use for outgoing probe packets.<br><br><b><b>-f</b> <i>first_hop</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the starting hop limit (TTL) from which to begin probing. Default is 1.<br><br>


title: DESCRIPTION
content:
<b>traceroute6.iputils</b> is a fundamental network diagnostic utility within the Linux <b>iputils</b> package, specifically designed to trace the route that IPv6 packets take to reach a destination host. It operates by sending probe packets with progressively increasing IPv6 hop limits (analogous to Time To Live in IPv4). When a router receives a packet with a hop limit of 1 and forwards it, it decrements the hop limit to 0 and, by standard, returns an ICMPv6 "Time Exceeded" message to the source. By analyzing these messages and the time taken for their return, <b>traceroute6</b> constructs a map of the network path and measures the round-trip time to each intermediate hop.<br><br>This command is invaluable for identifying network bottlenecks, diagnosing routing loops, pinpointing points of failure, or understanding connectivity issues within an IPv6 network. It supports various probe types, including ICMPv6 Echo Request, UDP, and TCP SYN, allowing flexibility to bypass certain firewall rules or test specific service paths.


title: CAVEATS
content:
Firewalls and network devices may block ICMPv6 "Time Exceeded" messages or probe packets, leading to "* * *" (no response) for certain hops.<br>Round-trip times displayed might not be precise, especially on busy routers, and can vary due to network congestion or asymmetric routing.<br>The command traces the forward path; the return path may differ, especially in complex network topologies.<br>Some network devices might not return appropriate ICMPv6 messages, causing the trace to appear to stop prematurely.


title: PROBE TYPES AND USAGE
content:
<b>traceroute6.iputils</b> offers different probe types to cater to various network scenarios:<br><b>ICMPv6 probes</b> (default with <b>-I</b>): Most common, often used for basic reachability and hop detection. Can be blocked by firewalls.<br><b>UDP probes</b> (with <b>-U</b>): Can sometimes bypass simple ICMP blocks, but may hit UDP port-unreachable blocks at the destination.<br><b>TCP SYN probes</b> (with <b>-T</b>): Excellent for testing paths to specific services, as it mimics actual connection attempts. Requires root privileges and is more likely to pass through firewalls designed to allow web traffic, for example.


title: INTERPRETING OUTPUT
content:
The output lists each hop along the path, its IP address (and optionally hostname), and the round-trip times for the probes sent to that hop. For example:<br><i>1  2001:db8::1 (2001:db8::1)  1.234 ms  1.567 ms  1.345 ms</i><br>indicates the first hop at IP 2001:db8::1 with three response times.<br><br>An asterisk (<b>*</b>) indicates no response was received for a probe, which can signify packet loss, a non-responding router, or a firewall blocking the probes.<br><br>The final hop usually represents the destination host itself. If the trace doesn't complete to the destination, it often points to a problem on the last responding hop or beyond.


title: HISTORY
content:
The original <b>traceroute</b> utility was developed by Van Jacobson in 1987, quickly becoming an indispensable tool for network diagnostics on Unix-like systems. The <b>iputils</b> package on Linux provides a robust and widely used implementation of <b>traceroute</b>. With the advent of IPv6, the utility was extended to support the new protocol, often as <b>traceroute -6</b> or a dedicated <b>traceroute6</b> command. The <b>iputils</b> version adapted the core principles of using progressively increasing hop limits and ICMP Time Exceeded messages to the IPv6 standard (ICMPv6 and Hop Limit), ensuring similar diagnostic capabilities for modern IPv6 networks.


title: SYNOPSIS
content:
<b>traefik</b> [OPTIONS]<br><b>traefik</b> [COMMAND] [OPTIONS]<br><br>The <b>traefik</b> command is primarily used to start the Traefik daemon, applying a configuration through command-line flags, environment variables, or a configuration file. It can also be used with subcommands for specific operations.<br><br><i>Example:</i><br><b>traefik</b> --configfile=/etc/traefik/traefik.yml --entrypoints.web.address=:80


title: PARAMETERS
content:
<b>--configfile=<path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the main configuration file (TOML or YAML).<br><br><b>--entrypoints.<name>.address=<address></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines a listening port and protocol for incoming requests (e.g., <code>--entrypoints.web.address=:80</code>).<br><br><b>--providers.docker.exposedByDefault=<bool></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets whether services discovered by the Docker provider are exposed by default (e.g., <code>--providers.docker.exposedByDefault=false</code>).<br><br><b>--log.level=<level></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the logging level (e.g., DEBUG, INFO, WARN, ERROR).<br><br><b>--api.dashboard=<bool></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables or disables the Traefik API and dashboard (e.g., <code>--api.dashboard=true</code>).<br><br><b>--certificatesresolvers.<name>.acme.email=<email></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Email address used for ACME (Let's Encrypt) certificate resolution (e.g., <code>--certificatesresolvers.myresolver.acme.email=user@example.com</code>).<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the command or a specific subcommand.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the Traefik version information.<br><br>


title: DESCRIPTION
content:
Traefik is an open-source Edge Router that makes publishing your services a fun and easy experience. It receives requests on behalf of your system and finds out which components are responsible for handling them. Unlike traditional reverse proxies, Traefik is designed to be highly dynamic, automatically discovering services in various environments such as <i>Docker</i>, <i>Kubernetes</i>, <i>Mesos</i>, and more, without requiring manual configuration updates. This makes it particularly well-suited for microservices architectures where services are ephemeral and change frequently.<br><br>Key features include automatic service discovery, support for multiple providers, load balancing algorithms, SSL/TLS termination (including automatic <i>Let's Encrypt</i> certificate management), circuit breakers, retries, and comprehensive metrics. It integrates seamlessly with existing infrastructure, simplifying the routing of incoming requests to the correct backend services. Traefik aims to be simple, efficient, and auto-configuring, significantly reducing operational complexity for modern, cloud-native applications.


title: CAVEATS
content:
<i>Complex Configuration</i>: Traefik offers extensive configuration options, which can be overwhelming for new users. Proper understanding of its routing concepts (Entrypoints, Routers, Services, Middlewares) is crucial.<br><br><i>Dependency on Providers</i>: Its dynamic nature heavily relies on integration with orchestration platforms (e.g., Docker, Kubernetes). Misconfigurations in these environments can impact Traefik's ability to discover and route traffic.


title: CONFIGURATION METHODS
content:
Traefik can be configured using a variety of methods, which are applied in a specific precedence order: <b>command-line flags</b> (highest precedence), <b>environment variables</b>, and <b>configuration files</b> (TOML or YAML). This flexibility allows for diverse deployment scenarios.


title: CORE CONCEPTS
content:
Understanding Traefik requires familiarity with its core components:<br><i>Entrypoints</i>: Listeners for incoming requests.<br><i>Routers</i>: Analyze incoming requests and determine which service to forward them to.<br><i>Services</i>: Define how to reach your actual applications.<br><i>Middlewares</i>: Apply transformations or logic to requests before they reach a service (e.g., authentication, rate limiting).


title: HISTORY
content:
Traefik was first released in 2016 by <i>Containous</i> (now <i>Traefik Labs</i>). It rapidly gained popularity in the cloud-native ecosystem due to its unique ability to automatically discover and configure routing for services deployed in dynamic environments like <i>Docker Swarm</i> and <i>Kubernetes</i>. Its design addressed a critical need for efficient and simplified edge routing in microservices architectures, establishing it as a leading solution in its domain.


title: SYNOPSIS
content:
<b>trans</b> [<i>OPTIONS</i>] [<i>TEXT...</i>]<br><b>trans</b> <i>:</i>&lt;<i>target_lang</i>&gt; [<i>TEXT...</i>]<br><b>trans</b> &lt;<i>source_lang</i>&gt;<i>:</i>&lt;<i>target_lang</i>&gt; [<i>TEXT...</i>]<br><b>trans</b> <i>-i</i>


title: PARAMETERS
content:
<b><b>-b</b>, <b>--brief</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output only the translation, without additional details.<br><br><b><b>-s</b> &lt;<i>lang</i>&gt;, <b>--source</b> &lt;<i>lang</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the source language for translation.<br><br><b><b>-t</b> &lt;<i>lang</i>&gt;, <b>--target</b> &lt;<i>lang</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the target language for translation.<br><br><b><b>-i</b>, <b>--interactive</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enter an interactive translation shell for continuous input.<br><br><b><b>-l</b>, <b>--list-languages</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;List all supported language codes.<br><br><b><b>-V</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the version information of <b>trans</b>.<br><br><b><b>--speak</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Speak the translated text (requires an external text-to-speech engine).<br><br><b><b>--detect</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Detect and display the language of the provided text.<br><br><b><b>-e</b> &lt;<i>engine</i>&gt;, <b>--engine</b> &lt;<i>engine</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the translation engine to use (e.g., <i>google</i>, <i>bing</i>, <i>yandex</i>).<br><br><b><b>--set-proxy</b> &lt;<i>url</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set a proxy for network requests (e.g., <i>http://host:port</i>).<br><br>


title: DESCRIPTION
content:
The <b>trans</b> command, also known as <i>translate-shell</i>, is a powerful command-line utility for translating text.<br>It provides quick access to various online translation services like Google Translate, Bing Translator, and Yandex.Translate, directly from your terminal.<br>Users can effortlessly translate words, phrases, or entire sentences without opening a web browser.<br>Key features include automatic source language detection, translation to multiple target languages, dictionary lookups, and text-to-speech output for translations.<br>It also offers an interactive shell mode for continuous translation sessions.<br><b>trans</b> is highly efficient for developers, writers, or anyone needing instant translation capabilities within their workflow.


title: CAVEATS
content:
<b>trans</b> relies on unofficial APIs of online translation services, which means its functionality can occasionally break due to changes in those services.<br>An active internet connection is required for most operations.<br>Users should be aware of potential rate limiting or temporary IP blocking by translation providers.<br>Privacy is a consideration, as text is sent to third-party services for processing.<br>Translation accuracy is dependent on the underlying machine translation engine.


title: INTERACTIVE SHELL
content:
By invoking <b>trans</b> with the <b>-i</b> or <b>--interactive</b> option, users enter a continuous translation environment.<br>This mode allows for entering multiple lines of text one after another for translation without re-executing the command each time, making it ideal for extended translation sessions.


title: LANGUAGE CODES
content:
<b>trans</b> utilizes standard ISO 639-1 two-letter language codes for specifying source and target languages (e.g., '<i>en</i>' for English, '<i>fr</i>' for French, '<i>es</i>' for Spanish).<br>A comprehensive list of supported languages and their corresponding codes can be retrieved using the <b>-l</b> or <b>--list-languages</b> option.


title: INSTALLATION
content:
<b>trans</b> can typically be installed on Linux distributions via their package managers (e.g., <i>apt-get install translate-shell</i> on Debian/Ubuntu, <i>dnf install translate-shell</i> on Fedora).<br>It can also be installed using <i>pip</i> (Python package manager) for users who prefer that method, or by cloning its Git repository and following manual installation instructions.


title: HISTORY
content:
The <b>trans</b> command, officially known as <i>translate-shell</i>, is an open-source project primarily written in Bash and Awk.<br>It began as a simple script to leverage Google Translate from the command line and has evolved significantly into a feature-rich, community-driven tool.<br>Its development has focused on providing a robust and convenient CLI interface for translation, adapting to changes in web services and expanding support for various translation engines and advanced features like text-to-speech and interactive modes.


title: SYNOPSIS
content:
<B>transfersh</B> [<I>options</I>] <I>file(s)</I>...<br><B>transfersh</B> [<I>options</I>] <I>directory/</I><br><B>transfersh</B> [<I>options</I>] <I>- < input</I>


title: PARAMETERS
content:
<b>file(s)</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path(s) to the file(s) you want to upload. Multiple files can be uploaded, often compressed into a zip archive by the server.<br><br><b>directory/</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uploads the contents of a directory. The server will typically zip the directory before serving.<br><br><b>-</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads input from standard input (stdin) for text uploads.<br><br><b>-s, --short-url</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Optional</I>. Requests a shorter URL from the server, often using a custom domain.<br><br><b>-p, --progress</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Optional</I>. Displays a progress bar during the upload process.<br><br><b>-g, --gist</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Optional</I>. Primarily for text files. Uploads the content as a gist (pastebin-like format) if the server supports it.<br><br><b>-e <time>, --expires <time></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Optional</I>. Sets an expiration time for the uploaded file. Examples: <I>1h</I> (1 hour), <I>1d</I> (1 day), <I>1w</I> (1 week).<br><br><b>-d <count>, --downloads <count></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Optional</I>. Sets the maximum number of times the file can be downloaded before it's removed.<br><br><b>-t, --no-progress</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Optional</I>. Suppresses the upload progress bar.<br><br><b>--upload-only</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Optional</I>. Uploads the file and prints the URL, but does not attempt to open it in a web browser.<br><br><b>--no-browser</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Optional</I>. Similar to <I>--upload-only</I>, prevents opening the URL in a browser.<br><br><b>--zip</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Optional</I>. Forces zipping of single files or multiple files/directories even if not strictly necessary.<br><br>


title: DESCRIPTION
content:
<I>transfersh</I> is a convenient command-line utility for uploading files to the <I>transfer.sh</I> file-sharing service. It provides a simple and quick way to share files directly from your terminal, receiving a URL in return that can be easily shared with others. The <I>transfer.sh</I> service supports various file types, and <I>transfersh</I> streamlines the upload process, often wrapping <I>curl</I> commands to interact with the service's API. It's particularly useful for quickly sharing logs, scripts, or small binaries during troubleshooting sessions or collaborative work, without the need for complex setup or authentication. Files are typically encrypted during transfer and can be configured with download limits or expiration times.


title: CAVEATS
content:
<I>transfersh</I> is not a standard, pre-installed Linux command; it typically requires manual installation of a shell script or a separate client. It relies on the external <I>transfer.sh</I> service, which means:<br><B>Service Dependency:</B> The availability and reliability of file sharing depend entirely on the <I>transfer.sh</I> service.<br><B>Privacy:</B> Uploaded files are publicly accessible via the generated URL. While transfers are encrypted (HTTPS), the files are stored unencrypted on the server and are accessible to anyone with the link. Do not share sensitive or private information.<br><B>Retention Policy:</B> Files are subject to the service's default retention policy (often 14 days) or specified expiration. They are not permanently stored.<br><B>File Size Limits:</B> The service may impose limits on individual file sizes or total storage, though these are generally generous for casual use.


title: INSTALLATION
content:
<I>transfersh</I> is typically installed by downloading a shell script and making it executable. A common method is:<br><I>curl -L https://transfer.sh/transfersh > ~/.local/bin/transfersh && chmod +x ~/.local/bin/transfersh</I><br>Ensure <I>~/.local/bin</I> is in your system's <I>PATH</I> environment variable for easy access.


title: USAGE EXAMPLES
content:
<B>1. Upload a single file:</B><br><I>transfersh myfile.txt</I><br><br><B>2. Upload a file with a 7-day expiration:</B><br><I>transfersh -e 7d mydocument.pdf</I><br><br><B>3. Upload multiple files, forcing zipping:</B><br><I>transfersh --zip file1.log file2.conf</I><br><br><B>4. Upload content from stdin:</B><br><I>echo "Hello, world!" | transfersh -</I>


title: SELF-HOSTING TRANSFER.SH
content:
The <I>transfer.sh</I> service is open-source, allowing users to host their own private instances. This can be beneficial for organizations with strict privacy requirements or a need for custom configurations, reducing reliance on the public service.


title: HISTORY
content:
The <I>transfer.sh</I> file-sharing service was created by <B>Remco Verhoef</B> as a simple, free, and open-source solution for quick file sharing. It gained popularity due to its command-line friendly nature, allowing users to upload files directly from their terminal using tools like <I>curl</I>. The <I>transfersh</I> command-line client itself is often a community-developed shell script wrapper that simplifies the <I>curl</I> commands, making it even more user-friendly. Its design philosophy emphasizes simplicity and efficiency for temporary file sharing, quickly becoming a go-to tool for developers and system administrators.


title: SYNOPSIS
content:
<b>transmission-remote</b> [<I>host</I>:<I>port</I>] [<I>options</I>] [<I>torrent-ID</I>... | <I>file</I> | <I>magnet-URI</I>]


title: PARAMETERS
content:
<b><b>--add</b> <I>file</I>|<I>url</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add a new torrent to the daemon from a local .torrent file path or a magnet URI/URL.<br><br><b><b>--list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;List all torrents currently managed by the daemon, showing their status, size, progress, and speed.<br><br><b><b>--torrent</b> <I>ID</I>|<I>hash</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify one or more torrents by their ID number (from <b>--list</b>) or info hash for subsequent operations (e.g., stop, remove).<br><br><b><b>--remove</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remove the specified torrents from the daemon. Use with <b>--torrent</b>.<br><br><b><b>--start</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Start the specified torrents, or all paused torrents if no specific torrents are given.<br><br><b><b>--stop</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stop the specified torrents, or all active torrents if no specific torrents are given.<br><br><b><b>--verify</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Initiate a local data verification check for the specified torrents.<br><br><b><b>--info</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show detailed information about the specified torrents, including trackers, files, and peer details.<br><br><b><b>--move</b> <I>directory</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Move the data files of the specified torrents to a new download directory.<br><br><b><b>--port</b> <I>port</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the RPC port of the Transmission daemon to connect to (default is 9091).<br><br><b><b>--auth</b> <I>user</I>:<I>pass</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provide username and password for authentication with the Transmission daemon's RPC interface.<br><br><b><b>--global-info</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the current global configuration settings of the Transmission daemon.<br><br><b><b>--global-set</b> <I>key</I>=<I>value</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set a global configuration option for the daemon (e.g., download-dir, upload-limit).<br><br>


title: DESCRIPTION
content:
<i>transmission-remote</i> is a versatile command-line tool designed to manage the <b>Transmission BitTorrent client's daemon</b> (<i>transmission-daemon</i>). It allows users to interact with the daemon's RPC interface to perform a wide range of operations, including adding new torrents, listing active downloads, starting, stopping, and removing torrents, verifying data, and modifying both individual torrent settings and global daemon configurations.<br><br>This utility is particularly valuable for users running Transmission on headless servers, NAS devices, or in automated scripting environments where a graphical user interface is unavailable or undesirable. It provides full programmatic control over torrent activity, making it a cornerstone for efficient and flexible torrent management.


title: CAVEATS
content:
The <i>transmission-daemon</i> service must be running for <i>transmission-remote</i> to function.<br>If the daemon requires authentication, the <b>--auth</b> option must be used, or credentials can be stored in environment variables (TR_AUTH, TR_USERNAME, TR_PASSWORD) or the configuration file.<br>Using <i>transmission-remote</i> from untrusted networks without proper security measures (like VPN or SSH tunneling) is discouraged due to potential security risks to your daemon.


title: REMOTE ACCESS AND AUTOMATION
content:
<i>transmission-remote</i> is ideal for controlling torrents on a remote server. It's frequently used in shell scripts for automating torrent downloading workflows, such as adding torrents from RSS feeds, managing download directories, or pausing/resuming torrents based on network conditions or time of day.


title: CONFIGURATION MANAGEMENT
content:
Beyond basic torrent operations, <i>transmission-remote</i> allows full control over the daemon's global settings. This includes setting download and upload limits, configuring port forwarding, managing blocklists, and defining alternative download directories, offering comprehensive administrative capabilities from the command line.


title: HISTORY
content:
The Transmission BitTorrent client project began in 2005, aiming for a lightweight and user-friendly experience. As part of its design philosophy to be modular, the project developed <i>transmission-daemon</i> for server environments and <i>transmission-remote</i> as its primary command-line interface for interaction. This separation allowed Transmission to be widely adopted on various platforms, from desktop Linux to embedded systems like NAS devices, solidifying <i>transmission-remote</i>'s role as a powerful tool for headless torrent management.


title: SEE ALSO
content:
transmission-daemon(1), transmission-cli(1), transmission-create(1), transmission-show(1), aria2c(1), rtorrent(1)


title: PARAMETERS
content:
<b><b>-f</b> <i>&lt;script&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Execute the specified <i>script</i> when the torrent finishes downloading and seeding. This can be used for automation.<br><br><b><b>-g</b> <i>&lt;port&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the global peer listening port. This is the TCP port Transmission uses to communicate with other peers on the BitTorrent network.<br><br><b><b>-m</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not seed after the download is complete; exit immediately once the torrent finishes downloading. Useful for one-off downloads.<br><br><b><b>-u</b> <i>&lt;limit&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the maximum upload speed limit in Kilobytes per second (KB/s). A value of 0 means unlimited upload speed.<br><br><b><b>-d</b> <i>&lt;limit&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the maximum download speed limit in Kilobytes per second (KB/s). A value of 0 means unlimited download speed.<br><br><b><b>-w</b> <i>&lt;directory&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the directory where downloaded files should be saved. If not specified, files are typically saved to the current working directory.<br><br><b><b>-q</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable quiet mode, suppressing most output to the console, showing only critical messages.<br><br><b><b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message detailing available command-line options and then exit.<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the version number of <b>transmission-cli</b> and exit.<br><br>


title: DESCRIPTION
content:
<b>transmission-cli</b> is the command-line interface for the popular Transmission BitTorrent client. It allows users to download and upload torrents directly from the terminal without requiring a graphical user interface. This makes it ideal for use on servers, headless systems, or in scripts where automated torrent management is needed.<br><br>It supports essential BitTorrent features like magnet links, DHT, and peer exchange. Users can specify download directories, set bandwidth limits for both upload and download, and configure scripts to run upon torrent completion. Unlike the daemonized versions, <b>transmission-cli</b> typically runs for a single torrent and exits when the download is complete or after a period of seeding, making it perfect for one-off torrent operations.


title: CAVEATS
content:
<b>transmission-cli</b> is designed for single-torrent operations. It does not run as a persistent background service like <b>transmission-daemon</b>, nor does it manage multiple torrents concurrently from a single invocation. For continuous torrent management or handling many torrents, <b>transmission-daemon</b> paired with <b>transmission-remote</b> is the more appropriate solution.


title: USAGE WITH MAGNET LINKS
content:
<b>transmission-cli</b> can directly accept magnet URIs as arguments, removing the need to first download a .torrent file. Simply pass the magnet link string after the command, for example: <b>transmission-cli</b> <i>"magnet:?xt=urn:btih:hash..."</i>. Ensure the magnet link is properly quoted.


title: AUTOMATED DOWNLOAD & EXIT
content:
For scenarios where you only want to download a file and then stop immediately without seeding, utilize the <b>-m</b> option. This ensures the command exits gracefully upon download completion, which is particularly useful in automated scripts or for one-time downloads where continuous sharing is not required.


title: HISTORY
content:
<b>transmission-cli</b> is an integral part of the Transmission BitTorrent client project, which began development around 2005. It provides the foundational command-line interface, offering a simple and efficient way to interact with the BitTorrent network directly from the terminal. Its design emphasizes low resource consumption and ease of use in scripted or headless environments, contributing to Transmission's reputation as a lightweight and user-friendly client.


title: PARAMETERS
content:
<b><i>&lt;source-path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the file or directory that you want to create a torrent for. This is a mandatory argument and must point to valid content.<br><br><b><b>-o</b>, <b>--output</b> <i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the name and path for the generated <i>.torrent</i> file. If this option is omitted, the output file name will be derived from the source path with a <i>.torrent</i> extension (e.g., 'MyMovie.torrent' for 'MyMovie.mp4').<br><br><b><b>-c</b>, <b>--comment</b> <i>&lt;comment&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add a descriptive comment string to the <i>.torrent</i> file's metadata. This comment is often displayed by BitTorrent clients.<br><br><b><b>-p</b>, <b>--private</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Mark the torrent as 'private'. Private torrents disable DHT (Distributed Hash Table), PEX (Peer Exchange), and LSD (Local Peer Discovery) to enforce tracker-only peer discovery. This is commonly used on private trackers to ensure all traffic goes through the tracker for statistics and access control.<br><br><b><b>-t</b>, <b>--tracker</b> <i>&lt;url&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add a tracker URL to the torrent. This option can be used multiple times to include multiple trackers or tracker tiers. The URL should be a valid HTTP or UDP announce URL (e.g., 'http://tracker.example.com/announce').<br><br><b><b>-a</b>, <b>--announce-list</b> <i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Read a list of announce URLs from the specified file. Each URL should be on a new line, and tiers can be separated by a blank line.<br><br><b><b>-s</b>, <b>--piece-size</b> <i>&lt;size&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the size of each piece in the torrent. Common sizes include '256KB', '512KB', '1MB', '2MB', '4MB'. A larger piece size results in a smaller <i>.torrent</i> file but can make data integrity checks less granular and may impact sharing efficiency for very small files.<br><br><b><b>-n</b>, <b>--name</b> <i>&lt;name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Override the default name of the torrent. By default, the torrent name is derived from the source file or directory name.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a brief help message showing command usage and options, then exit.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the version information for the <b>transmission-create</b> utility and exit.<br><br>


title: DESCRIPTION
content:
The <b>transmission-create</b> command is a utility bundled with the Transmission BitTorrent client. Its primary function is to generate new <i>.torrent</i> files. These files contain essential metadata about the content being shared (files or directories), including their names, sizes, checksums of their pieces, and the addresses of tracker servers that help peers discover each other. This command is indispensable for anyone wishing to distribute content via the BitTorrent protocol, as it allows users to specify various parameters such as tracker URLs, comments, and whether the torrent should be private. It operates by scanning the specified files or directories and computing the necessary cryptographic hashes to include in the <i>.torrent</i> file, making the content discoverable and verifiable by other BitTorrent clients.


title: CAVEATS
content:
When creating torrents for very large files or extensive directories, the <b>transmission-create</b> command may take a significant amount of time to compute the checksums of all data pieces. Ensure the source files are not modified during this process, as any changes could result in an invalid <i>.torrent</i> file or corrupt data for peers. Private torrents (using <b>--private</b>) should only be used if explicitly required or supported by a specific tracker, as they intentionally limit peer discovery mechanisms that can otherwise improve availability.


title: PIECE SIZE SELECTION BEST PRACTICES
content:
Choosing an appropriate piece size is a critical decision. Smaller piece sizes result in larger <i>.torrent</i> files but allow for more granular verification and re-downloading of corrupt data, which can be beneficial for unreliable connections. Larger piece sizes create smaller <i>.torrent</i> files and are often suitable for very large single files or stable network environments. As a general rule, try to keep the <i>.torrent</i> file size manageable, but don't make pieces so large that minor corruptions require re-downloading huge blocks of data.


title: TRACKER URLS IMPORTANCE
content:
At least one tracker URL (using <b>-t</b>) is almost always required for the torrent to function correctly and for peers to find each other, unless it's intended exclusively for a DHT-only network (which is uncommon for new torrents). Including multiple trackers (or tracker tiers) can significantly improve redundancy and availability, especially if one tracker goes offline. Public trackers are widely available online, while private sharing often utilizes dedicated, invite-only trackers.


title: HISTORY
content:
The Transmission BitTorrent client project began its development in 2005, aiming to be a lightweight, cross-platform, and powerful client. The <b>transmission-create</b> command-line utility has been a fundamental component of the Transmission suite since its early versions, providing users with the essential capability to generate new torrent files, which is crucial for initiating content distribution within the BitTorrent ecosystem.


title: SEE ALSO
content:
transmission-remote(1), transmission-daemon(1), transmission-cli(1), transmission-show(1), transmission-edit(1)


title: PARAMETERS
content:
<b>-a <address>:<port></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an RPC bind address and port. Defaults to 0.0.0.0:9091.<br><br><b>-b</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable the blocklist.<br><br><b>-c <directory></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a directory for incomplete downloads.<br><br><b>-d <directory></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the default download directory.<br><br><b>-f</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run in the foreground, do not daemonize.<br><br><b>-g <directory></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the configuration directory. Defaults to <i>~/.config/transmission-daemon</i>.<br><br><b>-p <port></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the peer listening port.<br><br><b>-s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Start all torrents paused (same as --paused).<br><br><b>-t</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Test configuration file and exit.<br><br><b>-v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the version number and exit.<br><br><b>--auth <username>:<password></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify RPC authentication credentials.<br><br><b>--log-debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set log level to 'debug'.<br><br><b>--log-error</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set log level to 'error'.<br><br><b>--log-info</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set log level to 'info' (default).<br><br><b>--no-resource-limit</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not set a resource limit (e.g., maximum open files).<br><br><b>--pid-file <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the PID file path.<br><br><b>--rpc-bind-address <address></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the RPC bind address. Overrides -a address.<br><br><b>--rpc-port <port></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the RPC port. Overrides -a port.<br><br><b>--rpc-url <url></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the RPC URL path. Defaults to <i>/transmission/rpc</i>.<br><br><b>--rpc-whitelist <list></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Comma-separated list of IP addresses or ranges for RPC access.<br><br><b>--rpc-whitelist-enabled</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable the RPC whitelist.<br><br><b>--watch-dir <directory></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Watch a directory for new .torrent files.<br><br><b>--watch-dir-enabled</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable the watch directory feature.<br><br>


title: DESCRIPTION
content:
<b>transmission-daemon</b> is the daemon process for the popular Transmission BitTorrent client. It runs silently in the background, without a graphical user interface, making it ideal for servers, network-attached storage (NAS) devices, or headless systems. It efficiently manages torrent downloads and uploads, providing a low-resource footprint while maintaining essential BitTorrent functionalities. Users typically interact with <b>transmission-daemon</b> via its built-in web interface, the <b>transmission-remote</b> command-line tool, or third-party graphical clients that connect to its RPC (Remote Procedure Call) interface. It supports features like peer exchange, DHT, UPnP/NAT-PMP port forwarding, encryption, and blocklists. Its configuration is handled through a <i>settings.json</i> file, allowing for persistent settings and automation. Running as a daemon ensures that torrent activities continue even after the user logs out or closes their terminal session.


title: CAVEATS
content:
<b>Security Considerations:</b> By default, the RPC interface is often only bound to <i>localhost</i> (127.0.0.1). If configured to listen on all interfaces (0.0.0.0) without RPC authentication (<i>--auth</i>) and/or an RPC whitelist (<i>--rpc-whitelist</i>), it could be exposed to unauthorized access, allowing anyone on the network to control your Transmission instance.<br><br><b>Configuration Persistence:</b> Most settings are stored in <i>settings.json</i> within the configuration directory (often <i>~/.config/transmission-daemon/</i> or <i>/var/lib/transmission-daemon/</i>). Manually editing this file while the daemon is running can lead to lost changes or corrupted settings. Always stop the daemon before editing <i>settings.json</i>, or use the RPC interface to change settings.<br><br><b>Resource Usage:</b> While lightweight, running many active torrents or downloading at very high speeds can still consume significant CPU, memory, and disk I/O, especially on low-power devices.


title: CONFIGURATION FILE LOCATION
content:
The primary configuration file for <b>transmission-daemon</b> is <b><I>settings.json</I></b>. By default, it's located in the Transmission configuration directory, which is typically <i>~/.config/transmission-daemon/</i> for user-run instances, or <i>/var/lib/transmission-daemon/</i> when run as a system service. This file stores all daemon settings, including download directories, RPC credentials, port settings, and more.


title: RPC INTERFACE AND CONTROL
content:
<b>transmission-daemon</b> exposes an RPC (Remote Procedure Call) interface, usually on port 9091. This interface is how various clients communicate with and control the daemon. The official Transmission Web UI connects to this RPC, as does the <b>transmission-remote</b> command-line tool. Third-party applications and scripts can also interact with the daemon via this API.


title: RUNNING AS A SYSTEM SERVICE
content:
For continuous and reliable operation, it is highly recommended to run <b>transmission-daemon</b> as a system service (e.g., using <i>systemd</i> on Linux). This ensures it starts automatically on boot, runs with appropriate permissions, and can be managed easily with tools like <i>systemctl start transmission-daemon</i>, <i>systemctl stop transmission-daemon</i>, and <i>systemctl enable transmission-daemon</i>.


title: HISTORY
content:
Transmission was initially released in 2005, designed with a focus on being lightweight, simple, and cross-platform. The <b>transmission-daemon</b> component emerged as a natural extension of this philosophy, allowing the core BitTorrent engine to run as a background service without a graphical interface. This enabled its widespread adoption on servers, NAS devices, and embedded systems, providing a robust and efficient solution for headless torrent management. Its development has consistently aimed for a balance of features, performance, and low resource consumption, making it a preferred choice for many users needing a reliable BitTorrent daemon.


title: PARAMETERS
content:
<b><b>-a</b>, <b>--add</b> <i>&lt;file-or-folder&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a new <i>file</i> or <i>folder</i> to the torrent's file list. The path must be relative to the torrent's root directory.<br><br><b><b>-d</b>, <b>--delete</b> <i>&lt;file-or-folder&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deletes an existing <i>file</i> or <i>folder</i> from the torrent's file list. The path must match an existing entry.<br><br><b><b>-o</b>, <b>--out</b> <i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Saves the edited torrent to the specified <i>file</i>. If this option is omitted, the original torrent file is directly overwritten.<br><br><b><b>-p</b>, <b>--private</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Marks the torrent as private. Private torrents typically disable DHT (Distributed Hash Table) and PEX (Peer Exchange) to ensure all peer discovery goes through the tracker.<br><br><b><b>-P</b>, <b>--public</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Marks the torrent as public, allowing features like DHT and PEX for peer discovery, which are useful for trackerless torrents or when a tracker is down.<br><br><b><b>-t</b>, <b>--tracker</b> <i>&lt;url&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a new <i>tracker URL</i> to the torrent's announcement list. This option can be specified multiple times to add several trackers.<br><br><b><b>-T</b>, <b>--delete-tracker</b> <i>&lt;url&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deletes the specified <i>tracker URL</i> from the torrent's announcement list. This option can be used multiple times to remove various trackers.<br><br><b><b>-r</b>, <b>--replace-tracker</b> <i>&lt;oldurl&gt; &lt;newurl&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Replaces an <i>old tracker URL</i> with a <i>new tracker URL</i> in the torrent's announcement list. This option can be used multiple times for different replacements.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version number of <b>transmission-edit</b> and exits.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows a usage guide for the command, including available options and examples, then exits.<br><br>


title: DESCRIPTION
content:
The <b>transmission-edit</b> command-line utility allows users to modify the metadata within <i>.torrent</i> files. It provides functionalities to add or remove files and folders from a torrent's content list, manage tracker URLs by adding, deleting, or replacing them, and toggle the torrent's private or public status. This tool directly edits the specified <i>.torrent</i> file, or creates a new one if an output file is specified, making it useful for correcting or updating torrent information without needing to recreate the torrent from scratch.


title: CAVEATS
content:
When using <b>transmission-edit</b> without the <b>--out</b> option, the original <i>.torrent</i> file is directly overwritten. It is highly recommended to back up your torrent files before editing them to prevent accidental data loss. Modifying the file list (adding or deleting files/folders) in a torrent can change its info hash, which might necessitate that the BitTorrent client re-checks or re-hashes the torrent data.


title: USAGE EXAMPLES
content:
To modify a torrent, simply provide the path to the <i>.torrent</i> file(s) as argument(s).<br><br>To add a new tracker to 'my_movie.torrent': <br><i>transmission-edit -t "http://newtracker.com/announce" my_movie.torrent</i><br><br>To make 'my_album.torrent' private and save the changes to a new file named 'private_album.torrent':<br><i>transmission-edit -p -o private_album.torrent my_album.torrent</i><br><br>To replace an old tracker with a new one in 'my_archive.torrent':<br><i>transmission-edit -r "http://old.tracker.org" "http://new.tracker.org" my_archive.torrent</i>


title: HISTORY
content:
<b>transmission-edit</b> is an integral part of the Transmission BitTorrent client suite, a project known for its lightweight, fast, and feature-rich design. While its specific development timeline isn't extensively documented as a standalone utility, it has evolved alongside the main Transmission client. Its functionality reflects the common need for users to adjust or correct metadata in existing <i>.torrent</i> files, rather than requiring a full re-creation, making it a valuable tool for torrent management tasks.


title: SEE ALSO
content:
transmission-cli(1), transmission-create(1), transmission-daemon(1), transmission-remote(1), transmission-show(1)


title: PARAMETERS
content:
<b>-g, --config-dir &lt;directory&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the directory for configuration and torrent files.<br><br><b>-m, --minimized</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Start the application minimized to the system tray.<br><br><b>-p, --start-paused</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add new torrents in a paused state, preventing immediate download.<br><br><b>-f, --fullscreen</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Launch the application in fullscreen mode.<br><br><b>-e, --encryption-required</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Require encryption for all outgoing connections. This is generally for testing.<br><br><b>-v, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the version number of Transmission-GTK and exit.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show a summary of command-line options and exit.<br><br><b>[TORRENT_FILES...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more paths to .torrent files or magnet links to open and add.<br><br>


title: DESCRIPTION
content:
<I>transmission-gtk</I> is the official GTK+ graphical user interface for the popular <B>Transmission BitTorrent client</B>.<br><br>It provides a user-friendly and intuitive interface for managing BitTorrent downloads and uploads. Users can easily add new torrents, pause, resume, or remove existing ones, set download and upload speed limits, prioritize specific files within a torrent, and configure various network and privacy settings, including encryption and peer exchange. It operates as a standalone desktop application, directly interacting with the BitTorrent network to facilitate file sharing. Its design focuses on simplicity and efficiency, making it a preferred choice for many desktop Linux users.


title: CAVEATS
content:
<I>transmission-gtk</I> is a graphical client designed for desktop environments (like GNOME, XFCE, KDE). It requires an active X server or Wayland display. It is not suitable for headless server environments; for such use cases, <I>transmission-daemon</I> should be utilized.


title: HISTORY
content:
Transmission was initiated in 2005 with a focus on being a lightweight, open-source, and cross-platform BitTorrent client. The GTK+ interface has been one of its primary user interfaces since its early days, providing a native look and feel for Linux desktop environments and contributing significantly to Transmission's reputation for simplicity and efficiency.


title: SYNOPSIS
content:
transmission-remote [<i>host:port</i>] [<i>options</i>] [<i>torrent-IDs</i>]<br>transmission-remote [<i>options</i>]


title: PARAMETERS
content:
<b>-a <file|url></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add a new torrent from a .torrent file path or a magnet URI. E.g., <i>-a /path/to/file.torrent</i> or <i>-a 'magnet:?xt=urn:btih:...'</i><br><br><b>-r <ids></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remove specified torrents from the daemon. Use 'all' to remove all torrents. E.g., <i>-r 1,3,5</i> or <i>-r all</i><br><br><b>-s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show session statistics for the daemon, including global download/upload speeds, active torrent count, and total transferred data.<br><br><b>-l</b><br>&nbsp;&nbsp;&nbsp;&nbsp;List all torrents managed by the daemon, displaying their status, size, progress, and current speeds.<br><br><b>-f <ids></b><br>&nbsp;&nbsp;&nbsp;&nbsp;List files for the specified torrents. Add <i>--files</i> to see detailed file information within the torrent, including their download progress.<br><br><b>-t <ids></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Select torrents for subsequent operations. Can be a single ID, a range (e.g., <i>1-5</i>), a comma-separated list (e.g., <i>1,3,5</i>), or the word 'all'.<br><br><b>-p <ids></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pause specified torrents, stopping all transfers (download and upload) for them.<br><br><b>-S <ids></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Start specified torrents, resuming transfers if they were paused or stopped.<br><br><b>-v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the version of the <i>transmission-remote</i> client.<br><br><b>-g</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Get global Transmission daemon settings, such as download directory, speed limits, and port settings.<br><br><b>-G <option>=<value></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set global Transmission daemon settings. E.g., <i>-G download-dir=/path/to/downloads</i> or <i>-G dlimit-down=100</i>.<br><br><b>--auth <user:pass></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Authenticate with the daemon using the provided username and password for RPC access.<br><br><b>--exit</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Gracefully shut down the Transmission daemon that <i>transmission-remote</i> is connected to.<br><br><b>--incomplete-dir <dir></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When setting global options, specify the directory for incomplete downloads.<br><br><b>--bandwidth-limit-down <kbps></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When setting global options, set the global download speed limit in KB/s (kilobytes per second).<br><br><b>--bandwidth-limit-up <kbps></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When setting global options, set the global upload speed limit in KB/s (kilobytes per second).<br><br><b>--port <port></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the RPC port to connect to on the host, overriding the default 9091.<br><br><b>--ssl</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use SSL/TLS for the RPC connection, encrypting communication with the daemon.<br><br>


title: DESCRIPTION
content:
<i>transmission-remote</i> is a powerful command-line tool designed to interact with and control a running <i>Transmission BitTorrent daemon</i>. It provides a flexible way to manage torrents, view their status, add new downloads, remove completed ones, and configure global settings without needing a graphical user interface. This makes it ideal for headless servers, automation scripts, or users who prefer a terminal-based workflow. It communicates with the daemon via its RPC (Remote Procedure Call) interface, allowing for both local and remote management of your BitTorrent activity, offering comprehensive control over your downloads and uploads.


title: CAVEATS
content:
<i>transmission-remote</i> requires a running <i>transmission-daemon</i> instance to connect to. Ensure the daemon is configured to accept RPC connections, and if necessary, whitelist the IP address of the client running <i>transmission-remote</i> or provide correct authentication credentials. If the daemon is not running or not accessible (e.g., due to firewall rules), the command will fail to connect.


title: CONNECTING TO THE DAEMON
content:
By default, <i>transmission-remote</i> attempts to connect to <i>localhost:9091</i>. You can specify a different host and port as the first argument, e.g., <i>transmission-remote myhost.example.com:9091</i>, or simply <i>transmission-remote 192.168.1.10</i> (defaults to port 9091).


title: TORRENT ID SPECIFICATION
content:
Many commands that operate on specific torrents (e.g., pause, start, remove) accept <i>torrent-IDs</i>. This can be a single number (e.g., <i>1</i>), a comma-separated list of numbers (e.g., <i>1,3,5</i>), a range of numbers (e.g., <i>1-5</i>), or the keyword <i>all</i> to apply the command to every torrent currently managed by the daemon.


title: AUTHENTICATION
content:
If the <i>transmission-daemon</i> is configured to require authentication (username and password), you must provide these credentials. This can be done using the <i>--auth</i> option (e.g., <i>--auth myuser:mypassword</i>) or by setting the <i>TR_AUTH</i> environment variable. For convenience, you can also use a <i>.netrc</i> file for stored credentials.


title: HISTORY
content:
<i>transmission-remote</i> is an integral part of the <i>Transmission BitTorrent client</i> project, which began development in 2005. It was created to provide a lightweight, cross-platform client that is easy to use and manage. The remote control functionality, including <i>transmission-remote</i>, has been a core feature from early on, allowing users to run the daemon on a server (e.g., a home media server or a VPS) and control it from various devices or through scripts, significantly enhancing its utility for server environments and automation.


title: PARAMETERS
content:
<b><b>-m</b>, <b>--magnet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the magnet URI for the torrent.<br><br><b><b>-i</b>, <b>--info</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the info hash of the torrent.<br><br><b><b>-s</b>, <b>--size</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the total size of all files in the torrent.<br><br><b><b>-c</b>, <b>--comment</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the comment field from the torrent metadata.<br><br><b><b>-f</b>, <b>--files</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints a detailed list of all files contained within the torrent, including their paths and sizes.<br><br><b><b>-t</b>, <b>--tracker</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints a list of all tracker URLs associated with the torrent.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the <b>transmission-show</b> version number and exits.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message outlining command usage and options, then exits.<br><br>


title: DESCRIPTION
content:
<b>transmission-show</b> is a command-line utility bundled with the Transmission BitTorrent client. Its primary function is to parse and display detailed metadata contained within one or more <i>.torrent</i> files. Unlike the main Transmission application, <b>transmission-show</b> does not initiate downloads or manage torrents; it solely provides an inspection capability. Users can quickly view information such as the torrent's name, total size, individual file names and sizes, tracker URLs, creation date, comment, and info hash. This tool is invaluable for verifying torrent contents before adding them to a client, checking for malicious content, or simply getting a quick overview without launching the full GUI application or connecting to a daemon. It operates locally on <i>.torrent</i> files provided as arguments, making it a powerful diagnostic and preview tool for BitTorrent users.


title: CAVEATS
content:
<b>transmission-show</b> only works with local <i>.torrent</i> files. It cannot retrieve information from magnet links directly, nor can it inspect torrents that are currently active in a Transmission client without first downloading their <i>.torrent</i> file. It's a read-only utility; it does not modify torrent files or interact with the BitTorrent network.


title: KEY FEATURES
content:
<b>transmission-show</b> offers a quick, non-interactive way to inspect torrents. It's useful for scripting, automation, or simple command-line checks without resource overhead. Its ability to display specific fields (like magnet URI, info hash, files, trackers) makes it highly versatile for various inspection needs.


title: HISTORY
content:
<b>transmission-show</b> is an integral part of the Transmission BitTorrent client project, which was first released in 2005. Designed from the outset to be lightweight, simple, and resource-efficient, Transmission quickly gained popularity, especially among Linux users. The <b>transmission-show</b> utility was developed alongside the main client to provide users with a quick and easy way to inspect <i>.torrent</i> files without needing to open the full application or daemon. Its functionality has remained consistent, focusing on its core purpose of torrent metadata display, making it a reliable tool for pre-download verification and general torrent file analysis within the Transmission ecosystem.


title: SEE ALSO
content:
transmission-cli(1), transmission-daemon(1), transmission-remote(1), transmission-qt(1), transmission-gtk(1)


title: SYNOPSIS
content:
<i>transset</i> [<i>OPTIONS</i>] [<i>ALPHA</i>]<br><i>transset</i> [<i>OPTIONS</i>] <i>WINDOWID</i> [<i>ALPHA</i>]


title: PARAMETERS
content:
<b><i>ALPHA</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A floating-point value between 0.0 (fully transparent) and 1.0 (fully opaque), representing the desired opacity level. If <i>ALPHA</i> is provided but <i>WINDOWID</i> is omitted, <i>transset</i> will prompt the user to click on the desired window. If both <i>ALPHA</i> and <i>WINDOWID</i> are omitted, <i>transset</i> prints usage information.<br><br><b><i>WINDOWID</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The numerical ID of the target window whose opacity is to be changed. This ID can be obtained using utilities like <i>xwininfo</i>. If omitted and <i>ALPHA</i> is provided, <i>transset</i> enters an interactive mode, prompting the user to click on the desired window.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief help message and exits.<br><br><b><b>-V</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays version information and exits.<br><br><b><b>-n</b>, <b>--no-exit</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Keeps <i>transset</i> running after setting the window property, rather than exiting immediately. This is rarely used in typical scenarios.<br><br><b><b>-a</b>, <b>--all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies the specified opacity (<i>ALPHA</i>) to all currently managed windows on the X display. Useful for system-wide transparency changes.<br><br><b><b>-c</b>, <b>--click</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When interactive window selection is used (e.g., by running <i>transset 0.5</i> and clicking a window), this option causes <i>transset</i> to print the selected window's ID to standard output before exiting. This is primarily useful for scripting.<br><br>


title: DESCRIPTION
content:
<i>transset</i> is a command-line utility for the X Window System that enables users to dynamically change the opacity (transparency) level of specific windows. It operates by setting the <i>_NET_WM_WINDOW_OPACITY</i> Extended Window Manager Hint (EWMH) property on the target window. This property is then interpreted by a running compositing window manager (such as <i>xcompmgr</i>, <i>picom</i>, <i>KWin</i>, or <i>Mutter</i>) to render the window with the specified transparency. It is often used in shell scripts to achieve visual effects, manage desktop appearance, or to make certain application windows less obtrusive. Without a compositing manager, <i>transset</i> will execute but have no visible effect on window transparency.


title: CAVEATS
content:
Requires a running compositing window manager (e.g., <i>xcompmgr</i>, <i>picom</i>, <i>KWin</i>, <i>Mutter</i>) for the transparency effects to be visible. Without one, the command will execute but have no visual impact.<br>Only affects windows that support and correctly interpret the <i>_NET_WM_WINDOW_OPACITY</i> EWMH property. Most modern toolkits and applications support this.<br>Behavior and available options can vary slightly between different implementations or versions of <i>transset</i> (e.g., the original <i>transset</i> from <i>xcompmgr</i> versus <i>transset-df</i>).


title: THE _NET_WM_WINDOW_OPACITY PROPERTY
content:
<i>transset</i> functions by manipulating the <i>_NET_WM_WINDOW_OPACITY</i> Extended Window Manager Hint (EWMH) property on an X window. This property, defined by the NetWM specification, stores the desired opacity level as a 32-bit cardinal value. A value of 0x00000000 represents fully transparent, and 0xFFFFFFFF represents fully opaque. <i>transset</i> converts the 0.0-1.0 floating-point <i>ALPHA</i> value into this 32-bit integer representation before setting the property. Compositing managers monitor changes to this property and apply the corresponding visual transparency effect.


title: COMMON USAGE EXAMPLES
content:
<b>Make a window 50% transparent by clicking it:</b><br><i>transset 0.5</i><br>Then click the desired window.<br><br><b>Make a specific window 80% opaque:</b><br>First, find the window ID using <i>xwininfo</i> (e.g., <i>0x4800002</i>).<br><i>transset 0x4800002 0.8</i><br><br><b>Make all windows 25% transparent:</b><br><i>transset -a 0.75</i><br><br><b>Toggle a window's opacity (e.g., between 1.0 and 0.3):</b><br>This often requires a script due to <i>transset</i>'s simple nature.<br><i>#!/bin/bash</i><br><i>WID=$(xwininfo | grep 'Window id:' | awk '{print $4}')</i><br><i>CURRENT_OPACITY=$(xprop -id $WID _NET_WM_WINDOW_OPACITY | awk '{print strtonum($3)/4294967295}')</i><br><i>if (( $(echo "$CURRENT_OPACITY < 0.5" | bc -l) )); then</i><br><i>    transset $WID 1.0</i><br><i>else</i><br><i>    transset $WID 0.3</i><br><i>fi</i>


title: HISTORY
content:
<i>transset</i> originated as part of the <i>xcompmgr</i> project, an early and foundational compositing manager for the X Window System. Its primary purpose was to provide a simple command-line interface for manipulating the <i>_NET_WM_WINDOW_OPACITY</i> X property, demonstrating and facilitating basic window transparency. While <i>xcompmgr</i> has been superseded by more advanced compositors like <i>picom</i>, <i>transset</i> remains a functional and often included utility for directly controlling window opacity on X.org, leveraging the EWMH standard.


title: SYNOPSIS
content:
<b>trap</b> [<i>command</i>] [<i>signal ...</i>]<br><b>trap</b> <i>-l</i><br><b>trap</b> <i>-p</i> [<i>signal ...</i>]<br><b>trap</b> <i>-r</i> [<i>signal ...</i>]


title: PARAMETERS
content:
<b>command</b><br>&nbsp;&nbsp;&nbsp;&nbsp;A string containing the command(s) to be executed when the specified <i>signal</i> is received or event occurs. If <i>command</i> is an empty string (`""` or `''`), the trap for the specified <i>signal</i> is reset to its default action. If <i>command</i> is `'-'`, the <i>signal</i> is ignored by the shell and its children.<br><br><b>signal</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more signal names (e.g., <I>SIGINT</I>, <I>TERM</I>, <I>HUP</I>) or signal numbers (e.g., `2` for <I>SIGINT</I>). Special event names include:<br>    *   <I>EXIT</I> (or `0`): The command is executed when the shell exits.<br>    *   <I>ERR</I>: The command is executed whenever a command exits with a non-zero status.<br>    *   <I>DEBUG</I>: The command is executed before every simple command, <i>for</i> command, <i>case</i> command, <i>select</i> command, <i>while</i> command, or <i>until</i> command, or after a function definition.<br>    *   <I>RETURN</I>: The command is executed each time a shell function or a sourced script finishes executing.<br><br><b>-l</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a list of signal names and their corresponding numbers.<br><br><b>-p</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the trap commands associated with each <i>signal</i>, in a format that can be reused as input to <b>trap</b>. If no <i>signal</i> is specified, all current traps are printed.<br><br><b>-r</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Resets the action for each specified <i>signal</i> to its default (initial) state. If no <i>signal</i> is specified, all traps are reset. This is similar to setting an empty command string for each signal but specifically resets to default, not just ignores.<br><br>


title: DESCRIPTION
content:
The <b>trap</b> command is a powerful shell built-in that allows a script to capture and react to signals or other events. When a specified signal (like <I>SIGINT</I> for Ctrl+C, <I>SIGTERM</I> for termination, or <I>SIGHUP</I> for hangup) is received by the shell, or a special event occurs (like <I>EXIT</I> when the shell exits, <I>ERR</I> when a command exits with non-zero status, <I>DEBUG</I> before each command execution, or <I>RETURN</I> after a shell function/source script returns), <b>trap</b> executes a user-defined command.<br><br>This is crucial for robust script design, enabling clean-up operations, graceful shutdowns, or debugging. Without <b>trap</b>, many signals would terminate a script abruptly, potentially leaving temporary files or processes orphaned. It can also be used to ignore signals or reset their default behavior.


title: CAVEATS
content:
<b>trap</b> is a shell built-in command, meaning its behavior can slightly vary between different shells (e.g., Bash, Zsh, Dash).<br>Traps are inherited by subshells, but changes made to traps within a subshell are generally not propagated back to the parent shell.<br>The <I>DEBUG</I> trap can significantly impact script performance due to its frequent execution.<br>Signal handling can be complex, especially concerning asynchronous events and race conditions. Care must be taken when designing <b>trap</b> handlers, particularly in multi-process or heavily-threaded scripts.<br>Some signals, like <I>SIGKILL</I> and <I>SIGSTOP</I>, cannot be caught or ignored by <b>trap</b>.


title: COMMON USE CASES
content:
<i>Clean-up on Exit:</i> <i>trap 'rm -f /tmp/mytempfile' EXIT</i><br><i>Graceful Shutdown:</i> <i>trap 'cleanup; exit' INT TERM HUP</i><br><i>Error Handling:</i> <i>trap 'echo "Error on line $LINENO: $BASH_COMMAND" &gt;&2' ERR</i><br><i>Debugging:</i> <i>trap 'echo "Command: $BASH_COMMAND, Line: $LINENO" &gt;&2' DEBUG</i>


title: SIGNAL NUMBERS VS. NAMES
content:
While signal numbers can be used, it is generally recommended to use signal names for better readability and portability, as signal numbers can sometimes vary across different systems.


title: TRAP STACK (BASH SPECIFIC)
content:
Bash supports a trap stack for <I>DEBUG</I> and <I>RETURN</I> traps. Using <i>trap -p</i> and <i>trap -</i> can help manage this, allowing functions to add and remove their own traps without interfering with existing ones.


title: HISTORY
content:
The <b>trap</b> command has been a fundamental component of Unix shells for decades, providing a robust mechanism for script control and error handling. It was present in early versions of the Bourne shell and has since been incorporated into POSIX standards, ensuring its consistent availability across modern Unix-like operating systems. Its utility in handling script termination, unexpected errors, and debugging has made it an indispensable tool for shell programmers.


title: PARAMETERS
content:
<b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ignore non-existent files and arguments, never prompt.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explain what is being done by showing moved files.<br><br><b><b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display verbose debugging messages.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show program's version number and exit.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show help message and exit.<br><br><b><i>FILES...</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more files or directories to be moved to the trash.<br><br>


title: DESCRIPTION
content:
The <b>trash-put</b> command, often aliased simply as <b>trash</b> on many systems, provides a safer alternative to the <b>rm</b> command for deleting files from the command line. Unlike <b>rm</b> which permanently removes files, <b>trash-put</b> moves them to the freedesktop.org compatible trash bin, allowing for later recovery. This behavior mirrors the "Recycle Bin" or "Trash" functionality found in graphical desktop environments.<br><br>When a file or directory is "trashed," it is moved to a special location, typically <i>~/.local/share/Trash/</i>, where its original path and deletion date are also recorded. This design prevents accidental permanent data loss and provides a convenient way to manage deleted items. <b>trash-put</b> is part of the <b>trash-cli</b> suite, a set of command-line tools designed to interact with the freedesktop.org trash specification.


title: CAVEATS
content:
<b>trash-put</b> is not a default command on all Linux distributions and typically requires installation of the <i>trash-cli</i> package.<br><br>It relies on the <i>freedesktop.org trash specification</i>, which means it integrates well with desktop environments but might not be ideal for minimal server setups without a desktop environment.<br><br>Trashing files does not immediately free up disk space if the trash bin resides on the same filesystem. Space is only reclaimed when the trash is emptied.<br><br>When trashing files located on a different filesystem, <b>trash-put</b> might copy the files to the trash bin and then delete the originals, which can be slower and consume more space temporarily for large files.


title: THE <B>TRASH-CLI</B> SUITE
content:
The <b>trash-put</b> command is part of a larger collection of tools provided by the <b>trash-cli</b> package, all designed to interact with the <i>freedesktop.org trash specification</i>. Other commands in this suite include:<br><ul><li><b>trash-list</b>: To view all items currently in your trash bin.</li><li><b>trash-restore</b>: To interactively restore specific items from the trash back to their original location (or a specified one).</li><li><b>trash-empty</b>: To permanently delete all items in the trash, optionally specifying items older than a certain number of days.</li><li><b>trash-rm</b>: To permanently remove specific items from the trash without emptying the entire bin.</li></ul><br>These commands together provide comprehensive command-line management of trashed files.


title: FREEDESKTOP.ORG TRASH SPECIFICATION
content:
The <i>freedesktop.org trash specification</i> defines how trash bins should behave on Linux and other Unix-like systems. It mandates that trashed files are moved to a <i>Trash</i> directory, typically located at <i>~/.local/share/Trash/</i>. Inside this directory, two subdirectories are found: <i>files/</i> (where the actual trashed items reside) and <i>info/</i> (which contains metadata files (<i>.trashinfo</i>) detailing the original path and deletion date for each trashed item). This standardized approach ensures that files trashed via the command line (e.g., with <b>trash-put</b>) are visible and manageable by graphical file managers and vice-versa.


title: HISTORY
content:
The concept of a "trash bin" or "recycle bin" originated in graphical user interfaces to provide a safety net for file deletion. As command-line usage remained prevalent, a need arose for similar functionality outside of graphical environments. The <i>freedesktop.org trash specification</i> emerged to standardize this behavior across various Linux desktop environments. <b>trash-cli</b> (and thus <b>trash-put</b>) developed as a popular open-source implementation to bring this standardized trash management to the command line, offering a robust and recoverable alternative to the destructive nature of <b>rm</b>. Its development focused on user convenience and data safety, evolving to integrate seamlessly with desktop trash functionalities.


title: SEE ALSO
content:
<b>rm(1)</b>, <b>mv(1)</b>, <b>trash-list(1)</b>, <b>trash-restore(1)</b>, <b>trash-empty(1)</b>, <b>trash-rm(1)</b>


title: SYNOPSIS
content:
<b>trash-put</b> [<I>options</I>] <I>file</I>...<br><b>trash-list</b> [<I>options</I>]<br><b>trash-restore</b> [<I>options</I>] [<I>index</I>]<br><b>trash-empty</b> [<I>options</I>] [<I>days</I>]<br><b>trash-rm</b> [<I>options</I>] <I>file</I>...


title: PARAMETERS
content:
<b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays detailed information about the operation. This option applies to <b>trash-put</b>, <b>trash-list</b>, <b>trash-restore</b>, <b>trash-empty</b>, and <b>trash-rm</b>.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows a help message and exits. This option is available for all <b>trash-cli</b> commands.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the program's version number and exits. This option is available for all <b>trash-cli</b> commands.<br><br><b>-f, --force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Does not ask for confirmation before performing the operation. This option is primarily used with <b>trash-empty</b> to empty the trash without a prompt and with <b>trash-rm</b> to remove files from the trash without confirmation.<br><br><b>-d DAYS, --days DAYS</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with <b>trash-empty</b>, this option specifies that only files older than the given number of <I>DAYS</I> should be permanently deleted from the trash.<br><br><b>index</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with <b>trash-restore</b>, this argument specifies the numerical index of the file to restore from the trash list. If omitted, <b>trash-restore</b> will provide an interactive list for selection.<br><br><b>file...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with <b>trash-put</b>, this argument specifies one or more files or directories to move to the trash. When used with <b>trash-rm</b>, it specifies files to permanently remove from the trash by name.<br><br>


title: DESCRIPTION
content:
<i>trash-cli</i> provides a set of command-line tools that move files to the desktop trash folder, rather than permanently deleting them like the <b>rm</b> command. This offers a safety net, allowing users to restore accidentally deleted files. It adheres to the XDG Trash specification, ensuring compatibility with graphical desktop environments like GNOME, KDE, and XFCE.<br><br>The suite includes several commands:<br><b>trash-put</b>: Moves files to the trash.<br><b>trash-list</b>: Lists all files currently in the trash.<br><b>trash-restore</b>: Restores files from the trash interactively or by index.<br><b>trash-empty</b>: Permanently deletes all or old files from the trash.<br><b>trash-rm</b>: Permanently deletes specific files from the trash by name.<br><br>This makes <i>trash-cli</i> an essential tool for users who prefer the command line but desire the security and convenience of a graphical trash can.


title: CAVEATS
content:
<b>Cross-Filesystem Issues</b>: Trashing files across different filesystems can sometimes lead to complications with restoration or trash management if the trash directory structure isn't consistently accessible or managed per filesystem.<br><b>Not a True Undo</b>: While <i>trash-cli</i> provides a valuable safety net, it's not an infallible undo mechanism. The trash can still be manually emptied, files might be too large to be trashed, or the trash partition could fill up or be deleted.<br><b>User-Specific Trash</b>: The trash is typically user-specific. Files trashed by one user are not visible in or restorable from another user's trash directory.


title: XDG BASE DIRECTORY SPECIFICATION ADHERENCE
content:
<i>trash-cli</i> adheres to the XDG Base Directory Specification for trash management. This means trashed files are typically stored in a location like <b>$XDG_DATA_HOME/Trash</b> (which usually defaults to <b>~/.local/share/Trash</b> for individual users). For files on other filesystems, a <b>.Trash-UID</b> directory is created at the top level of that filesystem. This adherence ensures seamless integration and compatibility with graphical desktop environments that also follow this standard, allowing items trashed from the command line to appear in the desktop trash and vice-versa.


title: HISTORY
content:
<i>trash-cli</i> was developed as a safer, XDG-compliant alternative to the destructive <b>rm</b> command. It addresses the common user need for a 'trash bin' functionality in the command-line environment, mirroring the behavior of graphical desktop environments. Its development has focused on adhering to the XDG Trash specification to ensure interoperability and a consistent user experience across Linux desktops.


title: PARAMETERS
content:
<b>[DAYS]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Empties items that have been in the trash for longer than the specified number of days. If not provided, all items in the trash are permanently deleted.<br><br><b>--days DAYS</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Equivalent to specifying DAYS directly. Empties items older than DAYS.<br><br><b>-f, --force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not ask for confirmation before emptying the trash. Use with caution as this action is irreversible.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a list of each file and directory as it is being permanently deleted from the trash.<br><br>


title: DESCRIPTION
content:
<B>trash-empty</B> is a command-line utility used to permanently delete files and directories that have been moved to the trash according to the <I>freedesktop.org Trash Specification</I>. It is part of the <B>trash-cli</B> package, which provides a suite of tools for managing the user's trash from the terminal. Unlike the <B>rm</B> command, which deletes files immediately, <B>trash-put</B> moves files to a designated trash directory, allowing for later recovery. <B>trash-empty</B> then serves as the final step, removing these trashed items to free up disk space.<br><br>When executed without any arguments, <B>trash-empty</B> will delete all items currently in the trash. Users can also specify a number of <I>DAYS</I> to empty only those items that are older than the specified duration, providing a way to manage trash retention policies. This command is particularly useful for users who prefer to manage their system from the terminal but still wish to utilize the safety net of a trash bin, similar to what graphical file managers provide.


title: CAVEATS
content:
<ul><li><B>Irreversible Action</B>: Once <B>trash-empty</B> is executed, the files are permanently deleted and cannot be recovered through the trash system. There is no "undo" for this command.</li><li><B>User-Specific Trash</B>: <B>trash-empty</B> manages the trash for the current user session. It does not affect trash bins of other users or the root user.</li><li><B>Adherence to Standard</B>: It only empties files placed in the trash according to the <I>freedesktop.org Trash Specification</I> (typically located in <I>~/.local/share/Trash</I>). Files deleted via <B>rm</B> or other non-trash-aware methods are not affected.</li></ul>


title: TRASH LOCATION
content:
The standard location for a user's trash directory on Linux systems, adhering to the <I>freedesktop.org Trash Specification</I>, is typically <I>~/.local/share/Trash/</I>. This directory contains two subdirectories: <I>files/</I> (where the actual deleted items reside) and <I>info/</I> (which stores metadata like original path and deletion date). <B>trash-empty</B> operates by removing entries from both these locations.


title: INTEGRATION WITH DESKTOP ENVIRONMENTS
content:
Because <B>trash-empty</B> follows the freedesktop.org standard, it seamlessly integrates with most modern Linux desktop environments (e.g., GNOME, KDE, XFCE). Files moved to trash via the file manager (e.g., Nautilus, Dolphin) can be emptied using <B>trash-empty</B>, and vice-versa.


title: HISTORY
content:
The <B>trash-cli</B> project, which includes <B>trash-empty</B>, was developed to bring the convenience and safety of the freedesktop.org trash bin to the command line. Before <B>trash-cli</B>, users had to choose between the permanent deletion of <B>rm</B> or manually navigating to the trash directory. <B>trash-cli</B> aimed to bridge this gap, allowing terminal users to utilize the same trash mechanism as their graphical desktop environments. <B>trash-empty</B> specifically provides the necessary command to finally clear out accumulated trashed items, completing the trash management workflow.


title: SYNOPSIS
content:
<b>trash-list</b> [<i>-l</i> | <i>--long</i>] [<i>-a</i> | <i>--absolute</i>] [<i>-r</i> | <i>--relative</i>] [<i>PATTERN...</i>]


title: PARAMETERS
content:
<b><i>-l</i>, <i>--long</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays detailed information for each trashed item, including its original path, deletion date, and size.<br><br><b><i>-a</i>, <i>--absolute</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the original absolute path for each trashed item. This is often the default behavior.<br><br><b><i>-r</i>, <i>--relative</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows paths relative to the trash directory (e.g., <i>files/</i> or <i>info/</i> subdirectories), which might be less intuitive for general use.<br><br><b><i>PATTERN...</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filters the list of trashed items to display only those matching the specified pattern(s). Patterns can be filenames or parts of original paths.<br><br>


title: DESCRIPTION
content:
<i>trash-list</i> is a utility from the <b>trash-cli</b> package, providing a safe alternative to <b>rm</b> by moving files to a trash directory instead of permanent deletion. Specifically, <i>trash-list</i> allows users to view the files and directories currently residing in their trash. It typically displays crucial information such as the original absolute path of the deleted item, the date and time of its deletion, and its size.<br><br>This command is essential for users who wish to review deleted items before proceeding with recovery using <b>trash-restore</b> or permanent removal via <b>trash-empty</b>. Adhering to the XDG Base Directory Specification, <i>trash-list</i> inspects the standard trash location, usually <i>~/.local/share/Trash</i>, making it a reliable tool for managing user's trashed content and understanding what occupies space within the trash bin. It offers a more user-friendly and informative interface compared to manually navigating the hidden trash directories.


title: CAVEATS
content:
<i>trash-list</i> is part of the <b>trash-cli</b> project and is not a standard core utility; it may need to be installed separately. It strictly adheres to the XDG Trash specification and only manages files trashed using <b>trash-cli</b> commands, not files deleted by other methods like <b>rm</b> or potentially desktop environment trash implementations if they use a different mechanism.


title: TRASH LOCATION
content:
<i>trash-list</i> reads the contents of the trash directories defined by the XDG Base Directory Specification. The primary trash location is typically <i>~/.local/share/Trash</i>. This directory contains two crucial subdirectories: <i>files</i> (where the actual trashed items are stored) and <i>info</i> (which contains corresponding <i>.trashinfo</i> files with metadata).


