TLDR Client Specification Requirements: A Complete Implementation Guide

The tldr client specification mandates that all official clients must support mandatory CLI arguments including --version and --platform, implement specific page resolution logic across platform directories, handle POSIX-style language detection, and manage caching through GitHub release archives while maintaining non-zero exit codes for missing pages.

The tldr-pages/tldr repository defines a strict contract for command-line clients in its [CLIENT-SPECIFICATION.md](https://github.com/tldr-pages/tldr/blob/main/CLIENT-SPECIFICATION.md) file (currently version 2.3). This specification ensures consistent behavior across platforms, languages, and implementations. Understanding these tldr client specification requirements is essential for developers building compatible clients or contributing to the ecosystem.

Required CLI Arguments

The specification defines several mandatory and optional command-line flags that every client must support. All variants of each option must be implemented (e.g., both -v and --version).

Mandatory arguments:

• -v / --version: Prints the client version and the specification version it implements
• -p / --platform: Forces a specific platform target (e.g., linux, windows, common, osx)
• -u / --update: Required only if the client implements caching; refreshes the offline page archive

Optional arguments:

• -l / --list: Lists every available page for the selected platform
• -L / --language: Overrides automatic language detection with a specific locale
• --short-options: Displays only short-form flags in command examples
• --long-options: Displays only long-form flags in command examples

tldr --version                # Output: client v1.2.3, spec v2.3

tldr -p windows git           # Force Windows platform resolution

tldr -u                       # Update local cache (if caching is implemented)

tldr --short-options tar      # Show "tar -x" instead of "tar --extract"

Page Name Normalization

The first non-flag argument passed to the client is treated as the page name. According to the specification in CLIENT-SPECIFICATION.md, clients must normalize this input by converting spaces to dashes and lowercasing the entire string.

• git checkout resolves to git-checkout
• eyeD3 resolves to eyed3
• Mixed case is tolerated but normalized to lowercase

tldr Git Checkout     # Internally resolves to "git-checkout"

tldr eyeD3            # Resolves to "eyed3"

Platform Resolution Algorithm

Pages are organized under pages/<platform>/ directories (e.g., pages/linux/, pages/common/). The client must implement a specific fallback sequence when locating pages:

1. Use the platform specified by -p / --platform if provided
2. Search the host platform directory (e.g., linux on Linux systems)
3. Fall back to the common directory
4. If still missing, iterate through other available platforms

For example, requesting apt on Windows without a local page would search: windows → common → osx → linux (found).

The specification also recommends supporting macos as an alias for the osx platform and designing clients to auto-detect new platforms without breaking.

Language Selection and Localization

Clients must implement POSIX-style locale detection to support multilingual pages stored in pages.<locale>/ directories. The resolution priority follows this exact order:

1. Check the LANG environment variable
2. Build a priority list from LANGUAGE (colon-separated) if set
3. Append LANG to the priority list
4. Use the first language with a matching translated page
5. Default to English if no translations exist

Users may override this logic using -L / --language.

# With LANG=it and LANGUAGE="it:fr:en"

tldr ls          # Prefers Italian, falls back to French, then English

# Override automatic detection

tldr -L fr grep  # Explicitly request French translation

Caching Requirements

While optional, caching is common among clients. If implemented, the -u / --update flag becomes mandatory. Clients must download archives from the official GitHub releases:

• Full archive: https://github.com/tldr-pages/tldr/releases/latest/download/tldr.zip
• Language-specific: https://github.com/tldr-pages/tldr/releases/latest/download/tldr-pages.<language>.zip

The legacy endpoint https://tldr.sh/assets is deprecated and scheduled for removal after December 2025.

Error Handling Standards

When a requested page cannot be found in any platform directory, the client must:

• Display a message containing a link to open a new GitHub issue: https://github.com/tldr-pages/tldr/issues/new?title=page%20request:%20{command_name}
• Exit with a non-zero status code
• Optionally warn if multiple platform versions exist but the specific requested one is missing

Placeholder Rendering Rules

Pages use custom {{…}} syntax for placeholders. Clients must render these according to the specification:

• Strip outer {{ and }} delimiters when displaying
• Support {{[-s|--long]}} syntax to show short/long variants based on --short-options or --long-options flags
• Preserve escaped braces \{\{…\}\} as literal characters in output

# Page content: git add {{[-A|--all]}}

tldr --short-options git add    # Renders as: git add -A

tldr --long-options git add     # Renders as: git add --all

Summary

• Mandatory arguments: Every client must support --version, --platform, and conditionally --update if caching exists
• Page resolution: Follow the platform fallback chain: explicit flag → host platform → common → other platforms
• Language detection: Implement POSIX locale handling via LANG and LANGUAGE variables with English fallback
• Caching protocol: Download from GitHub releases latest URLs, not the deprecated tldr.sh endpoint
• Error behavior: Return non-zero exit codes and provide GitHub issue links for missing pages
• Rendering: Handle {{placeholder}} syntax including short/long option variants and escaped braces

Frequently Asked Questions

What arguments must every tldr client implement?

Every client must implement -v / --version to report the client and specification version, and -p / --platform to force specific platform resolution. If the client supports offline caching, -u / --update becomes mandatory to refresh the local page archive. All variants (short and long forms) of each argument must be supported according to the specification in CLIENT-SPECIFICATION.md.

How does a tldr client resolve page locations across platforms?

The client searches directories under pages/<platform>/ using a specific hierarchy: first checking the platform specified by the -p flag, then the host platform, then common, and finally iterating other platforms. For example, a Windows client searching for apt would check pages/windows/, then pages/common/, then potentially pages/osx/ and pages/linux/ until finding the page.

What are the caching requirements for tldr clients?

Caching is optional, but if implemented, clients must provide the -u / --update flag and download archives from https://github.com/tldr-pages/tldr/releases/latest/download/tldr.zip for full archives or language-specific variants like tldr-pages.<language>.zip. Clients must not use the deprecated https://tldr.sh/assets endpoint, which will be removed after December 2025.

How should tldr clients handle missing pages?

When a page is not found in any platform directory, the client must exit with a non-zero status code and display a message including a link to https://github.com/tldr-pages/tldr/issues/new?title=page%20request:%20{command_name} to allow users to request the missing page. If multiple platform versions exist but the requested one is missing, the client may optionally warn the user about available alternatives.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}