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.

Linux x64fcl-linux-x64.tar.gzLinux ARM64fcl-linux-arm64.tar.gzmacOS Apple Siliconfcl-macos-arm64.tar.gzWindows x64fcl-windows-x64.tar.gz

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

fcl logout

Log out and clear stored credentials

fcl convert

Convert one or more files to another format

fcl watch

Watch a folder and convert files as they appear

fcl status

Check the status of a conversion job

fcl download

Download a completed conversion result

fcl whoami

Show current user info and limits

`fcl login`

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

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

--asyncOnly upload and return job IDs, don't wait for completion

-o, --output <OUTPUT>Output file path, for a single input file

--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

`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

`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

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

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.

Restore the stored credentials file for non-interactive login, add --async for fire-and-forget submission, and a pipeline can upload a batch of files, move on immediately, and come back later to collect results with the status and download commands.

Supported Formats

PDF

worddocexcelcsvpdfapowerpointpngjpghtmlmarkdownepub

PDF tools

compressunlocksplitdelete-pageswatermarkanti-copyextract-images

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

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)

zip7ztar.gztar.bz2tar.xz

Environment Variables

FCL_API_URLOverride the API base URL

FCL_ACCESS_TOKENUse a specific access token (skip login)

FileConvertLab CLI Reference

Installation

Usage

Global Options

Commands

fcl login

fcl logout

fcl convert

Arguments

Options

fcl watch

Arguments

Options

fcl status

Arguments

fcl download

Arguments

Options

fcl whoami

Authentication

Converting Files

Examples

Convert a PDF to Word

Convert with custom output path

Async conversion (background)

Several files at once

Machine-readable output for a script

Operation options

PDF page tools

Text out of a scan

E-books

Watch a folder

Authentication

Scripting fcl in CI

Supported Formats

Environment Variables

Cookie Consent

`fcl login`

`fcl logout`

`fcl convert`

`fcl watch`

`fcl status`

`fcl download`

`fcl whoami`