Build Image URLs from the Command Line

The optimole url command of the optimole command-line tool prints the Optimole URL of an image, with the size, crop, quality or format you ask for. It takes the image's asset key or an Optimole URL you already have. It also reads what optimole upload prints, so you can upload images and get their URLs in one command. To install the tool and upload files with it, see Upload Files to Optimole from the Command Line.

In this article

• Before You Start
• Get an Image's URL
• Options
• How the CLI Changes a URL
• Pipe Commands Together
• Use the CLI in Scripts
• Troubleshooting

Before You Start

• Install the CLI, as described in Install the CLI. If you installed it earlier, run the install command again to update it.
• To look up images by their asset key, connect the CLI to your account, as described in Connect the CLI to Your Account. Your root API key and sub API keys both work. A sub API key can look up only the images in the folders shared with it.
• To change an Optimole URL you already have, you do not need an API key. The CLI changes the URL on your computer, without contacting Optimole.

Get an Image's URL

From an Asset Key

Each image in your library has an asset key: the 32 characters after id: in its URL. optimole upload --json also prints it, as key. Name the key after optimole url, followed by the options you want:

optimole url 42cf6621995747f69a30d32f6a6c4f82 --width 800 --format webp

The CLI looks up the image in your account, and prints its URL with your options:

https://xyz.i.optimole.com/w:800/h:auto/q:auto/f:webp/id:42cf6621995747f69a30d32f6a6c4f82/directUpload/photo.jpg

If your account serves images from a custom domain, the URL uses that domain.

From a URL

To change a URL that you copied from the dashboard, from your website or from an earlier command, name the URL instead of a key. Put it in quotes, so that your terminal passes it on unchanged:

optimole url 'https://xyz.i.optimole.com/w:auto/h:auto/q:auto/id:42cf6621995747f69a30d32f6a6c4f82/directUpload/photo.jpg' --quality 60

https://xyz.i.optimole.com/w:auto/h:auto/q:60/id:42cf6621995747f69a30d32f6a6c4f82/directUpload/photo.jpg

This also works for the URLs of images that Optimole serves from your website, such as https://xyz.i.optimole.com/w:auto/h:auto/q:auto/https://example.com/wp-content/uploads/hero.jpg.

You can name several keys and URLs in one command. The CLI prints one URL per line, in the same order.

Options

Option	URL part	What it does
--width N	w:	The width in pixels, or auto.
--height N	h:	The height in pixels, or auto.
--resize TYPE	rt:	How the image fits the width and height: fit, fill, fill-down, force or auto. See Resize Types.
--gravity POS	g:	The part of the image that fill keeps: center, top, bottom, left, right, top-left, top-right, bottom-left, bottom-right or smart.
--focus X:Y	g:fp:	The point that fill keeps, as fractions of the width and height: 0:0 is the top left corner, 1:1 the bottom right corner, and 0.5:0.2 the middle, near the top.
--quality Q	q:	auto, mauto, eco, or a number from 1 to 100. mauto is the machine-learning Auto-Quality.
--format F	f:	auto removes a forced format, so that each browser gets AVIF or WebP when it accepts them. To serve one format to every browser, use webp, jpg, png, gif, ico, jxl or heic. AVIF cannot be forced: browsers that accept it get it with auto.
--dpr N	dpr:	The pixel density, from 1 to 5, for example 2 for high-density (Retina) screens.
--download	att:1	Serves the image as a download instead of showing it in the browser.
--set NAME:VALUE	any	Sets another option that Optimole reads, for example --set bl:5 for a blur. You can repeat it.
--unset NAME		Removes an option from the URL, for example --unset q. You can repeat it.
--reset		Starts from w:auto/h:auto/q:auto, and drops the other options of the URL.

Run optimole url -h to see every option.

To add a cache buster, which makes the CDN serve a fresh copy of the image, use --set cb: with a value such as abc.1. Optimole ignores a cache buster unless it has at least 3 characters, a dot, and then at least 1 more character. To learn when to use one, see Using Cache Tokens.

Resize Types

Type	What it does
fit	The default. Keeps the aspect ratio, and makes the image fit inside the width and height.
fill	Keeps the aspect ratio, fills the width and height, and cuts off what sticks out. --gravity or --focus sets the part it keeps.
fill-down	Like fill, but an image smaller than the width and height is only cut to their aspect ratio.
force	Ignores the aspect ratio, and stretches the image to the width and height.
auto	Works like fill when the image and the size have the same orientation (both landscape or both portrait), and like fit otherwise.

For example, this command makes a 1200 × 600 banner that keeps the top of the image:

optimole url 42cf6621995747f69a30d32f6a6c4f82 --width 1200 --height 600 --resize fill --gravity top

How the CLI Changes a URL

• An option that is already in the URL is replaced, never added a second time. Optimole uses only the first copy of an option, so a second w: has no effect. For example, --width 800 turns w:auto into w:800.
• The options you do not name stay as they are. Use --unset to remove one, or --reset to start over from w:auto/h:auto/q:auto.
• The options are written in the order Optimole applies them, so the same options always give the same URL.
• Two options that change the same part of the URL, such as --width and --set w:900, or --gravity and --focus, are an error.
• Each value is checked before anything is printed. A value that Optimole ignores, or answers with an empty image, is refused with a message that says what is expected.
• Files that are not images, such as PDFs, are printed as they are. Options that change images are an error for them.

Pipe Commands Together

When you name no key or URL, optimole url reads them from the previous command, one per line. It also reads the JSON lines that optimole upload --json and optimole url --json print, so you can upload images and get their URLs in one command:

optimole upload -r ./photos --json | optimole url --width 1200

https://xyz.i.optimole.com/w:1200/h:auto/q:auto/id:4f.../directUpload/a.jpg
https://xyz.i.optimole.com/w:1200/h:auto/q:auto/id:9c.../directUpload/b.jpg

A file that the upload skipped has no URL. The CLI reports it, for example optimole url: photos/b.psd: the JSON line has no "url" (status skipped), prints the other URLs, and exits with 1.

Each optimole url in a pipe changes what the previous one printed:

optimole url 42cf6621995747f69a30d32f6a6c4f82 --width 800 | optimole url --resize fill --height 400 --gravity top

To change a list of URLs saved in a file, one per line, read the file:

optimole url --format webp < urls.txt

Use the CLI in Scripts

• Set OPTIMOLE_API_KEY to provide the API key. Only asset key lookups need it.
• Add --json to get one JSON object per key or URL, in the same order. Each object has input and url, and, when they are known, key, mime_type, original_width and original_height. For a key or URL that failed, the object has input, error and code, which is invalid_input, not_found, no_url or not_an_image.
• Add -c N to look up up to N keys at once, from 1 to 16. The default is 4.
• Check the exit code: 0 means every URL was printed, 1 means at least one key or URL failed (the others are still printed) or the API key was rejected, 2 means the command was invalid or no API key was set for a key lookup, and 130 means the CLI was interrupted.

Changing a URL does not contact Optimole, so a script can look up an asset key once and then change its URL as often as it needs. For example, to print the srcset entries of an image at three widths:

url=$(optimole url 42cf6621995747f69a30d32f6a6c4f82)
for w in 480 800 1200; do
  echo "$(optimole url "$url" --width "$w") ${w}w"
done

https://xyz.i.optimole.com/w:480/h:auto/q:auto/id:42cf6621995747f69a30d32f6a6c4f82/directUpload/photo.jpg 480w
https://xyz.i.optimole.com/w:800/h:auto/q:auto/id:42cf6621995747f69a30d32f6a6c4f82/directUpload/photo.jpg 800w
https://xyz.i.optimole.com/w:1200/h:auto/q:auto/id:42cf6621995747f69a30d32f6a6c4f82/directUpload/photo.jpg 1200w

Troubleshooting

"AVIF cannot be forced"

Optimole does not serve AVIF to every browser: it drops f:avif from the URL. Use --format auto instead. Browsers that accept AVIF get AVIF, and the others get WebP when they accept it, or the original format.

"must be fit, fill, fill-down, force or auto"

The resize type is not one that Optimole offers, for example --resize crop. To cut the image to the width and height, use --resize fill, with --gravity or --focus to choose the part it keeps.

The Cache Buster Is Refused

The message says that the value must look like "abc.1". Optimole ignores a cache buster (cb:) unless it has at least 3 characters, a dot, and then at least 1 more character, so the CLI refuses any other value. Use a value such as abc.1, or a cache token, as described in Using Cache Tokens.

"both change the w option"

Two of your options change the same part of the URL, for example --width 800 and --set w:900, or --gravity and --focus. Keep only one of them.

"is not an option the CDN reads"

The name after --set or --unset is not an option that Optimole reads, so it has no effect. Check the spelling of the name, for example bl for a blur.

"no such asset, or this API key cannot see it"

No image in your account has this asset key, or you are using a sub API key and the image is not in a folder shared with it. Check the key, or use your root API key.

"not an Optimole URL"

The CLI changes only Optimole URLs: URLs on your Optimole domain or your custom domain, with the image's id: or your website's image URL in the path. A URL on your website itself, such as https://example.com/photo.jpg, is not an Optimole URL. To get the Optimole URL of an image in your library, give its asset key instead.

The rest of the message says what is wrong. For example, it contains spaces or control characters means that the URL was cut, or pasted with a space in it.

"not an image (a file URL)"

Files that are not images, such as PDFs, cannot be resized or converted. Their URLs contain /files/. Without options, optimole url prints their URL as it is.

"which the CDN reads as an option"

The image's path on your website contains a part that looks like an Optimole option, such as w:9, and the URL does not set that option itself. Optimole reads that part as an option, so the CLI refuses the URL. Set the option yourself, for example with --width auto, and the URL works.

The API Key Is Rejected or Missing

The message says The API key (from ...) was rejected. or no API key. Looking up an asset key needs a valid API key: run optimole login and paste your API key, or set it in OPTIMOLE_API_KEY. Changing a URL needs no API key.

"unknown command" for optimole url

Your copy of the CLI does not have the url command yet. Run the install command again to update it, as described in Install the CLI.