---
title: "AI & CLI Integration"
description: "Connect Zipic to AI agents like Claude Desktop, Cursor and your own scripts via the zipic CLI and URL Scheme — let agents compress and convert images as part of larger automated workflows."
canonical: https://docs.zipic.app/ai/overview/
source: zipic.doc
mirroredAt: 2026-10-22T13:30:05.417Z
---
Zipic is more than a GUI app. With the `zipic` CLI (new in 1.9.5), URL Scheme, Shortcuts, and AppIntents, you can drive every compression capability from a shell script, a CI pipeline, or an AI agent like Claude Code — all while keeping the privacy benefits of 100% local image processing — your images are never uploaded.

## The `zipic` CLI — designed to be agent-friendly

Zipic 1.9.5 ships with a built-in `zipic` command-line client that talks to the running Zipic app over a Unix domain socket. **For AI agents and scripts, this is the recommended entry point** — it reuses the GUI's compression pipeline, presets, and license state, while exposing a contract designed for programmatic use.

```bash
# Compress a folder to WebP at level 3, emit one JSON line per file
zipic compress ~/Pictures --level 3 --format webp --json
```

### Why CLI beats URL Scheme for agents

| Capability | `zipic` CLI | URL Scheme |
|---|:---:|:---:|
| Exit codes that signal success / failure | ✅ | ❌ (fire-and-forget) |
| Structured `--json` output per file | ✅ | ❌ |
| Machine-readable Pro / quota errors (`purchase_url`, `blocked_format`, `remaining`) | ✅ | ❌ |
| `--dry-run` to preview before acting | ✅ | ❌ |
| Returns when work is done (synchronous) | ✅ | ❌ |
| Smart Skip results visible in stdout | ✅ | ❌ |

This is the difference between an agent that *fires and hopes* and an agent that *acts, reads, decides*. With `--json`, your agent can parse `state: "success"` vs. `state: "kept_source"`, branch on `error.data.purchase_url` when the user hits a Pro feature, or fall back to a different format when `blocked_format` is reported.

### Agent-friendly example

```bash
# Dry-run first to confirm the plan
zipic compress ~/Downloads/screenshots --format webp --level 3 --dry-run --json

# Then actually compress, parsing each result line
zipic compress ~/Downloads/screenshots --format webp --level 3 --json | \
  jq -c 'select(.state == "success") | {file: .source, saved: .saved_bytes}'
```

If the agent encounters a Pro restriction, the JSON error object carries the exact reason and a purchase URL — your agent can surface that to the user verbatim instead of guessing.

For the full command reference (presets, history, all flags, exit codes, the socket protocol), see [**Command Line Tool**](/guides/zipic-cli/).

## URL Scheme — the lightweight fallback

If your environment can't run a binary (for example, an iOS Shortcut, a `.command` file shared with non-technical users, or a one-shot Raycast snippet), the URL Scheme is still fully supported:

```bash
open "zipic://compress?url=/path/to/image.png&level=3&format=webp"
```

It's fire-and-forget — no exit code, no return data — but ideal for triggering compression from environments that can't run a CLI. Full parameter reference, batch examples, Shortcuts download, and AppIntents details: [**Integrating Zipic Capabilities**](/guides/optimizing-workflow/).

## AI Agent Skill (One-Command Install)

Claude Code and other agent-skill-compatible tools can install the Zipic skill in one command. Once installed, you can talk to your AI agent in natural language — *"compress these screenshots"*, *"convert this PNG to WebP"*, *"shrink these images to 1920px wide"* — and the agent will translate your intent into the right Zipic call (CLI or URL Scheme depending on the environment).

Install the skill:

```bash
npx skills add okooo5km/Skills4U --skill zipic
```

### What the Skill Does

<Card title="Environment detection" icon="approve-check-circle">
    Verifies macOS and a Zipic installation before running, with friendly install hints (Homebrew, website) when missing.
  </Card>
  <Card title="Safe path handling" icon="setting">
    URL-encodes spaces and non-ASCII characters in file paths automatically. Batch loops handle whole folders without escaping headaches.
  </Card>
  <Card title="Sensible defaults" icon="rocket">
    Recommends **Q2–Q3** (`--level 2–3`) for everyday use, and picks a target format based on the use case — WebP/AVIF for the web, HEIC for the Apple ecosystem, JPEG for maximum compatibility.
  </Card>
  <Card title="Pro feature awareness" icon="star">
    Knows which features (Notch Drop, clipboard auto-compress, folder watching) require Pro, and reminds you of the free-tier 25-compressions-per-day limit before hitting it.
  </Card>

### Try It in Conversation

Once installed, ask your agent things like:

- *"Compress all the images in `~/Downloads/screenshots/`."*
- *"Convert this PNG to WebP for the blog."*
- *"Resize these product photos to 1920px wide and save them as AVIF."*

The agent figures out the right `level`, `format`, `width`, and target paths, and runs the appropriate Zipic call for you.

## Use Cases

- **Build pipelines** — compress static assets in CI before deploying to a CDN.
- **Blog automation** — feed screenshots into a script that emits web-ready WebP/AVIF on save.
- **Bulk export** — drop a folder onto a script and walk away.
- **Editor / IDE integration** — plug Zipic into VS Code tasks or your AI coding assistant of choice.

:::tip
For agents and scripts that need to read results, see [**Command Line Tool**](/guides/zipic-cli/). For URL Scheme parameters, terminal demos, Shortcuts download, and AppIntents documentation, see [**Integrating Zipic Capabilities**](/guides/optimizing-workflow/).
:::