CLI & REST API Reference

Overview

The pme CLI lets you transcode, probe media files, manage presets, and run a headless encoding server, all from the terminal. It ships inside the application bundle.

The same binary is also an MCP server for AI assistants (pme mcp). Setup, tools and example prompts are in the MCP server guide.

Installation

Install the CLI from within the app: Parallel Media Encoder → Install CLI Tool… in the menu bar. This creates the symlink automatically. See the Getting Started guide for details.

Or create the symlink manually:

ln -s "/Applications/Parallel Media Encoder.app/Contents/MacOS/pme" /usr/local/bin/pme

License requirement

The transcode and watch commands require an active Pro license. The probe, inspect and service commands work on the free tier; the service applies the same per-job free-tier rules as the app (standard codecs, no RAW, LUT, overlays, DNx or custom presets) and returns 403 for a Pro feature on the free tier. The free tier is licensed for personal, educational, and evaluation use; paid work needs a Pro license per Mac.

Accepting the License Terms

Before pme does any work on a Mac, the License Terms must have been accepted there, either by choosing Agree in the app or with pme terms accept. Until then every working command prints a notice and exits with code 6 and the error terms_not_accepted; --help, pme terms, pme license status, pme service status and the pme mcp install commands still run. A background service or MCP server never accepts on your behalf.

Quick check

pme --version

pme --help

pme transcode

Transcode one or more media files. Requires a Pro license.

Multiple inputs encode in parallel using the same scheduler as the app, up to the hardware session limit (or --concurrency), with RAW formats held to their per-format isolation caps. Invalid flag values are rejected up front with exit code 2; they are never silently ignored.

Flags

Examples

pme transcode input.mxf -o output.mov --codec hevc --quality 0.8

pme transcode input.mxf -o output.mov --preset "YouTube 4K H.265"

pme transcode input.mxf -o output.mov --codec prores422hq --lut /path/to/look.cube

pme transcode input.braw -o output.mov --codec prores422hq --proresraw-color rec709

pme transcode A001C001.CRM -o output.mov --codec prores422hq --canon-color canonlog2:cinemagamut

pme transcode shot.mxf -o output.mov --codec prores4444 --arri-color logc4

pme transcode *.mxf -o /output/folder/

pme transcode input.mxf -o output.mov --json

pme transcode input.braw -o output.mov --codec hevc --rotate cw90

pme transcode input.R3D -o output.mov --codec prores422hq --rotate ccw90 --resolution 1080x1920

pme transcode input.mov -o output.mov --resolution 1920x1080 --resize-mode fit

pme transcode input.mxf -o output.mov --rotate cw90 --resolution 1080x1920 --resize-mode fill

pme transcode input.mov -o clip.mov --in 00:01:30:00 --out 00:02:15:00 --codec hevc

pme transcode input.mov -o clip.mov --in 00:05:00:00

pme transcode A038C026.MXF -o clip.mov --codec prores422 --in '01:22:03;26' --out '01:23:13;30'

pme transcode input.mov -o output.mov --codec hevc --bitrate 20000 --profile main10 --audit

pme transcode IMG_2266.MOV livestream.mp4 -o proxies/ --preset "LucidLink (Proxy)" --audit
# Warning: livestream.mp4 is variable frame rate (variable: avg 27.866 fps, 29 fps base, 4702 held / 0 short frames); its frame timing is kept.
# Transcoding: livestream.mp4 → livestream.mp4
#   Bitrate: 2,148 Kbps (14,000 Kbps ceiling scaled to 320×640; capped at 1.5× the source's 1,432 Kbps)

pme transcode livestream.mp4 -o proxy.mov --preset "LucidLink (Proxy)" --frame-timing resample

pme transcode input.mov -o output.mov --watermark /path/to/logo.png --watermark-scale 50

pme transcode input.mov -o output.gif --codec gif

pme transcode input.mov -o clip.gif --codec gif --in 00:00:10:00 --out 00:00:13:00

pme transcode A001C003.braw -o /Volumes/RAID/Pulls/ --codec dpx --image-bit-depth 10 --frame-numbering source_timecode

pme transcode shot.mov -o /Volumes/RAID/VFX/sh010 --codec exr --custom-start-frame 1001 --frame-padding 4 --audit

pme transcode interview.mp4 -o stills/ --codec jpeg --jpeg-quality 85 --in 00:00:10:00 --out 00:00:12:00

pme probe

Inspect a media file and print its metadata. Works without a Pro license.

pme probe /path/to/video.mxf

pme probe --json /path/to/video.mxf

Example JSON response:

{
  "videoCodec": "H.264",
  "width": 3840,
  "height": 2160,
  "frameRate": 59.94,
  "duration": 60.5,
  "container": "MXF",
  "audioTracks": [
    {
      "index": 0,
      "codec": "PCM",
      "channels": 1,
      "sampleRate": 48000,
      "bitDepth": 24
    },
    {
      "index": 1,
      "codec": "PCM",
      "channels": 1,
      "sampleRate": 48000,
      "bitDepth": 24
    }
  ],
  "fileSize": 1073741824
}

MOV and MP4 files also carry frameTiming, read from the file's sample table (no decoding): whether the file is variable frame rate, its base cadence and average rate, how many frames are held or short, and how far a constant grid would be off.

"frameTiming": {
  "variableFrameRate": true,
  "baseFrameRate": 29,
  "averageFrameRate": 27.866,
  "heldFrames": 4702,
  "shortFrames": 0,
  "cadenceErrorSeconds": 22.3784,
  "summary": "variable: avg 27.866 fps, 29 fps base, 4702 held / 0 short frames"
}

pme inspect

Display full metadata for a media file, including codec, resolution, bit depth, chroma subsampling, timecode, HDR info, and more. Works without a Pro license.

This is a deeper analysis than pme probe. Use probe for fast scripting; use inspect for detailed human inspection.

pme inspect /path/to/video.mxf

pme inspect --json /path/to/video.braw

Flags

pme presets

Manage encoding presets. Presets are shared with the app, so a preset created via the CLI appears in the GUI and vice versa. Built-in presets cannot be modified or deleted.

List

pme presets list

pme presets list --json

--detailed adds every setting under the pme transcode option it corresponds to (codec, container, resolution, frame rate and frame timing, rate control and bitrate (with bitrate_scaling on when the bitrate is a ceiling scaled to the picture), profile, keyframe interval, audio codec, channels and bit depth, timecode, LUT, audit), so you can see what a preset writes before using it; --name shows one preset that way. Two values are descriptive: container source (H.264/HEVC keep a MOV or MP4 source's container; override with --container) and resolution source ÷ 2 (a preset scale-down that --resolution has no form for).

pme presets list --name "LucidLink (Proxy)"

Create

Creates a custom preset, starting from an existing preset's settings when --base is given, otherwise from app defaults. --codec is required unless --base is given. Requires a Pro license.

pme presets create "Proxy 1080p" --codec prores422proxy --resolution 1920x1080

pme presets create "YouTube 4K Stereo" --base "YouTube 4K H.265" --audio-channels stereo

Rename, delete, export, import

pme presets rename "Proxy 1080p" "Proxy FHD"

pme presets delete "Proxy FHD"

pme presets export "YouTube 4K H.265" ~/Desktop/youtube-4k.json

pme presets import ~/Desktop/youtube-4k.json

pme license

Manage your Pro license from the command line. Activation, deactivation and renewals (each time the app or the background service starts, and about once a day while it runs) go through the Parallel Media Encoder license server, which keeps track of which Macs hold a license's seats.

pme license status

Prints the tier, the scope it is licensed for, the validation status and the terms link. On Pro it also prints the edition, licensee, where the key came from, the seats in use ("This Mac: 1 of 5 seats") and the date until which the license works offline. It reports the stored license without contacting the server; --refresh asks the license server first, so a seat released from another Mac shows at once (offline, the stored license still answers).

--json adds scope, terms_url, terms_version, terms_accepted and, once accepted, terms_accepted_at and terms_accepted_via. A Pro license adds source (direct for a PME key, gumroad), edition (pro, education, nfr or trial), licensee, seats, seats_used, lease_expires (how long it works offline) and, for a license with an end date, license_expires. When a license stops unlocking Pro, lapse says why: check_pending, deactivated, seat_limit, suspended, revoked, expired or key_not_recognized. With seat_limit, machines lists the Macs holding every seat (id, name, model, last_seen). An education license unlocks Pro features for non-commercial use only.

Tier: free
Scope: Personal, educational, and evaluation use. Paid work requires a Pro license per Mac.
Status: No license key found. Use 'pme license activate <key>' to activate.
Terms: https://parallelmediaencoder.com/license/

pme license activate PME-XXXXX-XXXXX-XXXXX-XXXXX

Takes a PME- key from us or a key bought on Gumroad. Activation needs an internet connection and the License Terms accepted on this Mac first. Run pme terms accept, or add --accept-license-terms to accept them as part of the activation. Activation sends your license key, this Mac's name and a machine identifier to the Parallel Media Encoder license server, as described in the Privacy Policy. After that, Pro works offline for up to 30 days at a time. If every seat on the key is in use, the key is kept and the command lists the Macs holding them, with the ids pme license release takes.

pme license deactivate

Releases this Mac's seat on the license server and removes the key here, so the license can be activated on another Mac. Offline, Pro turns off at once and the seat is released the next time pme or the app can reach the server. This is Deactivate This Mac in Settings → License.

pme license release <mac-id>

For a PME- key whose seats are all in use: frees the seat held by the Mac with that id (listed by pme license status), then activates this Mac. The Mac you replace switches to Free the next time it checks in, and pme license status on it names the Mac that released it. This is Replace in Settings → License. Keys bought on Gumroad can't release seats, and a key can release up to 5 Macs in 24 hours.

pme license add-seats [--seats 2]

Opens a checkout page in your browser that adds seats to the PME- key stored on this Mac. The key itself doesn't change, and this Mac doesn't need a seat of its own, so it also works when every seat is in use. --seats sets the starting quantity (1 to 10; you can change it on the checkout page). --no-open prints the link instead of opening it, and --json prints url and expires_at. After paying, run pme license status --refresh to see the new seat count, or pme license activate again if this Mac was refused for seats. This is Add Seats in Settings → License. Keys bought on Gumroad, education keys and keys with an end date can't buy seats online: contact us instead. Without the app, you can also add seats on the web.

pme terms

Show, accept, or check acceptance of the License Terms. Acceptance is recorded once per terms version on this Mac and shared with the app; the record holds the version, the date, the document checksum and which command or button recorded it, never your license key.

pme terms show

pme terms accept

pme terms accept --yes

pme terms status --json

pme terms accept without --yes refuses to run when standard input is not a terminal, so an automated install never accepts silently.

pme service

Run Parallel Media Encoder as a headless HTTP server. This enables remote job submission, queue management, and real-time progress monitoring through the REST API. The service runs on any tier; licensing is enforced per submitted job.

Start & stop

pme service start

The default socket is ~/Library/Application Support/ParallelMediaEncoder/pme.sock. If you pass a custom --socket, keep the path short: macOS limits Unix socket paths to 104 characters.

pme service start --port 8080

pme service start --no-auth

pme service stop

pme service status

The status names the host (the app or the headless daemon), its version and build, and built_at, when the running binary was built, which tells apart two local builds with the same version and build number.

Auto-start with launchd

pme service install

pme service uninstall

Auth tokens

pme service token

pme service token --regenerate

pme watch

Manage watch folders for automatic transcoding. Drop media into a folder and PME picks it up, applies a preset, and transcodes to your output folder. Requires a Pro license. Your AI assistant can do the same through the MCP server.

While the Parallel Media Encoder app (or pme service) is running, it owns watch folders: every pme watch command goes through it, so a folder you add or change from the terminal appears in the app at once and is never overwritten by it. With nothing running, the commands edit ~/Library/Application Support/ParallelMediaEncoder/WatchFolders.json directly, and pme watch start runs the folders in the terminal.

How it works

When a watch folder is active, PME scans it (subfolders included) at a configurable interval (1–60 minutes). A new file is picked up once it has stopped changing across two scans: it is moved into a PickedUp subfolder (or a custom destination on the same volume) and queued, so it is never processed twice. The source of an encode that fails for good is moved to a Failed folder next to PickedUp. Media already in the folder is picked up on the first scan; --dry-run lists it first. To re-process a file, move it back into the watch folder.

The output folder cannot be inside or the same as the watch folder (this would create an infinite loop). Watch folders also cannot overlap (a new watch folder cannot be a parent or subfolder of an existing one), and one watch folder's output or PickedUp folder can't sit inside another watch folder.

A folder is watched by one process at a time. If the app is watching it, pme watch start --foreground skips it (and the other way round); pme watch status says who is watching.

For network shares (SMB, NFS), PME stores credentials in the Keychain and remounts the share automatically if it disconnects; pme watch mount reconnects it on demand.

Add a watch folder

pme watch add \
  --folder /Volumes/Ingest/DailyRushes \
  --output /Volumes/Export/Proxies \
  --preset "ProRes 422 Proxy" \
  --interval 5 \
  --suffix "-Proxy" --dry-run

pme watch add \
  --folder /Volumes/Ingest/DailyRushes \
  --output /Volumes/Export/Proxies \
  --preset "ProRes 422 Proxy" \
  --interval 5 \
  --suffix "-Proxy" --start

security find-generic-password -w -s studio-nas | pme watch add \
  --folder /Volumes/NAS/Ingest \
  --output /Volumes/NAS/Transcoded \
  --preset "ProRes 422 HQ" \
  --network-user "[email protected]" \
  --network-password-stdin

Read passwords from standard input: a password passed as a flag is visible to other processes and stays in your shell history. (--network-password still works, with a warning.)

pme watch add \
  --folder /Volumes/Rushes/Camera_A \
  --output /Volumes/Rushes/Proxies \
  --preset "ProRes 422 Proxy" \
  --picked-up-path /Volumes/Rushes/Processed

Change a watch folder

pme watch edit changes only the flags you pass, with the same flags as add. A folder that is being watched restarts with the new settings. The watch folder and its PickedUp destination can't move while its jobs are still queued or encoding.

pme watch edit DailyRushes --interval 1 --preset "LucidLink (Proxy)"
pme watch edit a1b2c3d4 --no-suffix --dry-run

A watch folder is named by its id, a unique id prefix (4 or more characters), its folder name, or its path.

List and status

pme watch list
pme watch list --json

• a1b2c3d4 DailyRushes: idle in the app · /Volumes/Ingest/DailyRushes → /Volumes/Export/Proxies · ProRes 422 Proxy · every 5 min · next scan in 3 min · jobs: 12 completed, 1 encoding
• b5c6d7e8 Ingest: error · /Volumes/NAS/Ingest → /Volumes/NAS/Transcoded · ProRes 422 HQ · every 5 min
  Error: Source network share disconnected
  Reconnect the source share with the watch folder's mount action (… CLI pme watch mount b5c6d7e8).

pme watch status DailyRushes --activity 20
pme watch status a1b2c3d4 --json

status shows what a folder is doing: its state and who watches it, errors with what to do about them, the last and next scan, files still being copied or sent back to the folder (with the reason PME couldn't transcode them), the ids of its jobs, the Failed folder count, network share state, and recent activity kept by the app or service. --json returns the same status object as the REST API; pme watch list --json keeps its array format (plus state and watched_by).

Start, stop, scan

When the app or service is running, start starts the folder there and returns straight away. Otherwise, or with --foreground, the folders run in the terminal and print events as files are picked up; press Ctrl+C to stop.

pme watch start DailyRushes
pme watch start all
pme watch start all --foreground --json   # run here, JSON event stream

PME watch folders running. Press Ctrl+C to stop.
  [a1b2c3d4] /Volumes/Ingest/DailyRushes (every 5 min)

[14:32:01] [a1b2c3d4] Scanning /Volumes/Ingest/DailyRushes...
[14:32:02] [a1b2c3d4] 3 files picked up (3 total)
[14:37:01] [a1b2c3d4] Scanning /Volumes/Ingest/DailyRushes...

pme watch stop DailyRushes      # stop watching (jobs already queued keep running)
pme watch stop all
pme watch scan DailyRushes      # scan now instead of waiting for the interval
pme watch mount Ingest          # reconnect the source share (--output for the output share)

Remove

pme watch remove a1b2c3d4
pme watch remove /Volumes/Ingest/DailyRushes

Removing a watch folder stops it and deletes its stored network credentials from the Keychain. No files are moved or deleted: media in the folder, PickedUp and Failed stay where they are, and queued jobs finish.

pme mcp

A Model Context Protocol server for AI assistants (Claude Desktop, Claude Code, Codex and Gemini CLI). The AI app launches pme mcp itself and talks to it over stdio; encodes are handed to pme service, which it starts when needed. Free on every tier. Full guide: MCP Server for AI Assistants.

pme mcp install              # register PME with every detected AI app
pme mcp install --client codex   # one app (repeatable), even if not detected
pme mcp install --dry-run    # show what would change
pme mcp status               # installed / not installed / stale per app
pme mcp uninstall            # remove the entry everywhere
pme mcp bridges              # running bridges (one per AI session) and the service socket
pme mcp bridges --stop-stale # stop bridges whose assistant quit or that run an older pme
pme mcp bridges --stop <pid> # stop one bridge (repeatable)

All of these accept --json. pme mcp with no subcommand (or pme mcp serve) runs the server; --socket <path> picks the service socket and --no-autostart makes encode tools fail instead of starting the service. What makes a bridge stale is explained under Connected assistants.

pme report

Report a problem to the developer from Terminal. PME builds the report itself: your PME and macOS versions, your Mac's model, chip and memory, and, for the jobs you name, their settings, errors, warnings, audit results and log lines. File and folder names are replaced by placeholders. Free on every tier.

pme report                                   # describe it, review it, send it
pme report --job 44E65B81-2DB1-431B-8375-7FBBF1FE82FE --summary "HEVC encode fails at 80%"
pme report --log latest                      # attach the newest session log instead of the newest failed one
pme report --summary "Test" --dry-run --json # print exactly what would be sent, and exit
pme report list                              # drafts waiting to be sent, and recent reports
pme report show <id>                         # a draft exactly as it would be sent
pme report send <id>                         # review and send a saved draft

Before anything is sent, pme report shows the report, asks for an optional email address (only if you'd like a reply) and whether to include file names (names only, never folders), then waits for you to type send. Pressing Enter keeps the report as a draft. Sending needs an interactive terminal: run from a script, or by an AI assistant running commands for you, pme report only saves a draft and prints how to send it. When pme transcode fails at a terminal, it saves a draft of the failure and prints the pme report send command. Drafts are kept for 7 days; drafts an AI assistant opens through MCP appear here too.

REST API

When the service is running, all endpoints are available over HTTP. Every request requires an Authorization: Bearer <token> header unless the server was started with --no-auth.

Endpoints

Watch folder errors carry error, a stable code (invalid_value, unsafe_path, exists, overlaps, busy, not_found, not_watching, watched_elsewhere, pro_required) and the field they concern. The API refuses to watch your home folder, Desktop, Documents, Downloads, Movies, Pictures or Music folder, system folders and whole volumes (unsafe_path), because pickup moves every media file it finds; pme watch may. Network share passwords are never accepted over the API. Jobs a watch folder makes carry watch_folder_id.

Submit a job

All fields except inputs are optional. Every pme transcode override is accepted under its snake_case name with the same values, so anything that works on the command line works here. Invalid values are rejected with a 400/404 that names the field; they are never silently ignored.

{
  "inputs": ["/path/to/input1.mxf", "/path/to/input2.mov"],
  "output_dir": "/path/to/output/",
  "codec": "hevc",
  "quality": 0.8,
  "auto_start": true
}

201 returns an array of job objects; each carries id, state, progress, input_path, output_path, requested vs. effective rate_control_*, encoder_preset_*, profile_*, frame_timing_* (e.g. auto → variable (kept), 29 fps base) and bitrate_* (with bitrate_scaling_note saying why a scaled bitrate is lower), started_at/completed_at (ISO 8601), output_file_size, retry_attempt, and its own warnings: every notice for the job, each once, covering what is known at submit (ML frame processing an FFmpeg-decoded source can't use, SDR-range preservation on an HLG source, a variable-frame-rate source, an odd size) and what the engine records while encoding. warning_message is the same list as one string. An image sequence job's output_path is the folder of frames, frame_pattern names the frames inside it (clip/clip.%07d.dpx), output_file_size is the frames' total, a finished job's frames_written counts them, and the sequence values it writes with are echoed under the option names (image_bit_depth, frame_numbering, ...). Trimmed jobs echo trim_reference, trim_in/trim_out (clip offsets) and source_start_timecode. held marks an auto_start: false job, and a queued job's wait_reason/wait_message say why it hasn't started (held, queue_paused, session_limit, arri_isolation, ...). Audited jobs carry audit_status (pending, then verified, needs_review or failed), safe_to_archive, audit_mismatches and audit_report_path; a job never reports completed with its audit still unknown. Each request gets one audit report, written when its last job finishes; until then its audited jobs carry audit_report_pending: true. 400 is an invalid value, 404 a missing input or preset, 409 an existing output without overwrite, and 403 a Pro feature on the free tier ({"code": "pro_required", "features": [...], "upgrade_url": ...}) or License Terms not yet accepted on this Mac ({"code": "terms_not_accepted", "terms_url": ...}; accept in the app or with pme terms accept). Poll GET /api/v1/jobs/:id or subscribe to events for progress.

By default the service listens on a Unix domain socket:

curl -X POST \
  --unix-socket "$HOME/Library/Application Support/ParallelMediaEncoder/pme.sock" \
  http://localhost/api/v1/jobs \
  -H "Authorization: Bearer $(pme service token)" \
  -H "Content-Type: application/json" \
  -d '{"inputs": ["/path/to/file.mxf"], "output_dir": "/output/", "codec": "hevc"}'

With pme service start --port 8080, the same API is available over TCP (localhost only):

curl -X POST http://localhost:8080/api/v1/jobs \
  -H "Authorization: Bearer $(pme service token)" \
  -H "Content-Type: application/json" \
  -d '{"inputs": ["/path/to/file.mxf"], "output_dir": "/output/", "codec": "hevc"}'

Server-Sent Events

Connect to /api/v1/events for real-time updates. Because EventSource can't set headers, this endpoint also accepts the token as a query parameter: /api/v1/events?token=<token>. The stream emits three event types:

• progress: per-file encoding progress (percentage, speed, ETA)
• state_change: job state transitions (queued, encoding, completed, failed)
• queue_status: overall queue summary updates

Available Codecs

Pass these IDs to --codec. DNxHR/DNxHD codecs and DPX, TIFF and OpenEXR sequences require a Pro license.

Containers: H.264/HEVC/ProRes write .mov. Passing a DNx codec via --codec writes .mxf; DNx via a preset follows the preset's container setting (.mov wrapper by default, matching the app).

Exit Codes

Use these codes to handle errors in scripts and CI pipelines.