> For the complete documentation index, see [llms.txt](https://docs.calibratedsoftware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.calibratedsoftware.com/tin-man/getting-started-server.md).

# Getting Started (Server)

Tin Man Server is a professional command-line tool for batch processing, metadata extraction, creating thumbnails, copying media with xxHash64 verification and MHL, and report generation designed to support high-volume video production and post-production workflows.

Compatible with both Windows and macOS, Tin Man Server is licensed to handle a wide range of professional formats, including Apple ProRes & ProRes RAW, Avid DNxHD/HR, ARRIRAW, Blackmagic RAW, Canon RAW, Panasonic AVC-Ultra, RED RAW, and Sony RAW & XAVC.

#### Installation & Access

After installing Tin Man, the Server CLI is available at:

**macOS:**

```bash
"/Applications/Calibrated Tin Man.app/Contents/Server/tinman-server"
```

**Windows:**

```bash
"C:\Program Files\Calibrated\Tin Man\tinman-server.exe"
```

The installer automatically configures command-line access:

* **Windows:** Adds `C:\Program Files\Calibrated\Tin Man` to your system PATH
* **macOS:** Creates a symlink in `/usr/local/bin`

After installation, you can use `tinman-server` directly from any Command Prompt on Windows or Terminal on macOS.

#### Quick Start

View all available commands and options:

```bash
tinman-server --help
tinman-server --version
```

#### RAW Colorspace & GPU Options

These general options come before your input files and apply to the whole operation. The RAW colorspace flags set the output colorspace for all RAW files; the GPU flags control compute and encoding:

```bash
# Set all RAW files to Rec. 709 with tone mapping
tinman-server --raw709tonemap /path/footage/ metadata --output-dir /path/reports/

# Set all RAW files to Log
tinman-server --rawLog /path/footage/ export --preset mov_prores422_hq --output-dir /path/exports/

# Use CUDA instead of OpenCL (Windows / NVIDIA only)
tinman-server --gpu-cuda /path/footage/ export --preset mp4_h264_10mbps --output-dir /path/exports/

# Enable GPU hardware encoding
tinman-server --gpu-encode /path/footage/ export --preset mp4_h264_10mbps --output-dir /path/exports/
```

Additional RAW colorspace flags: `--raw2020`, `--rawHLG`, `--rawPQ`, `--rawACES`.

#### Extract Metadata

Generate comprehensive metadata reports in multiple formats:

```bash
# PDF report (default) with Rec. 709 conversion with Tone Mapping for Thumbnails
tinman-server /path/footage/ metadata --output-dir /path/reports/ --rec709tonemap

# CSV report
tinman-server /path/footage/ metadata --output-dir /path/reports/ --format csv

# Multiple formats at once
tinman-server /path/footage/ metadata --output-dir /path/reports/ --format csv pdf xlsx

# JSON with all metadata types
tinman-server /path/footage/ metadata --output-dir /path/reports/ --format json

# Contact sheet report
tinman-server /path/footage/ metadata --output-dir /path/reports/ --type contactsheet --format pdf

# Both clips and contact sheet reports
tinman-server /path/footage/ metadata --output-dir /path/reports/ --type clips contactsheet --format pdf
```

**Custom Report Configuration**

```bash
# Generate default config file
tinman-server generate-config --output my-config.json

# Use config for reports
tinman-server /path/footage/ metadata --config my-config.json --output-dir /path/reports/
```

#### Generate Thumbnails (currently free)

Extract thumbnail images with extensive control:

```bash
# Single thumbnail per file (320px wide, default)
tinman-server /path/footage/ thumbnail --output-dir /path/thumbs/

# Three evenly distributed thumbnails (start/middle/end)
tinman-server /path/footage/ thumbnail --output-dir /path/thumbs/ --position-count 3

# Six evenly distributed thumbnails (0%, 20%, 40%, 60%, 80%, 100%)
tinman-server /path/footage/ thumbnail --output-dir /path/thumbs/ --position-count 6

# Time-based thumbnails with intervals
tinman-server /path/footage/ thumbnail --output-dir /path/thumbs/ \
  --time-count 5 --time-interval 1.0 --usesubdirs

# Custom naming with prefix and timecode index
tinman-server /path/file.R3D thumbnail --output-dir /path/thumbs/ \
  --nameprefix Dailies --nameindex timecode

# with Rec. 709 conversion with Tone Mapping
tinman-server /path/file.braw thumbnail --output-dir /path/thumbs/ \
  --startframe 100 --size 512 --quality 95 --rec709tonemap
```

#### Export & Transcode

Export and transcode media files using system presets or custom configurations:

```bash
# List all available system presets
tinman-server export --list-presets

# Export using system preset to ProRes 422 HQ
tinman-server /path/footage/ export --preset mov_prores422_hq --output-dir /path/exports/

# Export using custom preset JSON file
tinman-server /path/footage/ export --preset /path/my-preset.json --output-dir /path/exports/

# Override preset resolution to half
tinman-server /path/footage/ export --preset mov_prores422_hq --output-dir /path/exports/ \
  --resolution half

# Override preset bitrate (target and max in kbps, H.264/H.265 only)
tinman-server /path/footage/ export --preset mp4_h264_10mbps --output-dir /path/exports/ \
  --bitrate 12000 16000

# Export with custom naming pattern to 10Mbps H264
tinman-server /path/footage/ export --preset mp4_h264_10mbps --output-dir /path/exports/ \
  --naming "{date}_{source}_{timecode}"

# Export image sequence with custom frame numbering
tinman-server /path/file.R3D export --preset imageseq_dpx_10bit_rgb_be \
  --output-dir /path/exports/ --index-prefix "." --index-min-size 6 --index-offset 1
```

#### Copy Files with Verification (currently free)

Copy media files and camera cards with checksum verification. Every copy is verified with xxHash64, and an MHL file is written to the output folder.

```bash
# Copy a single file (to /path/backup/input.R3D)
tinman-server /path/input.R3D copy --output-dir /path/backup/

# Copy a camera card folder (to /path/backup/A001/...)
tinman-server /path/cards/A001/ copy --output-dir /path/backup/

# Copy two cards in one run (to /path/backup/A001/... and /path/backup/B001/...)
tinman-server /path/cards/A001/ /path/cards/B001/ copy --output-dir /path/backup/

# Overwrite existing files
tinman-server /path/cards/A001/ copy --output-dir /path/backup/ --overwrite
```

A folder is copied whole under its own name: every file and subfolder, sidecar files and empty folders included, so camera cards keep their structure. Hidden and system files (`.DS_Store`, `._*`, `Thumbs.db`, `desktop.ini`) are skipped. Copies keep the source files' modified dates.

#### Multi-Threading

Process files faster with concurrent operations (1-5 threads - default 1):

```bash
# Metadata extraction with 3 threads
tinman-server --threads 3 /path/footage/ metadata --output-dir /path/reports/ --format csv

# Export with 3 threads
tinman-server --threads 3 /path/footage/ export --preset mov_prores422_hq --output-dir /path/exports/

# File copying with maximum threads (5)
tinman-server --threads 5 /path/footage/ copy --output-dir /path/backup/
```

#### Chaining Commands

Execute multiple operations in a single command:

```bash
# Generate both metadata report and thumbnails
tinman-server /path/input.R3D metadata --output-dir /path/reports/ thumbnail --output-dir /path/thumbs/
```

#### Progress Output

By default, Tin Man Server writes JSON progress events to stderr, each line starting with `STATUS:` , ready for automation tools to parse:

```bash
# JSON progress (default) - ideal for automation
tinman-server /path/footage/ metadata --output-dir /path/reports/

# JSON lines on stdout, without the STATUS: prefix
tinman-server --progress=ndjson /path/footage/ metadata --output-dir /path/reports/

# Human-readable progress
tinman-server --progress=no-json /path/footage/ metadata --output-dir /path/reports/
```

The JSON progress output includes file processing status, progress percentage, errors and warnings, operation results, and timing metrics. With `--progress=ndjson`, stdout holds only the JSON events and any human-readable text stays on stderr. It can't be combined with `metadata --stdout-json`, which also writes to stdout.

#### Exit Codes

| Code | Meaning                                                                                     |
| ---- | ------------------------------------------------------------------------------------------- |
| 0    | Success                                                                                     |
| 1    | Error, or every file failed                                                                 |
| 2    | Cancelled                                                                                   |
| 3    | Usage error: unknown command or option, bad value or combination                            |
| 4    | No input: no supported files found, none could be opened, or the project couldn't be loaded |
| 10   | Partial failure: some files failed, the rest succeeded                                      |

#### Input Methods

```bash
# Single file
tinman-server /path/input.R3D metadata --output-dir /path/reports/

# Multiple files
tinman-server /path/file1.R3D /path/file2.braw metadata --output-dir /path/reports/

# Folders (recursive by default)
tinman-server /path/footage/ metadata --output-dir /path/reports/

# Don't scan subfolders
tinman-server --no-recursive /path/footage/ metadata --output-dir /path/reports/

# File list from text file
tinman-server @filelist.txt metadata --output-dir /path/reports/

# A saved Tin Man project (see Tin Man Projects)
tinman-server /path/MyShoot.tmprjt metadata --output-dir /path/reports/
```

#### Tin Man Projects

Use a saved Tin Man project (`.tmprjt`) as the input, and Tin Man Server works from its clips with their saved settings: slate and camera metadata, timecode, in/out points, rotation, LUTs, color correction, RAW settings, and linked or synced audio. The project must be the only input.

```bash
# Clip report for every clip in the project
tinman-server /path/MyShoot.tmprjt metadata --output-dir /path/reports/ --format pdf

# Export only the clips in one bin and its sub-bins
tinman-server --bin "Day 1/A Cam" /path/MyShoot.tmprjt export --preset mov_prores422_hq --output-dir /path/exports/

# Thumbnails for two bins
tinman-server --bin "Day 1" --bin "Day 2" /path/MyShoot.tmprjt thumbnail --output-dir /path/thumbs/
```

* Exports cover each clip's marked in/out range.
* Offline clips are skipped with a warning, and the rest are processed.
* `copy` copies the project's clips, not the project itself.
* `--bin` takes a bin path with `/` between levels. Write a `/` inside a bin name as `\/`: a bin named `A/B Cam` inside `Day 1` is `"Day 1/A\/B Cam"`. A bin that isn't in the project gives a warning.
* JSON, CSV and XLSX reports have a Bin column. To leave it out, set `bin` to `false` under `columns` in a report config (see Custom Report Configuration).

#### Claude Plugin

Tin Man Server includes a Claude plugin for macOS and Windows, so you can run all Tin Man Server operations through natural language in the Claude desktop app and Claude Code. Install the plugin from the [GitHub repository](https://github.com/calibratedsoftware/tinman-server-claude-plugin).

#### Other MCP Clients

To connect Tin Man Server to any MCP-compatible client, add the following entry to your client's MCP configuration file.

**Windows:**

```json
"tinman-server": {
  "command": "C:\\Program Files\\Calibrated\\Tin Man\\python\\python.exe",
  "args": ["C:\\Program Files\\Calibrated\\Tin Man\\MCP\\tinman_server_mcp.cpython-310.pyc"]
}
```

**macOS:**

```json
"tinman-server": {
  "command": "/Applications/Calibrated Tin Man.app/Contents/PlugIns/Frameworks/Python.framework/Versions/3.10/bin/python3",
  "args": ["/Applications/Calibrated Tin Man.app/Contents/Server/tinman_server_mcp.cpython-310.pyc"]
}
```

#### Support

For complete command reference and all available options:

```bash
tinman-server --help
```

For questions or workflow consultation: <support@calibratedsoftware.com>

Download Tin Man: <https://www.calibratedsoftware.com/tin-man/trial/>
