# TLDR Client Specification Requirements: A Complete Implementation Guide

> Understand the tldr client specification requirements for CLI arguments, page resolution, language detection, and caching. Implement official tldr clients effectively.

- Repository: [tldr pages/tldr](https://github.com/tldr-pages/tldr)
- Tags: architecture
- Published: 2026-03-05

---

**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](https://github.com/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)](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

```bash
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`](https://github.com/tldr-pages/tldr/blob/main/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

```bash
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`.

```bash

# 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

```bash

# 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`](https://github.com/tldr-pages/tldr/blob/main/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.