@imagerry/cli 0.1.8-beta → 0.2.0-beta

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +124 -126
  2. package/package.json +9 -9
package/README.md CHANGED
@@ -1,11 +1,6 @@
1
- # Imagerry CLI (Beta)
1
+ # Imagerry CLI (v0.2.0-beta)
2
2
 
3
- The official command-line interface for [Imagerry](https://imagerry.com), built for automating image processing and styling directly from your terminal.
4
-
5
- > [!NOTE]
6
- > **Beta Release**
7
- >
8
- > Imagerry CLI is currently in beta. At this time, it only supports the **image customizer** mode with basic styling capabilities.
3
+ The official high-performance command-line interface for [Imagerry](https://imagerry.com), built for automating image processing, styling, format conversion, and mockups directly from your terminal.
9
4
 
10
5
  > [!IMPORTANT]
11
6
  > **Privacy-first processing**
@@ -16,14 +11,17 @@ The official command-line interface for [Imagerry](https://imagerry.com), built
16
11
 
17
12
  ## Features
18
13
 
19
- * 🖥️ Process images directly from the terminal
20
- * 🌐 **New:** Host a self-hosted API server with `serve`
21
- * 🧠 **New:** Model Context Protocol (MCP) server support for AI agents (Claude Desktop, Cursor, Zed)
22
- * 🔒 Keep image processing completely local
23
- * 🎨 Apply built-in styling presets
24
- * ⚙️ Create and reuse custom JSON presets
25
- * 🤖 Use in scripts, Docker, and CI/CD workflows
26
- * 📦 Automate workflows with GitHub Actions
14
+ * 🖥️ **Terminal Processing**: Style single images or batch process entire directories
15
+ * 🖼️ **Multi-Format Output**: Native WebP, JPEG, and PNG encoding with configurable quality
16
+ * 🎨 **Built-in Presets**: Stunning modern aesthetics (`mesh`, `gradient`, `cyberpunk`, `sunset`, `studio`, `aurora`)
17
+ * ⚡ **Direct CLI Overrides**: Fine-tune `--padding`, `--radius`, `--shadow`, `--bg-color`, and `--ratio` directly from the command line without writing JSON
18
+ * 📁 **Batch Processing**: Parallel multi-image folder and wildcard conversion (`--batch`) with live progress
19
+ * ⚙️ **Project Config**: Define team-wide default styles in `imagerry.config.json` with `imagerry init`
20
+ * 🌐 **Self-Hosted API Server**: Run a local or VPS microservice with `imagerry serve`
21
+ * 🧠 **Model Context Protocol (MCP)**: Native tools for Claude Desktop, Cursor, and Zed AI assistants
22
+ * 🤖 **CI/CD & Automation**: Run in GitHub Actions, Docker, and shell pipelines
23
+
24
+ ---
27
25
 
28
26
  ## Installation
29
27
 
@@ -36,160 +34,186 @@ npm install -g @imagerry/cli
36
34
  Verify the installation:
37
35
 
38
36
  ```bash
37
+ imagerry -v
39
38
  imagerry -h
40
39
  ```
41
40
 
42
- ## Free Tier & Licensing
43
-
44
- Imagerry CLI includes a **Free Tier** that allows you to process up to **15 free images per day** without requiring a license key.
41
+ ---
45
42
 
46
- For unlimited daily processing, automated loops/batch scripts, or hosting the self-hosted `serve` API and `mcp` server, an **[Imagerry Pro](https://imagerry.com/pro)** license is required.
43
+ ## Free Tier & Licensing
47
44
 
48
- ### Using Pro License
45
+ Imagerry CLI includes a **Free Tier** allowing you to process up to **15 free images per day** without a license key.
49
46
 
50
- You can provide your license key in either of the following ways:
47
+ For unlimited daily processing, high-volume automated batch scripts, or hosting the self-hosted `serve` API and `mcp` server, an **[Imagerry Pro](https://imagerry.com/pro)** license is required.
51
48
 
52
- #### Command-line option
49
+ ### Providing Pro License
53
50
 
51
+ #### Option A: Command-line flag
54
52
  ```bash
55
- imagerry --input=input.png --output=output.png --license-key=YOUR_KEY
53
+ imagerry -i input.png -o output.png --license-key=YOUR_KEY
56
54
  ```
57
55
 
58
- #### Environment variable
59
-
60
- For automation, Docker, and CI/CD environments:
61
-
56
+ #### Option B: Environment variable (Recommended for CI/CD & Docker)
62
57
  ```bash
63
58
  export IMAGERRY_LICENSE_KEY="YOUR_KEY"
64
59
  ```
65
60
 
66
61
  > [!TIP]
67
- > CLI usage does **not count against your device limit**. You can use your Pro license freely across your local terminal, Docker containers, and CI/CD pipelines.
62
+ > CLI usage does **not count against your desktop device limit**. You can use your Pro license freely across terminals, servers, Docker containers, and CI/CD pipelines.
68
63
 
69
- ## Usage
64
+ ---
70
65
 
71
- ### Basic usage
66
+ ## Usage Guide
72
67
 
73
- Process an image using the default settings:
68
+ ### 1. Basic Usage & Formats
74
69
 
70
+ Process an image with default styles:
75
71
  ```bash
76
- imagerry --input=input.png --output=output.png
72
+ imagerry -i input.png -o output.png
77
73
  ```
78
74
 
79
- You can also use the shorter argument aliases:
80
-
75
+ Convert and compress to **WebP** or **JPEG** with custom quality:
81
76
  ```bash
82
- imagerry -i input.png -o output.png
77
+ # Auto-detected format from file extension
78
+ imagerry -i photo.png -o photo.webp -q 85
79
+
80
+ # Explicit format flag
81
+ imagerry -i photo.png -o result.jpg --format jpeg --quality 80
83
82
  ```
84
83
 
85
- ## Built-in Presets
84
+ ### 2. Built-in Presets
86
85
 
87
- To view a full list of available built-in styles and their descriptions, run:
86
+ Imagerry includes curated visual presets (e.g. `mesh`, `gradient`, `cyberpunk`, `default`).
88
87
 
88
+ To list all available presets from your terminal:
89
89
  ```bash
90
90
  imagerry --list-presets
91
91
  ```
92
92
 
93
- Once you've found a style you like, you can apply it using the `--preset` flag:
93
+ All presets and configuration properties are documented in the **[JSON Schema](https://imagerry.com/schema/config.json)**.
94
94
 
95
+ Apply a preset:
95
96
  ```bash
96
- imagerry --input=input.png --output=output.png --preset=mesh
97
+ imagerry -i app.png -o app-styled.webp --preset mesh
97
98
  ```
98
99
 
99
- ## Custom JSON Presets
100
-
101
- For more control over the output, Imagerry supports custom JSON presets.
100
+ ### 3. Direct CLI Styling Flags (No JSON Required)
102
101
 
103
- ### 1. Export a preset template
104
-
105
- Generate a starting configuration:
102
+ Easily adjust individual visual parameters without touching preset files:
106
103
 
107
104
  ```bash
108
- imagerry --export-preset-template=my-style.json
105
+ imagerry -i screenshot.png -o screenshot.webp \
106
+ --preset mesh \
107
+ --padding 40 \
108
+ --radius 20 \
109
+ --shadow 60 \
110
+ --bg-color "#0a0a0a" \
111
+ --ratio 16:9 \
112
+ --watermark "© 2026 Acme Corp"
109
113
  ```
110
114
 
111
- Edit `my-style.json` with your preferred settings.
115
+ Supported direct flags:
116
+ - `--padding <number>`: Canvas padding percent (e.g. `24`, `40`, `50`)
117
+ - `--radius <number>`: Inner image corner radius (e.g. `12`, `16`, `24`)
118
+ - `--shadow <number>`: Drop shadow strength (e.g. `30`, `50`, `70`)
119
+ - `--bg-color <hex>`: Solid background color (e.g. `"#000000"`, `"#18181b"`)
120
+ - `--ratio <ratio>`: Aspect ratio (`"16:9"`, `"1:1"`, `"4:3"`, `"auto"`)
121
+ - `--watermark <text>`: Watermark text overlay
122
+ - `--title <text>` & `--subtitle <text>`: Header overlay text
123
+ - `--blur <number>`, `--contrast <number>`, `--brightness <number>`, `--saturation <number>`
124
+
125
+ ### 4. Batch & Directory Processing
112
126
 
113
- ### 2. Apply a preset file
127
+ Process an entire folder of screenshots or images in one command:
114
128
 
115
129
  ```bash
116
- imagerry \
117
- -i input.png \
118
- -o output.png \
119
- -m image-customizer \
120
- --preset my-style.json
130
+ # Process all images in a directory to ./dist
131
+ imagerry -i ./screenshots -o ./dist --preset mesh --format webp
132
+
133
+ # Batch process with wildcard pattern
134
+ imagerry --batch "assets/*.png" -o ./dist --preset gradient --quality 85
135
+
136
+ # Adjust parallel worker concurrency
137
+ imagerry -i ./raw-photos -o ./compressed --preset studio --concurrency 6
121
138
  ```
122
139
 
123
- ### 3. Pass JSON directly
140
+ ### 5. Project Configuration (`imagerry.config.json`)
124
141
 
125
- For simple configurations, you can provide the preset directly from the terminal:
142
+ Standardize visual branding across team members and repositories. Initialize a configuration file in your project root:
126
143
 
127
144
  ```bash
128
- imagerry \
129
- -i input.png \
130
- -o output.png \
131
- -m image-customizer \
132
- --preset '{"padding": 64, "bgColor": "#000000"}'
145
+ imagerry init --preset mesh
146
+ ```
147
+
148
+ This creates an `imagerry.config.json`:
149
+ ```json
150
+ {
151
+ "$schema": "https://imagerry.com/schema/config.json",
152
+ "preset": "mesh",
153
+ "format": "webp",
154
+ "quality": 90,
155
+ "padding": 36,
156
+ "borderRadius": 16,
157
+ "shadowSize": 50,
158
+ "canvasRatio": "auto"
159
+ }
133
160
  ```
134
161
 
135
- This can be useful for scripts where creating a separate preset file would add unnecessary complexity.
162
+ Whenever you run `imagerry -i input.png -o output.webp`, the CLI automatically detects and applies your project configuration!
136
163
 
137
- ## Command Reference
164
+ ### 6. Custom JSON Presets
138
165
 
139
- To view all available commands, options, and examples:
166
+ For full control over every setting, export and customize template JSON files:
140
167
 
141
168
  ```bash
142
- imagerry -h
169
+ # Export template
170
+ imagerry --export-preset-template=my-style.json
171
+
172
+ # Apply template
173
+ imagerry -i input.png -o output.png --preset my-style.json
143
174
  ```
144
175
 
145
- ## API Server
176
+ ---
146
177
 
147
- Imagerry CLI includes a built-in Express server that allows you to self-host the engine as a REST API. You can host this on Railway, Render, or any VPS.
178
+ ## API Server
148
179
 
149
- To start the API server:
180
+ Self-host the Imagerry engine as a high-performance REST API:
150
181
 
151
182
  ```bash
152
183
  imagerry serve --port 5273
153
184
  ```
154
- *(Note: A valid `IMAGERRY_LICENSE_KEY` environment variable or `--license-key` flag is required to start the server).*
185
+ *(Requires `IMAGERRY_LICENSE_KEY`)*
155
186
 
156
- ### API Example
157
-
158
- Send a `multipart/form-data` POST request to process an image instantly over HTTP:
187
+ ### Processing via HTTP:
159
188
 
160
189
  ```bash
161
190
  curl -f -X POST http://localhost:5273/api/v1/process \
162
- -F "image=@/path/to/your/input.png" \
163
- -F 'preset={"padding": 64, "bgColor": "#18181b"}' \
164
- --output result.png
191
+ -F "image=@/path/to/screenshot.png" \
192
+ -F "preset=mesh" \
193
+ -F "format=webp" \
194
+ -F "quality=85" \
195
+ -F "padding=40" \
196
+ --output result.webp
165
197
  ```
166
198
 
167
- > [!WARNING]
168
- > We strongly recommend including the `-f` (or `--fail-with-body`) flag when using `curl` with `--output`. If the API returns an error, this flag prevents `curl` from saving the JSON error response directly into your output image file, which would result in a corrupted image.
169
-
170
- ### Built-in API Reference
171
-
172
- Once the server is running, visit **`http://localhost:5273/docs`** in your browser to view the API reference.
199
+ Helpful metadata endpoints:
200
+ - `GET /presets` — List built-in presets
201
+ - `GET /template` — Full JSON template structure
202
+ - `GET /health` — Server health status and version
173
203
 
174
- The server also exposes a few helpful informational routes:
175
-
176
- - `GET /presets` — Returns a JSON array of all built-in named presets.
177
- - `GET /template` — Returns a JSON object of all available settings keys and their defaults.
178
- - `GET /health` — Returns server health status and engine version.
204
+ ---
179
205
 
180
206
  ## Model Context Protocol (MCP) Server
181
207
 
182
- Imagerry CLI includes an official **Model Context Protocol (MCP)** server that exposes local image styling and formatting tools directly to AI assistants like Claude Desktop, Cursor, and Zed.
208
+ Imagerry CLI includes a built-in MCP server enabling AI coding assistants (Claude Desktop, Cursor, Zed) to style, format, and batch-process local images autonomously.
183
209
 
184
- ### Starting the MCP Server
210
+ ### Starting MCP:
185
211
 
186
212
  ```bash
187
213
  imagerry mcp
188
214
  ```
189
215
 
190
- ### Claude Desktop Configuration
191
-
192
- Add the following to your `claude_desktop_config.json`:
216
+ ### Configuration (`claude_desktop_config.json`):
193
217
 
194
218
  ```json
195
219
  {
@@ -205,45 +229,19 @@ Add the following to your `claude_desktop_config.json`:
205
229
  }
206
230
  ```
207
231
 
208
- ### Registered Tools
209
- * **`customize_image`**: Applies presets, gradients, and custom styles to local images (`inputPath`, `outputPath`, `preset`, `mode`).
210
-
211
- ## Automation
232
+ ### Available AI Tools:
233
+ 1. **`customize_image`**: Format and style single images with preset, padding, radius, format (`webp`, `jpeg`, `png`), and quality.
234
+ 2. **`batch_customize_images`**: Process entire directories in bulk for agents generating assets.
235
+ 3. **`list_presets`**: Query descriptions of all available styling presets.
212
236
 
213
- Imagerry CLI is designed to work well in automated environments.
237
+ ---
214
238
 
215
- For example, you can provide your license through an environment variable:
239
+ ## Troubleshooting & Privacy
216
240
 
217
- ```bash
218
- export IMAGERRY_LICENSE_KEY="YOUR_KEY"
219
-
220
- imagerry \
221
- -i input.png \
222
- -o output.png \
223
- --preset=gradient
224
- ```
225
-
226
- When using a CI provider, store `IMAGERRY_LICENSE_KEY` as a secret rather than committing the license key to your repository.
227
-
228
- > [!WARNING]
229
- > Never commit your Imagerry license key to Git or include it directly in a public workflow configuration.
230
-
231
- ## Troubleshooting
232
-
233
- ### License issues
234
-
235
- If your license cannot be verified, double-check that your key is valid and it belongs to Imagerry. If you lost your key or need help, please contact us at **support@imagerry.com**.
236
-
237
- ## Privacy
238
-
239
- Your source images stay on your machine or your own hosted server.
240
-
241
- Imagerry CLI processes and renders all images locally. Images do not need to be uploaded to Imagerry or any external image-processing server.
242
-
243
- The CLI only communicates with the licensing service when verifying your Imagerry Pro license.
241
+ - **Image Security**: All image manipulation is performed in-memory on your local CPU/GPU using native Skia bindings (`@napi-rs/canvas`). Your images are **never transmitted over the network**.
242
+ - **Licensing**: For support or key inquiries, contact **support@imagerry.com**.
244
243
 
245
244
  ## Links
246
-
247
- * [Imagerry](https://imagerry.com)
245
+ * [Imagerry Official Website](https://imagerry.com)
248
246
  * [Imagerry Pro](https://imagerry.com/pro)
249
- * [Legal & Terms](https://imagerry.com/legal)
247
+ * [Legal & Privacy Terms](https://imagerry.com/legal)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@imagerry/cli",
3
- "version": "0.1.8-beta",
3
+ "version": "0.2.0-beta",
4
4
  "description": "Command-line interface for the Imagerry engine",
5
5
  "homepage": "https://cli.imagerry.com",
6
6
  "repository": {
@@ -23,13 +23,13 @@
23
23
  "imagerry": "bin/imagerry.js"
24
24
  },
25
25
  "optionalDependencies": {
26
- "@imagerry/cli-android-arm64": "0.1.8-beta",
27
- "@imagerry/cli-darwin-arm64": "0.1.8-beta",
28
- "@imagerry/cli-darwin-x64": "0.1.8-beta",
29
- "@imagerry/cli-linux-arm64": "0.1.8-beta",
30
- "@imagerry/cli-linux-x64": "0.1.8-beta",
31
- "@imagerry/cli-win32-arm64": "0.1.8-beta",
32
- "@imagerry/cli-win32-x64": "0.1.8-beta"
26
+ "@imagerry/cli-android-arm64": "0.2.0-beta",
27
+ "@imagerry/cli-darwin-arm64": "0.2.0-beta",
28
+ "@imagerry/cli-darwin-x64": "0.2.0-beta",
29
+ "@imagerry/cli-linux-arm64": "0.2.0-beta",
30
+ "@imagerry/cli-linux-x64": "0.2.0-beta",
31
+ "@imagerry/cli-win32-arm64": "0.2.0-beta",
32
+ "@imagerry/cli-win32-x64": "0.2.0-beta"
33
33
  },
34
34
  "keywords": [
35
35
  "image",
@@ -45,6 +45,6 @@
45
45
  "author": "Imagerry <support@imagerry.com>",
46
46
  "license": "SEE LICENSE IN LICENSE.md",
47
47
  "imagerry": {
48
- "minimumVersion": "0.1.7-beta"
48
+ "minimumVersion": "0.2.0-beta"
49
49
  }
50
50
  }