# tldr CLI Help API
> Simplified, example-driven help for the command line as an API — the community tldr-pages project, 7,045 command-line tools across Linux, macOS, Windows and more. Instead of dense man pages, every command (tar, git, ffmpeg, curl, docker, ssh, awk, …) comes back as a short description plus a handful of practical, copy-paste example commands with placeholders. Look up a command, search commands by name or description, filter by platform, or fetch a random command. Ideal for terminals, IDEs, chatbots, developer tools, onboarding and learning. Open data from tldr-pages (CC-BY).

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/tldr-api/..."
```

## Pricing
- **Free** (Free) — 3,400 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 48,000 calls/Mo, 8 req/s
- **Pro** ($12/Mo) — 239,000 calls/Mo, 20 req/s
- **Mega** ($33/Mo) — 1,195,000 calls/Mo, 50 req/s

## Endpoints

### tldr

#### `GET /v1/command` — Full tldr page for a command

**Parameters:**
- `name` (query, required, string) — Command name, e.g. tar, git, ffmpeg Example: `tar`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tldr-api/v1/command?name=tar"
```

**Response:**
```json
{
    "data": {
        "command": {
            "name": "tar",
            "title": "tar",
            "examples": [
                {
                    "command": "tar cf {{path/to/target.tar}} {{path/to/file1 path/to/file2 ...}}",
                    "description": "[c]reate an archive and write it to a [f]ile"
                },
                {
                    "command": "tar czf {{path/to/target.tar.gz}} {{path/to/file1 path/to/file2 ...}}",
                    "description": "[c]reate a g[z]ipped archive and write it to a [f]ile"
                },
                {
                    "command": "tar czf {{path/to/target.tar.gz}} {{[-C|--directory]}} {{path/to/directory}} .",
                    "description": "[c]reate a g[z]ipped (compressed) archive from a directory using relative paths"
                },
                {
                    "command": "tar xvf {{path/to/source.tar[.gz|.bz2|.xz]}}",
                    "description": "E[x]tract a (compressed) archive [f]ile into the current directory [v]erbosely"
                },
                {
                    "command": "tar xf {{path/to/source.tar[.gz|.bz2|.xz]}} {{[-C|--directory]}} {{path/to/directory}}",
                    "description": "E[x]tract a (compressed) archive [f]ile into the target directory"
                },
                {
                    "command": "tar caf {{path/to/target.tar.xz}} {{path/to/file1 path/to/file2 ...}}",
                    "description": "[c]reate a co
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/random` — A random command

**Parameters:**
- `platform` (query, optional, string) — Restrict to a platform

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tldr-api/v1/random"
```

**Response:**
```json
{
    "data": {
        "command": {
            "name": "devfsadm",
            "title": "devfsadm",
            "examples": [
                {
                    "command": "devfsadm -c disk",
                    "description": "Scan for new disks"
                },
                {
                    "command": "devfsadm -C -v",
                    "description": "Cleanup any dangling `/dev` links and scan for new device"
                },
                {
                    "command": "devfsadm -C -v -n",
                    "description": "Dry-run - output what would be changed but make no modifications"
                }
            ],
            "platform": "sunos",
            "more_info": "https://www.unix.com/man-page/sunos/1m/devfsadm",
            "description": "Administer `/dev` Maintains the `/dev` namespace",
            "example_count": 3
        }
    },
    "meta": {
        "timestamp": "2026-05-31T09:49:21.174Z",
        "request_id": "dc0580eb-f325-4f94-8e5f-bfaba3bc80bc"
    },
    "status": "ok",
    "message": "Random command retrieved",
    "success": true
}
```

#### `GET /v1/search` — Search commands by name / description

**Parameters:**
- `q` (query, optional, string) — Search term Example: `git`
- `platform` (query, optional, string) — common | linux | osx | windows | android
- `limit` (query, optional, string) — Results per page (1-100, default 20) Example: `20`
- `offset` (query, optional, string) — Pagination offset Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tldr-api/v1/search?q=git&limit=20&offset=0"
```

**Response:**
```json
{
    "data": {
        "count": 20,
        "limit": 20,
        "total": 374,
        "offset": 0,
        "filters": {
            "q": "git",
            "platform": null
        },
        "results": [
            {
                "name": "git",
                "title": "git",
                "platform": "common",
                "description": "Distributed version control system Some subcommands such as `commit`, `add`, `branch`, `switch`, `push`, etc. have their own usage documentation",
                "example_count": 8
            },
            {
                "name": "git-abort",
                "title": "git abort",
                "platform": "common",
                "description": "Abort an ongoing rebase, merge, or cherry-pick Part of `git-extras`",
                "example_count": 1
            },
            {
                "name": "git-add",
                "title": "git add",
                "platform": "common",
                "description": "Stage changed files for a commit",
                "example_count": 8
            },
            {
                "name": "git-alias",
                "title": "git alias",
                "platform": "common",
                "description": "Create shortcuts for Git commands Part of `git-extras`",
                "example_count": 3
            },
            {
                "name": "git-am",
                "title": "git am",
                "platform": "common",
                "description": "Apply patch
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Totals & platforms

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tldr-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "Simplified, example-driven help pages for command-line tools (the tldr-pages project). /v1/command returns the full page (description + practical example commands); /v1/search finds commands by name or description; /v1/random returns a random command.",
        "total": 7045,
        "fields": [
            "name",
            "platform",
            "title",
            "description",
            "more_info",
            "example_count",
            "examples"
        ],
        "source": "tldr-pages/tldr (CC-BY)",
        "by_platform": {
            "dos": 10,
            "osx": 312,
            "linux": 1932,
            "sunos": 10,
            "common": 4537,
            "netbsd": 1,
            "android": 13,
            "freebsd": 4,
            "openbsd": 3,
            "windows": 212,
            "cisco-ios": 11
        }
    },
    "meta": {
        "timestamp": "2026-05-31T09:49:21.329Z",
        "request_id": "710de600-b683-49ac-8433-096e40529cc0"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/tldr-api
OpenAPI spec: https://www.oanor.com/api/tldr-api/openapi.json