Skip to content
Systemrunconvert · v0.1.0

RunConvert CLI

Convert files between 3,000+ formats from the terminal: an app you drag files into, one command for scripts and CI, and an MCP server so Claude, ChatGPT and Cursor can convert files for you. One small program, nothing else to install.

GitHub ↗npm ↗Overviewv0.1.0macOS · Windows · LinuxMIT

Installing

The install script downloads the latest release, checks it against its checksum and puts it on your PATH.

Terminal
curl -fsSL https://www.runconvert.com/install.sh | sh

It installs to ~/.local/bin. RUNCONVERT_VERSION pins a version and RUNCONVERT_INSTALL_DIR changes the folder.

With npm

Terminal
npm i -g @runconvert/cli      # or run it once: npx @runconvert/cli

Signing in

runconvert login opens runconvert.com: sign in, check the code matches and click Authorize. It makes an API key named “CLI · this computer” and saves it in the system keychain. New accounts get 10 free credits to try the CLI, once.

Terminal
runconvert login                # opens runconvert.com
runconvert login --no-browser   # servers and SSH: prints a link and a code
runconvert login --with-key     # paste a key from Dashboard → API keys
runconvert whoami               # who you're signed in as, and your credits
runconvert logout               # removes the saved key from this computer

In CI

Set RUNCONVERT_API_KEY instead of signing in. Revoke keys in Dashboard → API keys.

The app

Run runconvert on its own. Drag a file or folder in (or press Ctrl+O to pick files), pick a format, popular first, and press Tab for options like quality, size or bitrate. Your settings are remembered for next time.

Terminal
runconvert

# or just type what you want:
photo.heic to jpg
all videos in ~/Movies to mp4
talk.mp4 to mp3 192k

On servers and in CI the app never opens: piped, without a terminal, or with --no-input, runconvert prints help instead.

Convert

runconvert convert <files, folders, globs or URLs…> --to <format>. Each result is saved next to its input unless you choose a folder.

Terminal
runconvert convert photo.heic --to jpg
runconvert convert ./images/*.webp --to png --out ./png
runconvert convert "./Holiday Photos" --to jpg -r --keep-structure --out ./converted
runconvert convert ~/Downloads --only video --to mp4
runconvert convert talk.mp4 --to mp3 -o "./audio/{name}.{ext}" --opt audioBitrate=192k
runconvert convert https://example.com/report.docx --to pdf
runconvert convert *.png --to webp --json

Format

  • -t, --to <format>Output format, e.g. png, mp3, pdf. Required.
  • --from <format>Input format, when it can't be read from the file name.

Which files

  • --only <category>Only one category: image, video, audio, document, ebook, presentation, spreadsheet, vector, cad, archive, font.
  • -r, --recursiveInclude subfolders of folder inputs.

Where results go

  • --out <folder>Folder to save results in. Default: next to each input.
  • -o, --output <pattern>Output path pattern with {dir}, {name}, {ext} (new format) and {from} (old one).
  • --keep-structureRecreate subfolders in the output.
  • --overwriteReplace results that already exist. Default: skip them.

Settings and running

  • --opt name=valueA conversion setting; repeat it for more. runconvert formats <from> <to> lists the names.
  • --engine <name>Preferred engine, when a conversion has several.
  • --jsonPrint results as JSON, for scripts.
  • -p, --parallel <n>How many files to convert at once. Default 3.

Formats

What converts to what, and the settings each conversion takes.

Terminal
runconvert formats              # the 11 categories
runconvert formats video        # every video format
runconvert formats png          # everything PNG converts to
runconvert formats heic jpg     # the settings (--opt) for one conversion

Jobs

Every conversion is a job on your account. List them, see one’s details and download links, or stop one.

Terminal
runconvert jobs list --status finished --limit 5
runconvert jobs get <job-id>       # details and download links, as JSON
runconvert jobs cancel <job-id>

MCP

The CLI is also an MCP server, so AI apps can convert files with your account. runconvert mcp setup prints the exact setup for this computer.

On this computer

Terminal
runconvert mcp setup                       # Claude Code, Claude Desktop, Cursor, VS Code
claude mcp add runconvert -- runconvert mcp

Claude.ai and ChatGPT

Add https://mcp.runconvert.com/mcp as a connector and sign in. It converts files from links and returns download links.

Global flags

  • --key <key>API key. Default: RUNCONVERT_API_KEY, then the key saved by login.
  • --no-inputNever open the app (servers, CI). Same as RUNCONVERT_NO_INPUT=1.
  • -v, --versionPrint the version.
  • -h, --helpHelp for any command. runconvert help paths, help options and help env explain more.

Environment

  • RUNCONVERT_API_KEYAPI key, used when --key isn't given (CI, scripts, MCP configs).
  • RUNCONVERT_API_URLAPI address. Default https://api.runconvert.com.
  • RUNCONVERT_NO_INPUTSet to 1 to never open the app.
  • RUNCONVERT_NO_BROWSERSet to 1 to never open a browser on login.

Where the key is saved

In the system keychain. Where there is none (servers, containers), in a file only your user can read: ~/Library/Application Support/runconvert/config.json.

Like RunConvert? Set us as a preferred source on Google.

Add to Preferred Sources