FileConvertLab CLI Reference

FileConvertLab CLI — convert files from the terminal

v0.1.0

Installation

Download the archive for your platform, unpack it and put the fcl binary on your PATH. Each archive holds one binary with no runtime dependencies.

On Linux or macOS, download and install in one step (swap the archive name for your platform):

curl -L https://fileconvertlab.com/downloads/cli/fcl-linux-x64.tar.gz | tar -xz
sudo mv fcl-linux-x64/fcl /usr/local/bin/
fcl --version

A binary downloaded through a browser on macOS carries a quarantine flag and is blocked on first run; clear it with xattr -d com.apple.quarantine fcl. Downloads made with curl don't get the flag.

On Windows, unpack the archive with tar -xzf fcl-windows-x64.tar.gz in PowerShell or cmd and add the folder that holds fcl.exe to your PATH.

The Linux builds need glibc 2.30 or later (Ubuntu 20.04, Debian 11 and newer), the macOS build needs macOS 13 or later on Apple Silicon, and the Windows build runs on 64-bit Windows 10 and later.

Usage

fcl <COMMAND> [OPTIONS]

Global Options

--api-url <API_URL>Custom API base URL
--jsonPrint machine-readable JSON instead of human-readable progress
--helpPrint help
--versionPrint version

Commands

fcl login

Log in via browser (OAuth2 Device Flow)

fcl login

fcl logout

Log out and clear stored credentials

fcl logout

fcl convert

Convert one or more files to another format

fcl convert [OPTIONS] <FILES>

Arguments

<FILES>Input file paths; pdf-merge and ocr-multi-* pack several files into one ZIP job

Options

--to <TO>Target format: word, pdf, excel, png, epub; searchable-pdf, ocr-word or txt to read a scan; split, merge, delete-pages, watermark, anti-copy or extract-images for a PDF; extract for an archive
--operation <OPERATION>Backend operation to run as is, e.g. pdf-merge or gif-frames-to-png; see fcl ops
--asyncOnly upload and return job IDs, don't wait for completion
-o, --output <OUTPUT>Output file path, for a single input file or one packed job (pdf-merge, ocr-multi-*)
--out-dir <OUT_DIR>Directory to write results into, for several input files
--quality <QUALITY>Quality for lossy targets, 1-100
--dpi <DPI>Resolution in DPI, where the operation takes one
--ocr-language <CODE>Document language for OCR operations (e.g. ru, ja, ar); default is automatic
--pages <RANGES>Pages for split or delete-pages, e.g. 1-3,5
--text <TEXT>Watermark text
--option <KEY=VALUE>Any other option the operation accepts, as key=value; quote a value to keep it text, e.g. color="888888"; repeatable
--options-json <JSON>Options as a JSON object, e.g. '{"splitPoints":[1200,2400]}'; the flags above override its keys

fcl watch

Watch a folder and convert files as they appear

fcl watch [OPTIONS] <DIRECTORY>

Arguments

<DIRECTORY>Folder to watch

Options

--to <TO>Target format: word, pdf, excel, png, epub; searchable-pdf, ocr-word or txt to read a scan; split, delete-pages, watermark, anti-copy or extract-images for a PDF
--out-dir <OUT_DIR>Directory to write results into (default: alongside the input)
--interval <INTERVAL>Seconds between checks
--limit <LIMIT>Stop after this many conversions (0 keeps watching)
--quality <QUALITY>Quality for lossy targets, 1-100
--dpi <DPI>Resolution in DPI, where the operation takes one
--ocr-language <CODE>Document language for OCR operations (e.g. ru, ja, ar); default is automatic
--pages <RANGES>Pages for split or delete-pages, e.g. 1-3,5
--text <TEXT>Watermark text
--option <KEY=VALUE>Any other option the operation accepts, as key=value; quote a value to keep it text, e.g. color="888888"; repeatable
--options-json <JSON>Options as a JSON object, e.g. '{"splitPoints":[1200,2400]}'; the flags above override its keys

fcl status

Check the status of a conversion job

fcl status <JOB_ID>

Arguments

<JOB_ID>Job ID

fcl download

Download a completed conversion result

fcl download [OPTIONS] <JOB_ID>

Arguments

<JOB_ID>Job ID

Options

-o, --output <OUTPUT>Output file path

fcl whoami

Show current user info and limits

fcl whoami

fcl ops

List every operation with its input formats and --to targets

fcl ops [FILTER]

Arguments

[FILTER]Only operations whose name contains this text

Authentication

fcl login starts the OAuth2 Device Flow: the command prints a URL and a short code, you open the URL in any browser, sign in, and enter the code — your password never touches the terminal. Once approved, the CLI stores an access token locally and reuses it for every later command until you run fcl logout.

For CI and other non-interactive environments, run fcl login once on your own machine and store the credentials file it writes (credentials.json in the fcl folder of your config directory, ~/.config/fcl on Linux) as a CI secret; restore it before fcl runs. The file holds a refresh token valid for 30 days, and fcl uses it to get a fresh access token on every run. FCL_ACCESS_TOKEN also works, but an access token expires after one hour and can't be refreshed that way. Run fcl whoami to confirm who you're signed in as; if the session has expired, fcl falls back to guest limits.

Converting Files

fcl convert takes one or more input files and a target format. By default it uploads each file, waits for the conversion and saves the result next to the original under the extension of the file the server returns; -o sets the path for a single file and --out-dir a folder for several.

Pass a glob to convert a whole folder at once, or run fcl watch to keep converting files as they land in a folder:

fcl convert *.pdf --to word --out-dir converted
fcl watch ./inbox --to pdf --out-dir ./outbox

Queue every job with the async option instead of waiting for each conversion to finish before starting the next, then check on them afterward and pull down the finished files once they're ready.

Examples

Convert a PDF to Word

fcl convert document.pdf --to word
# Saved to document.docx

Convert with custom output path

fcl convert report.pdf --to excel -o report-tables.xlsx

Async conversion (background)

fcl convert large-file.pdf --to word --async
# Job created: a1b2c3d4-...
 
fcl status a1b2c3d4-...
# Status: COMPLETED
 
fcl download a1b2c3d4-...

Several files at once

fcl convert *.png --to jpg --quality 80 --out-dir converted/
# Saved to converted/first.jpg
# Saved to converted/second.jpg

Machine-readable output for a script

fcl --json convert scan.png --to excel
# {"input":"scan.png","jobId":"job_abc","operation":"image-to-excel","status":"completed","output":"scan.xlsx"}
 
fcl --json convert *.docx --to pdf | jq -r 'select(.status=="failed") | .input'

Operation options

fcl convert photo.jpg --to webp --quality 70
fcl convert scan.png --to dpi --dpi 300 --option resample=true
fcl convert deck.pptx --to pdf --option speakerNotes=true --option hiddenSlides=true
fcl convert report.pdf --to pdfa --option version=1

PDF page tools

fcl convert report.pdf --to split --pages 1-3,5
# Saved to report.zip
fcl convert report.pdf --to delete-pages --pages 2
fcl convert report.pdf --to watermark --text DRAFT --option opacity=0.2
fcl convert report.pdf --to extract-images

Merge several PDFs into one

fcl convert cover.pdf report.pdf appendix.pdf --to merge -o full.pdf
# Saved to full.pdf

Any operation by name

fcl ops gif
# gif-frames-to-png  gif  frames-png
fcl convert animation.gif --operation gif-frames-to-png
# Saved to animation.zip
fcl convert page1.png page2.png --operation ocr-multi-png-to-pdf

Text out of a scan

fcl convert scan.pdf --to txt --ocr-language de
# Saved to scan.txt

E-books

fcl convert novel.epub --to mobi
fcl convert novel.fb2 --to pdf

Watch a folder

fcl watch ~/inbox --to pdf --out-dir ~/converted --interval 5
# Watching /home/you/inbox for new files to convert to pdf.
# 0 files already there are left alone. Press Ctrl+C to stop.

Authentication

fcl login
#   To authenticate, open this URL in a web browser:
#     https://fileconvertlab.com/auth/device
#   Then enter this code: ABCD-1234
 
fcl whoami
# User: john (john@example.com)
# Credits: 50/min, 200/day

Scripting fcl in CI

Every command exits with a non-zero status and prints an error message to stderr when a step fails — a missing input file, a rejected upload, or a failed conversion. Standard shell and CI conventions apply: check the exit code rather than parsing the human-readable output.

In a pipeline, skip fcl login: store an API key from your account page as a masked secret named FCL_API_KEY, and fcl sends it with every request. A key does not expire. Add --async to submit a batch of files, move on, and collect the results later with the status and download commands.

Supported Formats

PDF
worddocexcelcsvpdfapowerpointpngjpghtmlmarkdownepub
PDF tools
compressunlocksplitmergedelete-pageswatermarkanti-copyextract-imagesvalidate-pdfa
Scans (.pdf, .png, .jpg)
searchable-pdfocr-wordtxt
Word (.docx, .doc)
pdfdocxpngjpgodtrtftxtepub
Excel (.xlsx, .xls)
pdfxlsx
PowerPoint (.pptx, .ppt)
pdfpptx
iWork (.pages, .numbers, .key)
docxxlsxpptx
Text (.txt)
docxodtrtf
RTF (.rtf)
docxodttxt
ODT (.odt)
pdfdocxrtftxtepub
HTML (.html)
pdf
E-books (.epub, .mobi, .azw3, .fb2)
epubmobiazw3fb2pdfdocxhtmltxtrtfodt
Table images (.png, .jpg, .tiff)
excelcsv
Images (.jpg, .png, .webp, .gif, .bmp, .tiff, .svg, .ico, .heic)
jpgpngwebpgifbmptiffsvgicopdfcompressdpino-exif
Animated GIF (.gif)
frames-pngframes-jpgframes-webpframes-bmpframes-tiffframe-pngframe-jpg
Long screenshots (.jpg, .png, .webp)
long-pdflong-pptupscaleno-background
Audio (.mp3, .wav, .ogg, .flac, .aac, .m4a, .wma)
mp3wavoggflacaacm4awmacompress
Video (.mp4, .avi, .mkv, .mov, .wmv, .flv, .webm)
mp4avimkvmovwmvflvwebmgifmp3compress
Archives (.zip, .7z, .tar.gz, .tar.bz2, .tar.xz, .rar)
zip7ztar.gztar.bz2tar.xzextract

Environment Variables

FCL_API_URLOverride the API base URL
FCL_API_KEYAuthenticate with an account API key instead of a login (CI)
FCL_ACCESS_TOKENUse a specific access token (skip login)