npm package: @inliner/cli
Description: CLI for Inliner.ai — generate and edit AI images from the terminal
Author: Inliner
Latest version: 0.1.10

# @inliner/cli

CLI for [Inliner.ai](https://inliner.ai) — generate and edit AI images from the terminal.

## Install

```bash
npm install -g @inliner/cli
```

Or run directly with npx:

```bash
npx @inliner/cli generate "hero image" --project mysite --size 1200x600
```

## Setup

Get an API key from **Account > API Keys** in the [Inliner dashboard](https://app.inliner.ai/account).

```bash
export INLINER_API_KEY=your-key
```

Or pass it per-command:

```bash
inliner-ai generate "hero" --api-key=YOUR_KEY --project mysite
```

## Commands

### Smart Mode (Default)

When no command is specified, the CLI parses your input as a smart description string:

```bash
# Pattern 1: Filename with dimensions and format → saves to local file
inliner-ai "hero-image_1200x600.png" -p mysite
# → Generates 1200x600 PNG, saves to hero-image_1200x600.png

# Pattern 2: Description with dimensions → outputs URL (or pipe to file)
inliner-ai "fat happy cats 900x900" -p mysite
# → Generates 900x900 PNG, prints URL to stdout

# Pattern 3: Filename with format only → saves to local file
inliner-ai "sunset-landscape.jpg" -p mysite
# → Generates JPG (API decides dimensions, usually 1024x1024), saves to sunset-landscape.jpg

# Override output filename with -o flag
inliner-ai "hero-image_1200x600.png" -p mysite -o custom-name.png
# → Generates image, saves to custom-name.png instead

# Auto-detects project if omitted (uses default project or first project)
inliner-ai "test-image_800x600.png"
# → Uses your default project automatically, saves to test-image_800x600.png
```

Smart URL behavior (default):
- The CLI calls `POST /url/recommend` to create a concise, readable slug.
- It then calls `POST /content/generate` with your full prompt + that slug.
- Result: long descriptive prompts still generate high-quality images, while URLs remain short and SEO-friendly.
- Use `--no-smart-url` to force legacy prompt-to-slug behavior.

**Supported patterns:**
- `description_WxH.jpg` or `description_WxH.png` → extracts dimensions and format, **saves to file**
- `description WxH` → extracts dimensions, defaults to PNG, **outputs URL**
- `description.jpg` → extracts format, API decides dimensions (usually 1024x1024), **saves to file**
- `description` → no dimensions or format, API decides (usually 1024x1024 PNG), **outputs URL**
- Auto-detects project if `-p` is omitted
- Use `-o filename.png` to override the auto-detected output filename

### generate

Generate an AI image from a text prompt.

```bash
# Print image URL to terminal
inliner-ai generate "modern office hero" -p acme --size 1200x600

# Pipe binary to file
inliner-ai gen "sunset landscape" -p mysite > hero.png

# Save directly
inliner-ai g "product shot" -p store -o product.png

# Auto-detect project (uses default project or first project)
inliner-ai generate "hero image" --size 1200x600

# No dimensions specified - API decides (usually 1024x1024)
inliner-ai generate "hero image" -p mysite
```

Options:
| Flag | Description |
|------|-------------|
| `-p, --project` | Project namespace (auto-detects if omitted) |
| `--size WxH` | Dimensions (default: API decides, usually 1024x1024) |
| `--width`, `--height` | Alternative to --size |
| `-f, --format` | `png` or `jpg` (default: png) |
| `--no-smart-url` | Disable smart URL recommendation and use legacy slug path |
| `-o, --output` | Save to file |

### edit

Edit an image with AI instructions. Accepts a local file, Inliner URL, or stdin.

```bash
# Edit a local file
inliner-ai edit photo.png "remove the background" -p myproject -o clean.png

# Pipe from stdin
cat photo.jpg | inliner-ai edit - "make it warmer" -p proj > warm.jpg

# Edit an existing Inliner image by URL
inliner-ai edit https://img.inliner.ai/proj/hero_800x600.png "add sunset sky"
```

For local files, the CLI uploads the image to your project first, then applies the AI edit.

### inline

Process HTML files to resolve Inliner image references. Reads from stdin or a file.

```bash
# Replace placeholders with Inliner image tags
inliner-ai inline template.html -p acme > output.html

# Embed images as base64 data URIs (for emails, offline HTML)
cat email.html | inliner-ai inline --embed > email-inlined.html
```

Supported HTML patterns (with `--project`):

```html
<!-- inliner: hero banner sunset landscape 1200x600 png -->
<!-- Becomes: <img src="https://img.inliner.ai/acme/hero-banner-sunset-landscape_1200x600.png" ...> -->

<img data-inliner="product shot on white background" width="800" height="600">
<!-- Gets an Inliner src URL added -->
```

With `--embed`, downloads all `img.inliner.ai` images and replaces URLs with `data:` URIs.

### projects

List your Inliner projects.

```bash
inliner-ai projects
inliner-ai proj --json
```

### create-project

Create a new project (reserves the namespace for your account).

```bash
# Create a project with required name
inliner-ai create-project my-project --name "My Project"

# Create with description and set as default
inliner-ai create-project marketing --name "Marketing Team" --description "Marketing assets" --default

# JSON output
inliner-ai create-project dev --name "Development" --json
```

Options:
| Flag | Description |
|------|-------------|
| `--name <name>` | Display name (required) |
| `--description <desc>` | Description (optional) |
| `--default` | Set as default project (optional) |
| `--json` | Output raw JSON |

### images

List generated images.

```bash
inliner-ai images
inliner-ai img -p myproject --limit 20
inliner-ai img --search "hero" --json
```

### usage

Show credit usage for your account.

```bash
inliner-ai usage
inliner-ai u --json
```

## Smart Output

The CLI adapts its output based on context:

| Context | Behavior |
|---------|----------|
| Interactive terminal (TTY) | Prints the image URL |
| Piped (`\| ...` or `> file`) | Outputs raw image bytes |
| `--output file.png` | Saves to file, prints URL to stderr |

This means standard Unix patterns work naturally:

```bash
# Save to file via redirect
inliner-ai generate "hero" -p site > hero.png

# Pipe through ImageMagick
inliner-ai generate "logo" -p brand --size 400x400 | convert - -resize 200x200 logo-small.png

# Chain edit operations
inliner-ai edit photo.png "remove background" -p proj | inliner-ai edit - "add gradient bg" -p proj > final.png
```

## Project Selection

The CLI automatically selects a project in this order:

1. **`--project` flag** (explicit)
2. **`INLINER_DEFAULT_PROJECT` environment variable**
3. **Default project** (project marked as default in your account)
4. **First project** (fallback if no default is set)

When auto-detecting, the CLI prints which project was used to stderr:
```
Using default project: mysite
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `INLINER_API_KEY` | API key (required) |
| `INLINER_DEFAULT_PROJECT` | Default project namespace (if `--project` omitted) |
| `INLINER_API_URL` | API base URL (default: `https://api.inliner.ai`) |
| `INLINER_IMG_URL` | Image CDN URL (default: `https://img.inliner.ai`) |

## Links

- [Inliner.ai](https://inliner.ai)
- [Tutorials](https://inliner.ai/tutorial)
- [@inliner/mcp-server](https://www.npmjs.com/package/@inliner/mcp-server) — MCP server for AI coding agents