Export Your Images from the Command Line

The optimole command-line tool can export the images in your Optimole library and download the ZIP parts for you. It runs the same export as Settings > Account > Export images in the dashboard: it starts the export, waits while Optimole prepares it, and downloads each part as soon as it is ready. This also makes it a good fit for regular backups from a script or a scheduled job. To print the URL of an image in your library instead, resized or converted, see Build Image URLs from the Command Line.

In this article

• Before You Start
• Export and Download Your Library
• Resume an Interrupted Download
• Download Options
• Check, List and Delete Exports
• Use the CLI in Scripts
• Troubleshooting

Before You Start

• Install the CLI and connect it to your account, as described in Upload Files to Optimole from the Command Line. If you installed it earlier, run the install command again to update it.
• Use your root API key. A sub API key cannot start or download exports.
• Check that the folder you download into has enough free space: an export takes about as much space as the images in your library.

Export and Download Your Library

Open a terminal in the folder where the export should go, and run:

optimole export start

The CLI starts an export and follows it until it is complete. Each ZIP part is downloaded as soon as Optimole has prepared it, while the next parts are still being prepared. The output lists each part, and ends with a summary:

Started export 42.
  example.com: running
  directUpload: running
Export 42: running
downloading optimole-export-42/example.com/images-1.zip (1.0 GB)
downloaded  optimole-export-42/example.com/images-1.zip (1.0 GB in 41s)
...
Export 42: completed

Export 42 completed: 2 downloaded, 0 already there, 0 failed (1.8 GB written) in optimole-export-42.

Your account runs one export at a time. If an export is already running, for example one you started in the dashboard, the CLI follows that export instead of starting a new one, and says Export 42 is already running; following it.

To start an export now and download it later, add --no-wait. The CLI prints the export's number and exits. When you are ready, run:

optimole export download

This downloads your latest export, and waits first if Optimole is still preparing it. To download an older export, add its number, for example optimole export download 42.

Where the Files Go

The CLI creates a folder named after the export. To put it somewhere else than the current folder, add -o with the destination, for example optimole export start -o /backups.

optimole-export-42/
  example.com/images-1.zip
  example.com/images-2.zip
  directUpload/images-1.zip
  export.json

• Each of your Allowed Domains gets its own folder, with the ZIP parts of its images.
• directUpload holds the files uploaded straight to your library, for example from the dashboard or with optimole upload.
• export.json lists every domain and part, with its size and whether it is downloaded.

The ZIP parts are not unpacked. To learn what they contain and how to extract them without losing files that share a name, see How To Export The Images From Optimole?.

Resume an Interrupted Download

If the download stops, for example because you pressed Ctrl+C or lost the connection, run the download again with the export's number:

optimole export download 42

The parts already on your computer are skipped, and a part that was cut off continues from where it stopped. Stopping the CLI does not stop the export: Optimole keeps preparing it. When you press Ctrl+C, the CLI prints the exact command to resume with.

Before it saves a part, the CLI checks that the part is complete and that every file in it is intact. A part that fails this check is downloaded again.

Download Options

optimole export start and optimole export download accept these options:

Option	What it does
-o FOLDER	Puts the export folder in this folder instead of the current one.
--domain NAME	Downloads only this domain's parts. You can repeat it. The export itself always covers every domain.
-c N	Downloads up to N parts at once, from 1 to 8. The default is 2.
--timeout DURATION	Stops waiting after this long, for example 90m or 2h. The export goes on in Optimole, and you can download it later.
--json	Prints one JSON object per line for each step, followed by a summary.
--no-wait	Only for optimole export start: starts the export and exits without downloading it.

Run optimole export start -h or optimole export download -h to see every option.

Check, List and Delete Exports

Command	What it does
optimole export status	Shows the latest export's status, and each domain's status, parts and size. Add an export number to see another export.
optimole export list	Lists your exports, newest first.
optimole export delete 42	Deletes a finished export and its ZIP parts from Optimole. Files you already downloaded stay on your computer.

Your account keeps up to 5 exports. Finished exports are deleted automatically 10 days after they finish.

Use the CLI in Scripts

• Set OPTIMOLE_API_KEY to provide your root API key.
• Add --timeout, so a scheduled job does not wait forever, and --json to get one JSON object per step, followed by a summary.
• Check the exit code: 0 means the export completed and every part is downloaded, 1 means the export failed, a part could not be downloaded, the timeout passed or your account already keeps 5 exports, 2 means the command itself was invalid, and 130 means the CLI was interrupted. With --no-wait, 0 means the export was started.

Each optimole export start creates a new export, so a daily job reaches the limit of 5 exports before the oldest ones are deleted automatically. Delete each export once it is downloaded:

optimole export start -o /backups --timeout 6h && optimole export delete "$(optimole export status --json | jq -r .id)"

Troubleshooting

"Full API access required"

The CLI is using a sub API key. Exports need your root API key: run optimole login and paste the root API key, or set it in OPTIMOLE_API_KEY.

"Maximum asset export count reached"

Your account already keeps 5 exports. The CLI names the oldest one: delete it with optimole export delete followed by its number, then start the export again. Run optimole export list to see all your exports.

"unknown command" for optimole export

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

"another optimole command is downloading into this folder"

Another optimole export command is downloading the same export into the same folder. Wait for it to finish, or download into a different folder with -o.

The export failed

If Optimole cannot export one of your domains, the export's status is failed. The parts of the other domains are still downloaded, and the CLI exits with 1. Start a new export to try again. If it fails again, see If the export status is Failed for what to send to support.