Command Reference

Every command, flag, and option available in the Derivv CLI.

Global flags

These flags can be used with any command:

  • Name
    --quiet, -q
    Description

    Suppress all output except errors.

  • Name
    --json
    Description

    Output results as JSON (one object per line). Useful for scripting and piping into other tools.

resize

Resize a single image with precise control over dimensions, format, compression, and fit.

derivv resize <input> -o <output> -w <width> -H <height> [options]
  • Name
    input
    Type
    required
    Description

    Path to the input image.

  • Name
    -o, --output
    Type
    required
    Description

    Output path. Can be a file path or a directory.

  • Name
    -w, --width
    Type
    required
    Description

    Target width in pixels.

  • Name
    -H, --height
    Type
    required
    Description

    Target height in pixels.

  • Name
    -f, --format
    Type
    optional
    Description

    Output format: jpg, png, webp, avif. Defaults to the input format.

  • Name
    -c, --compression
    Type
    optional
    Description

    Compression level 0–100 (0 = best quality, 100 = smallest file). Default: 0.

  • Name
    --fit
    Type
    optional
    Description

    Fit strategy: cover, contain, or none. Default: cover.

  • Name
    --filter
    Type
    optional
    Description

    Sampling filter: nearest, triangle, catmull-rom, gaussian, lanczos3. Default: catmull-rom.

  • Name
    --avif-speed
    Type
    optional
    Description

    AVIF encoding speed 1–10 (lower = smaller file, slower encode). Default: 8.

Examples

Basic resize:

derivv resize photo.jpg -o thumbnail.jpg -w 300 -H 200

Convert to WebP with compression:

derivv resize hero.png -o hero.webp -w 1200 -H 630 -f webp -c 20

Contain fit (letterbox) with a specific filter:

derivv resize banner.jpg -o banner-out.jpg -w 1920 -H 1080 --fit contain --filter lanczos3

batch

Process all images in a directory (or matching a glob pattern) using a saved preset.

derivv batch <input> -o <output> -C <config-name>
  • Name
    input
    Type
    required
    Description

    Input directory or glob pattern (e.g. ./photos or "./photos/*.jpg").

  • Name
    -o, --output
    Type
    required
    Description

    Output directory.

  • Name
    -C, --config
    Type
    required
    Description

    Name of the saved preset to use. Run derivv config list to see available presets.

Example

batch

derivv batch ./product-photos -o ./optimized -C "web-thumbnails"

watch

Watch a directory for new images and automatically process them using a saved preset. The watcher runs continuously until you stop it with Ctrl+C.

derivv watch <input> -o <output> -C <config-name>
  • Name
    input
    Type
    required
    Description

    Directory to watch for new images.

  • Name
    -o, --output
    Type
    required
    Description

    Output directory for processed images.

  • Name
    -C, --config
    Type
    required
    Description

    Name of the saved preset to use.

Examples

Watch a folder and process new images as they appear:

watch

derivv watch ~/Desktop/inbox -o ~/Desktop/processed -C "social-media"

With JSON output for scripting:

watch json

derivv --json watch ~/Desktop/inbox -o ~/Desktop/processed -C "social-media"

load

Send images to the Derivv Pro app. The app opens (or focuses) and the images appear as originals, ready to review, tweak, or process from the UI. Useful when you want a human-in-the-loop workflow, when you want to use features that only run inside the app (S3/WordPress connection uploads), or when you want to preview a preset against real files before committing.

derivv load <path> [options]
  • Name
    path
    Type
    required
    Description

    File or directory to load. Directories are searched for supported image formats; pass --recursive to descend into subdirectories.

  • Name
    -C, --config
    Type
    optional
    Description

    Preselect a saved preset by name. The app hydrates the preset before showing the images. Run derivv config list to see available presets.

  • Name
    --replace
    Type
    optional
    Description

    Clear the current originals in the app before loading. Default behavior is to append to whatever is already there.

  • Name
    -r, --recursive
    Type
    optional
    Description

    Recurse into subdirectories.

  • Name
    --no-focus
    Type
    optional
    Description

    Don't bring the app window to the foreground.

  • Name
    --override-cap
    Type
    optional
    Description

    Raise the default 100-image safety cap. derivv load refuses to hand off more than 100 images at once unless this flag is set, since the app can bog down with very large libraries. Use sparingly.

Examples

Load a single image into the app:

derivv load ./hero.jpg

Load every image in a folder and preselect a preset:

derivv load ./photoshoot -C "web-thumbnails"

Replace whatever is currently loaded with a fresh batch:

derivv load ./new-batch --replace

Walk a directory tree, raising the safety cap:

derivv load ./archive --recursive --override-cap 500

Exit codes

  • Name
    0
    Description
    Success — handoff sent to the app.
  • Name
    1
    Description
    Generic error (missing path, unreadable directory, etc.).
  • Name
    3
    Description
    Not signed in.
  • Name
    4
    Description
    Preset specified with --config not found.
  • Name
    8
    Description
    Too many images — over the cap. Re-run with --override-cap <n> to confirm.

The --auto-process, --upload, and --wait flags are reserved for a later release. They are parsed today but not yet honored.

info

Display metadata about an image: dimensions, file size, format, and EXIF data.

derivv info <input>
  • Name
    input
    Type
    required
    Description

    Path to the image file.

Example

derivv info photo.jpg

formats

List all supported output formats.

derivv formats

status

Show the CLI version, account email, plan, and session status.

derivv status

This command does not require an active subscription. Use it to check whether the CLI can connect to your local session.

Example output

Derivv CLI v1.2.0
Account: you@example.com
Plan:    Pro
Session: active

config

Manage saved presets from the command line. Presets are shared with the desktop app.

config list

List all saved presets.

derivv config list

config show

Show a preset's full details as JSON.

derivv config show <name>

config create

Create a new preset.

derivv config create --name <name> --dimensions <WxH,...> [options]
  • Name
    --name
    Type
    required
    Description

    Preset name.

  • Name
    --dimensions
    Type
    required
    Description

    Comma-separated WxH pairs (e.g. 800x600,1200x630).

  • Name
    --format
    Type
    optional
    Description

    Output format: jpg, png, webp, avif, inherit. Default: inherit.

  • Name
    --compression
    Type
    optional
    Description

    Compression level 0–100. Default: 0.

  • Name
    --fit
    Type
    optional
    Description

    Fit strategy: cover, contain. Default: cover.

  • Name
    --filter
    Type
    optional
    Description

    Sampling filter. Default: CatmullRom.

  • Name
    --avif-speed
    Type
    optional
    Description

    AVIF encoding speed 1–10. Default: 8.

config delete

Delete a preset by name.

derivv config delete <name>

config export

Export a preset as JSON to stdout.

derivv config export <name> > preset.json

config import

Import a preset from JSON on stdin.

config import

cat preset.json | derivv config import

Was this page helpful?