Image SEO and alt text Optimize images and alt text with Gemini CLI
Doing image SEO with Gemini CLI means asking Google's terminal agent to list your heaviest and unlabelled Shopify images through StoreSEO and then compress them and write alt text and file names one image per call, confirming each tool call as it goes.
Last updated: October 2026
Set up Gemini CLI for StoreSEO
Skip this if Gemini CLI is already connected. The full guide, with the alternatives, is on the Gemini CLI page.
- 1
Add StoreSEO to Gemini CLI
Run this in any terminal. The user scope writes the server to ~/.gemini/settings.json so every project sees it. Without --scope user the command writes to the current project's .gemini/settings.json.
Terminalgemini mcp add --scope user --transport http storeseo https://mcp.storeseo.com/mcp
- 2
Sign in to your store
Start gemini. The first time it calls StoreSEO it opens your browser: pick your Shopify store and approve access. If the window does not open, type /mcp auth storeseo inside Gemini CLI. Then gemini mcp list should show storeseo as connected.
Prompt/mcp auth storeseo
How does this work in Gemini CLI?
You run gemini in your theme folder and ask which product images have no alt text and which unoptimized files are heaviest. The model sees the StoreSEO tools as mcp_storeseo_ followed by the tool name, calls storeseo_start and storeseo_list_images, and shows each call in the terminal. Both are reads. The listing carries each image's compression, alt text and file name status, so Gemini CLI can print a ranked list or write it to a file in the folder for the next session.
Gemini CLI asks you to confirm an MCP tool call unless the server is trusted, and for this job that confirmation matters because storeseo_optimize_image compresses against the Image Optimizer quota and writes alt text and file names against AI credit. StoreSEO also tells the agent to name the spend and wait for your yes in the chat, so you answer once for the plan and once for each call the CLI prompts. Each call handles one image and returns a report for each axis, which Gemini CLI summarizes. If you want a tighter surface, includeTools on the server can limit what the model sees to the three image tools plus storeseo_start.
A rename changes the image's storefront URL, so ask Gemini CLI to search the theme for the old file name first, the way you would in any repository session. If you reject a result, storeseo_restore_image reverts compression, alt text or file name for that image, and the agent can re-list it afterwards to confirm the status changed.
-
You: Which product images have no alt text, and which unoptimized files are heaviest?
- storeseo_start read-only
- storeseo_list_images read-only
-
Gemini CLI: 28 images have no alt text, mostly on the Linen Shirt and Ceramic Mug products. The heaviest unoptimized file is 6 MB. Alt text spends AI credit, one image per call. Shall I start with the Linen Shirt images?
-
You: Yes, alt text for the Linen Shirt images.
- storeseo_optimize_image needs approval
-
Gemini CLI: First Linen Shirt image has alt text. Gemini CLI will ask you to confirm the next call.
What to ask Gemini CLI
Use StoreSEO to list my product images with no alt text, grouped by product. Do not change anything.
Compress the five heaviest unoptimized product images, one call each, and ask me before the first call.
Search this theme for the file names of the images you are about to rename, then write alt text and file names for the Linen Shirt images.
- Find my ten heaviest unoptimized product images and compress them. Tell me the quota it will use first.
- Which product images have no alt text at all? Write alt text for the ones on my best seller.
- Optimize every image on the product Canvas Tote: compression, alt text and file name.
- Restore the original alt text on the last image you changed.
- Give my collection images descriptive file names, and warn me which URLs will change.
What StoreSEO does: image seo and alt text
StoreSEO tracks three things per image: file-size compression, alt text and file name. The agent finds the heaviest or unlabelled images, optimizes them one call per image, and can restore any of the three if you do not like the result.
Requires: Compression needs the Image Optimizer add-on and counts against its monthly quota; alt text and file names spend AI Content Optimizer credit.
- 1
Find the images
The agent lists product, collection or article images, heaviest unoptimized first by default. It can filter to images with no alt text, or scope the list to one product by title.
- 2
Check what it found
A title search can also match image file names from other resources, so the agent checks each row belongs to the product you meant.
- 3
Agree the scope and cost
Compression uses image quota and alt text and file names use AI credit, so the agent confirms before working through many images.
- 4
Optimize one image per call
Each call takes the axes you want: compression, alt text, file name or all three. The axes always run compression, then file name, then alt text, and the response reports each one separately.
- 5
Report or restore
The agent reports what applied, what was already done and what was refused. If a result is wrong, the restore tool brings back the original file, alt text or name.
Image SEO and alt text reference
| Axes per image | Compression, alt text, file name |
|---|---|
| Image sources | Products, collections and articles (pages have no images) |
| Batching | One image per call; never two calls on the same image at once |
| Compression | Image Optimizer add-on and its monthly quota; an already compressed image is reported as already applied |
| Alt text and file name | AI Content Optimizer credit; both together are billed as one generation |
| File name change | Renames the file on Shopify and changes the image's storefront URL |
| Collection and article renames | Re-upload the image, so the call can take a couple of minutes |
| Restore | Reverts compression, alt text or file name per axis |
| Score impact | Alt text and file names count on products, collections and articles; compression counts on products |
Rules Gemini CLI follows
- The agent confirms the number of images and the kind of spend before a bulk run.
- One image per call, all wanted axes together; never parallel calls on the same image.
- A renamed image has a new URL, so the agent tells you, because anything that hard-coded the old URL keeps serving the old file.
- If a response is lost, the agent re-lists the image instead of retrying, because a retry regenerates and spends again.
- A refused axis, for example compression without the add-on, is reported as such while the other axes still apply.
In Gemini CLI
Do not set trust on the storeseo server for this job. Trust skips every tool confirmation, and with one image per call that would let storeseo_optimize_image and storeseo_restore_image run without any prompt, leaving only the confirmation StoreSEO asks for in chat. Google's site also says Gemini CLI was replaced by Antigravity CLI on June 18th, 2026 for the unpaid tier and Google One users, so if that is you, check which command-line agent your account can still use before relying on this setup.
What runs without asking. Reads such as SEO scores, store listings, settings and Google reports run straight away. Generating a preview spends AI credit but writes nothing, and StoreSEO tells the agent to say what a generation will cost before it runs one. Applying content, optimizing images, changing settings, publishing llms.txt or agents.md, writing a product description and deleting anything wait for your yes in the conversation. That yes is an instruction the agent follows, not a lock on the server, so your client's own tool-approval setting is the hard stop.
Questions
Should I trust the StoreSEO server in Gemini CLI to speed up image runs?
No. Trust skips every tool confirmation, so storeseo_optimize_image would run on each image with no prompt from the CLI. Keep it off and let Gemini CLI ask, since its confirmation is the hard stop alongside the yes StoreSEO tells the agent to wait for.
Can I limit Gemini CLI to just the image tools?
Yes. The includeTools list on the server controls which tools the model sees, so you can include storeseo_start, storeseo_list_images, storeseo_optimize_image and storeseo_restore_image and leave the rest out for an image-only session.
Can the agent compress images without the Image Optimizer add-on?
No. Compression needs the Image Optimizer add-on and counts against its monthly quota. Alt text and file names work without it and spend AI Content Optimizer credit instead.
Can I undo an image optimization?
Yes. The restore tool reverts compression, alt text or file name for one image, per axis. Restoring compression brings back the original file.
Why did my image URL change?
Giving an image a new file name renames the file on Shopify and re-points its storefront URL. Pages that use the image through Shopify keep working, but anything that hard-coded the old URL keeps the old file.
Can I write my own file name or alt text through the agent?
No. StoreSEO writes the alt text and file name from the resource's own context. You can steer the language, and you can always edit alt text yourself in Shopify admin.
Keep going
Image SEO and alt text with other agents
More Gemini CLI guides