Filee

Filee converts files offline. The filee command shares formats, presets and engines with the Filee app.

The command is filee on every OS. If the shell can't find it, Filee may be installed but not on PATH. On Linux and macOS the installer links it as $HOME/.local/bin/filee, so that folder has to be on PATH. On Windows, run cli\filee.cmd (or filee-cli.exe) from the Filee folder by its full path.

1. Check that Filee is installed

filee version

It prints something like filee 2.2.0 and exits with 0. If the command doesn't exist and you can't find the install, tell the user to download Filee from https://filee.sh and stop.

2. Check the conversion first

Ask Filee what a format can become before you convert:

filee formats md --json

Look at two lists in the result:

• targets: formats Filee can make right now.
• withEngines: formats Filee can make once the user gets an extra engine in the app.

If the target is in neither list, Filee can't do this conversion. Say so instead of trying.

3. Convert

Always pass --json --quiet and -o <folder>:

filee convert <files or folders...> --to <format> -o <folder> --json --quiet

Why --quiet: without it --json also writes progress events to stderr, one object per line, which get in the way when a shell merges stderr into stdout. The JSON result on stdout stays the same.

Why -o: results land in one folder you chose instead of wherever the app's output settings put them (usually next to the originals), so you can find them.

Other useful flags: --preset <preset> instead of --to (see filee presets --json), -r for sub folders, --sort <name|name-desc|modified|modified-desc|created|created-desc> for the order files merge in, --skip to leave existing outputs alone, --overwrite to replace them. By default Filee adds a number rather than overwriting.

4. Read the result

Exit code 0 doesn't mean every file was converted. It means no file failed or was cancelled. Always read the JSON on stdout.

In the JSON:

• converted, skipped, failed: counts for the whole run. failed also counts cancelled files.
• files[].state: done, skipped, failed or cancelled for each source.
• files[].outputs: the paths that were written. Use these exactly. Don't guess output names.

A file is converted only when its state is done and outputs isn't empty.

5. When a file fails

• If the failed file has needsEngines, Filee is missing an engine for this conversion. Tell the user which engine it names and ask them to open Filee, go to Settings → Engines, and get it. Then run the same command again.
• If the file's state is cancelled, the run was stopped before it finished. Tell the user it wasn't converted.
• Otherwise pass the file's error text on to the user. Don't retry blindly.

Examples

Convert one file

filee convert photo.png --to jpg -o converted --json --quiet

Output, trimmed to the fields that matter here:

{ "converted": 1, "failed": 0,
  "files": [ { "source": ".../photo.png", "state": "done",
               "outputs": [ ".../converted/photo.jpg" ] } ] }

Exit code 0, state is done, and the new file is the path in outputs.

A conversion that needs an engine

filee convert notes.md --to pptx -o converted --json --quiet

Output, trimmed:

{ "converted": 0, "failed": 1,
  "files": [ { "state": "failed", "outputs": [],
               "errorKey": "error.no_route", "needsEngines": [ "pandoc" ] } ] }

Exit code 1. Tell the user something like: "Filee needs the pandoc engine for this. Open Filee, go to Settings → Engines, get it, then I'll try again."