SDKs

Command line

The smol command: compress, convert and strip files from a terminal or a script, with the same options as the API.

Install

The smol command comes with the TypeScript SDK. It needs Node.js 18 or later.

bash

npm install -g https://smolmac.com/sdk/smolmac-api-0.1.0.tgz
export SMOL_API_KEY="smol_live_..."

smol compress photo.jpg

output

487 kB -> 79 kB (83.8% smaller), written to photo.min.jpg

The key is read from the SMOL_API_KEY environment variable. It is never taken from a command-line argument, so it does not end up in your shell history.

Commands

Command	What it does
`smol compress <file>`	Makes an image, PDF, audio or video file smaller.
`smol convert <file> --to <format>`	Converts to another format.
`smol strip <file>`	Removes metadata from an image or PDF without re-encoding it.
`smol estimate <file>`	Says what the request would cost. Nothing is sent but the file’s name and size. Add `--to` to estimate a conversion.
`smol usage`	Usage for the current month, or for `--from` and `--to` dates.

Options

Any option from the options reference is set with --set, written as its dotted path:

bash

smol compress photo.jpg --set image.format=avif --set image.quality=60
smol compress photo.jpg --set image.resize.width=1200 --set image.resize.height=1200
smol compress scans.pdf --set pdf.quality=small
smol convert photo.png --to webp
smol compress photo.jpg --preset web-hero --set image.quality=40

Flag	Meaning
`--set path=value`	One option. Repeat it for more.
`--preset name`	Start from a saved preset. `--set` values override it.
`-o, --output path`	Where to write the result.
`--force`	Overwrite the output file if it exists.
`--job`	Run as a job even if the file is small.
`--json`	Print the result object as JSON instead of a sentence.

Where the result goes

Without -o, the result is written beside the input with the result’s extension: photo.jpg to AVIF becomes photo.avif.
The input is never overwritten. If the result has the same name, .min is added: photo.min.jpg. If that exists too, a number is added: photo.min.2.jpg.
With -o, an existing file is refused before anything is sent, so the refusal costs nothing. Pass --force to overwrite.
If the file cannot be made smaller, nothing is written and nothing is charged. See Kept original.

Large files and jobs

Files over 25 MB, video and office documents run as jobs. The command does this by itself: it uploads the file (in parts when it is over 95 MB), waits, and downloads the result.

bash

smol convert report.docx --to pdf

output

Running as a job…
4 kB -> 17 kB (373.4% larger), written to report.pdf

In scripts

The exit status is 0 on success, 1 when the API or the file system reports an error, and 2 when the command was used wrongly.
Errors go to standard error, with the API’s error code and request ID.
--json prints the result object plus billed and output (the path written, or null).
SMOL_BASE_URL points the command at another address.

every JPEG in a folder to AVIF

for f in images/*.jpg; do
  smol compress "$f" --set image.format=avif --json | jq -r '.output'
done