convertr

convertr

Русская версия

Universal file format converter. One binary, 50+ formats, CLI, TUI, Web UI, REST API, and automatic route selection.

convertr wraps pandoc, ffmpeg, LibreOffice, ImageMagick, jq, yq, Tesseract, csvkit, AsciiDoctor, Calibre, pdfcpu, and plugin backends behind one command:

convertr FILE -o OUT

It detects formats, checks installed backends, and picks a conversion route automatically. If no direct route exists, it can chain available tools.

Why use it?

• One interface for documents, media, data, OCR, and PDF tools.
• Automatic routing over installed backend capabilities.
• Batch conversion with workers, retry policy, and conflict handling.
• Watch mode for converting files as they change.
• Unicode safety controls for Cyrillic PDF output and strict text-layer checks.
• TUI, built in Web UI, REST API, Docker image, and plugin protocol.

Install

Go

go install github.com/Mark1708/convertr/cmd/convertr@latest

Requires Go 1.25+.

Homebrew

brew install mark1708/tap/convertr

Source

git clone https://github.com/Mark1708/convertr.git
cd convertr
go build -o ~/.local/bin/convertr ./cmd/convertr

Backend tools

Install common conversion tools:

# macOS
./scripts/install-deps-macos.sh

# Debian or Ubuntu
./scripts/install-deps-linux.sh

Check what is available:

convertr version
convertr doctor

doctor prints installed tools, versions, paths, and install hints for missing backends.

First conversion

# Format is inferred from extensions.
convertr report.docx -o report.md

# Target format can be explicit.
convertr notes.md --to pdf -o notes.pdf

# Require Unicode-safe PDF text when Cyrillic is detected.
convertr notes.md --to pdf -o notes.pdf --unicode-mode strict

# Stdin to stdout.
cat data.json | convertr - --from json --to yaml -o -

Common workflows

# Convert a directory recursively.
convertr -r ./docs -o ./out --to md --mkdir

# Use 4 workers and retry failed jobs.
convertr -r ./inbox -o ./outbox --to pdf -j 4 --on-error retry --mkdir

# Preview the plan without writing files.
convertr -r ./docs -o ./out --to md --dry-run

# Prefer higher fidelity routes.
convertr source.docx -o out.pdf --route-policy quality

# Reject lossy route edges.
convertr image.png -o out.webp --avoid-lossy

# Limit route length.
convertr source.md -o out.pdf --max-hops 2

# Watch a directory and convert on every change.
convertr watch ./inbox -o ./outbox --to md

# Inspect formats and the conversion graph.
convertr formats
convertr formats --dot | dot -Tsvg > /tmp/formats.svg

More examples are in docs/workflows.md.

Interfaces

CLI

The CLI is the default interface for single files, batches, watch mode, PDF tools, backend checks, config, and plugins.

convertr --help
convertr backends list
convertr pdf merge -o bundle.pdf a.pdf b.pdf

Full reference: docs/cli.md.

Web UI and REST API

convertr serve
convertr serve --addr 127.0.0.1:8080

The browser UI supports uploads, route preview, Unicode safety selection, downloads, backend status, and PDF tools. Use --api-only when you only need the REST API.

• Web UI guide: docs/web-ui.md
• REST API: docs/api.md

TUI

convertr tui

Use the terminal UI to inspect backend status, preview routes, adjust route policy and Unicode mode on preview screens, and run an interactive conversion. Guide: docs/tui.md.

Docker

Use ghcr.io/mark1708/convertr for the full backend image with CLI, Web UI, and REST API. See docs/docker.md for tags, run commands, volumes, health checks, and image notes.

Configuration

Create a config file:

convertr config init
convertr config print
convertr config validate

Default path: ~/.config/convertr/config.toml. CLI flags override environment variables, which override the config file, which overrides built in defaults.

Common environment overrides:

• CONVERTR_QUALITY
• CONVERTR_WORKERS
• CONVERTR_ON_ERROR
• CONVERTR_ON_CONFLICT

Config fields and backend options are documented in docs/cli.md.

Backends and plugins

convertr removes missing backend capabilities from the graph at startup. Install tools, then run:

convertr doctor
convertr backends status

External plugins are executables named convertr-* in PATH.

convertr plugins list
convertr plugins test

Backend details and plugin protocol: docs/cli.md.

Demo gallery

VHS demo tapes live in docs/demos. Only the CLI basics GIF is committed. Render the full local gallery with:

make demo

More docs

• CLI reference
• Web UI guide
• TUI guide
• Workflows
• REST API
• Docker
• Demo gallery
• Remediation audit
• Contributing
• Security

Contributor checks

make build
make test
make lint

CI also runs go vet, race enabled tests, go build ./..., and govulncheck.

License

MIT, see LICENSE.