Upload Files to Optimole from the Command Line

The optimole command-line tool uploads files from your computer into your Optimole library, into the folders you choose. It can upload a single file or a whole folder tree, and it also works in scripts and CI jobs.

In this article

• Install the CLI
• Connect the CLI to Your Account
• Upload Files
• Use a Sub API Key
• What You Can Upload
• Use the CLI in Scripts
• Troubleshooting

Install the CLI

The installer downloads the build for your system, checks it, and needs no administrator rights.

macOS and Linux

Open a terminal and run:

curl -fsSL https://raw.githubusercontent.com/Codeinwp/optimole-cli/main/install.sh | sh

Windows

Open PowerShell and run:

irm https://raw.githubusercontent.com/Codeinwp/optimole-cli/main/install.ps1 | iex

To check the installation, run optimole version. If your terminal answers that the command is not found, open a new terminal window: the installer adds the tool to your PATH, and terminals that were already open do not see the change.

To update the CLI, run the same install command again. Other ways to install it, such as downloading the archive yourself, are described on the optimole-cli GitHub page.

Connect the CLI to Your Account

The CLI signs in with an API key from your Optimole dashboard.

1. Log in to your Optimole Dashboard and go to Settings > API Keys.

2. Copy your API key, or create a new one for the CLI.

3. In your terminal, run:

   optimole login

4. Paste the key and press Enter. The key stays hidden while you paste it.

The CLI checks the key and saves it in your user profile, readable only by you. Run optimole logout to remove the saved key.

💡 Tip: In a script or CI job, set the key in the OPTIMOLE_API_KEY environment variable instead of running optimole login.

Upload Files

Upload Single Files

Name the files after optimole upload. Without a folder, they go to the root of your library:

optimole upload logo.png

To upload into a folder, add --folder with the folder's path in your library:

optimole upload --folder "Brand/Logos" logo.png logo-dark.png

Each uploaded file is listed with its Optimole URL, followed by a summary:

uploaded  logo.png -> Brand/Logos  https://xyz.i.optimole.com/w:auto/h:auto/q:auto/id:4f.../directUpload/logo.png
uploaded  logo-dark.png -> Brand/Logos  https://xyz.i.optimole.com/w:auto/h:auto/q:auto/id:9c.../directUpload/logo-dark.png

2 uploaded, 0 skipped, 0 failed (2 files).

Upload a Whole Folder

Add -r to upload the contents of a folder on your computer. Its subfolders become folders in your library, below the folder you name:

optimole upload -r ./photos --folder Campaigns

On your computer	In your library
photos/a.jpg	Campaigns
photos/2024/b.jpg	Campaigns/2024
photos/2024/raw/c.jpg	Campaigns/2024/raw

The folders must already exist in your library. Add --create-folders to create the missing ones:

optimole upload -r ./photos --folder Campaigns --create-folders

To see where each file would go without uploading anything, add --dry-run. To list the folders in your library, run optimole folders.

Upload Options

Option	What it does
--folder PATH	Uploads into this folder, for example Campaigns/2026/Spring. Folder names match regardless of case.
--create-folders	Creates the folders that do not exist yet.
-r	Uploads the contents of folders, including their subfolders.
--exclude PATTERN	Skips matching files or folders, for example --exclude '*.psd'. You can repeat it.
--include-hidden	Also uploads hidden files and folders (names starting with .), which are skipped by default.
-c N	Uploads up to N files at once, from 1 to 16. The default is 4.
--dry-run	Shows where each file would go, without uploading anything.
--json	Prints the results as JSON, one line per file.

Run optimole upload --help to see every option.

Use a Sub API Key

A sub API key can upload only into the folders that were shared with it, and into their subfolders. This lets you give the CLI to a teammate or a client without sharing your root API key. To create a sub API key and share folders with it, see How to enable folder sharing in Optimole.

With a sub API key, always name the destination with --folder:

optimole upload -r ./client-photos --folder "Clients/Acme"

A sub API key cannot:

• upload into the root of your library;
• create folders, so --create-folders does not work with it. Create the folders in your library first, or with your root API key;
• list your folders with optimole folders.

What You Can Upload

Each file can be up to 100 MB. Images, videos, audio files, documents and archives are accepted. Web pages, scripts and programs (such as .html, .js and .exe files) are always refused.

Files that cannot be uploaded are listed as skipped, and the CLI goes on with the others. The files you upload count towards your plan's upload limit.

Use the CLI in Scripts

• Set OPTIMOLE_API_KEY to provide the key.
• Add --json to get one JSON object per file, with its status (uploaded, skipped or failed) and Optimole URL, followed by a summary.
• Check the exit code: 0 means every file was uploaded, 1 means at least one file failed, and 2 means the command itself was invalid, so nothing was uploaded.

optimole upload -r ./photos --folder Campaigns --json | jq -r 'select(.status=="uploaded") | .url'

Troubleshooting

"The selected folder is invalid"

The folder does not exist in your library. Check its path with optimole folders, or add --create-folders to create it. With a sub API key, the folder must be one of the folders shared with the key.

"folder_required" or "folder_creation_forbidden"

You are using a sub API key. Add --folder with a folder shared with the key, and remove --create-folders.

"upload_limit_reached"

Your account has reached its plan's upload limit. The CLI stops, and lists the files it did not send. See What happens if I exceed plan limits.

The upload slows down on large batches

The Optimole API limits how many requests your account can send per minute. When a large batch reaches that limit, the CLI waits and continues on its own.