@nghiavuive/random-image 1.1.0 → 1.2.1

package/README.md

@@ -1,6 +1,6 @@
 # random-image
 
-A generic utility library to fetch random images from various providers like Unsplash and Pexels, with built-in download capabilities.
+A generic utility library to fetch random images from various providers like Unsplash and Pexels, with built-in download capabilities and CLI support.
 
 ## Installation
 
@@ -8,7 +8,99 @@ A generic utility library to fetch random images from various providers like Uns
 npm install @nghiavuive/random-image
 ```
 
-## Usage
+## CLI Usage
+
+You can use the CLI without installation via `npx`:
+
+```bash
+npx @nghiavuive/random-image fetch --query "nature" --download
+```
+
+Or install globally:
+
+```bash
+npm install -g @nghiavuive/random-image
+random-image fetch --query "mountains" --download
+```
+
+### CLI Setup
+
+Set environment variables for the providers you want to use:
+
+```bash
+export UNSPLASH_KEY="your_unsplash_access_key"
+export PEXELS_KEY="your_pexels_api_key"
+export PIXABAY_KEY="your_pixabay_api_key"
+```
+
+Or create a `.env` file in your project:
+
+```env
+UNSPLASH_KEY=your_unsplash_access_key
+PEXELS_KEY=your_pexels_api_key
+PIXABAY_KEY=your_pixabay_api_key
+```
+
+### CLI Commands
+
+#### Fetch Command
+
+```bash
+# Basic usage - uses random provider from available API keys
+random-image fetch
+
+# Fetch with search query
+random-image fetch --query "nature"
+
+# Fetch and download
+random-image fetch --query "mountains" --download
+
+# Specify provider
+random-image fetch --provider unsplash --query "ocean"
+
+# Custom dimensions
+random-image fetch --width 1920 --height 1080 --query "sunset"
+
+# Download to custom directory
+random-image fetch --query "cats" --download ./my-images
+
+# Download with custom filename
+random-image fetch --query "dogs" --download --filename "my-dog.jpg"
+
+# Download with overwrite
+random-image fetch --download --overwrite
+
+# Generate random UUID filename
+random-image fetch --download --no-keep-original-name
+
+# Full example with all options
+random-image fetch \
+  --provider pexels \
+  --query "abstract art" \
+  --width 2560 \
+  --height 1440 \
+  --orientation landscape \
+  --download ./wallpapers \
+  --filename "wallpaper.jpg" \
+  --overwrite
+```
+
+#### CLI Flags
+
+- `-q, --query <search>`: Search query for the image
+- `-w, --width <number>`: Width of the image
+- `-h, --height <number>`: Height of the image
+- `--quality <number>`: Quality of the image (0-100)
+- `--orientation <type>`: Image orientation (`landscape` or `portrait`)
+- `-p, --provider <name>`: Provider to use (`unsplash`, `pexels`, `pixabay`, or `random`)
+- `-d, --download [path]`: Download the image (default: `./downloads`)
+- `--filename <name>`: Custom filename for downloaded image
+- `--overwrite`: Overwrite existing files
+- `--no-keep-original-name`: Generate random UUID filename instead of keeping original
+
+**Random Provider Mode**: If you don't specify `--provider` or use `--provider random`, the CLI will randomly select from providers that have API keys configured. This is useful for distributing requests across multiple services.
+
+## Programmatic Usage
 
 You need to obtain API keys from the respective providers:
 - [Unsplash Developers](https://unsplash.com/developers)
@@ -149,8 +241,16 @@ Result object containing image information:
 
 ## Features
 
+### CLI Features
+- ✅ Command-line interface for quick image fetching
+- ✅ Random provider selection when multiple API keys are available
+- ✅ Environment variable support for API keys
+- ✅ Direct download from command line
+- ✅ All library features available via CLI flags
+
+### Library Features
+
 ### Download Functionality
-- ✅ Automatic directory creation
 - ✅ Flexible filename options:
   - Custom filename
   - Keep original filename from URL (default)

package/dist/cli.js

@@ -0,0 +1,465 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/cli.ts
+var import_commander = require("commander");
+
+// src/providers/unsplash.ts
+var import_axios = __toESM(require("axios"));
+var UnsplashProvider = class {
+  constructor(accessKey) {
+    this.accessKey = accessKey;
+  }
+  async fetchRandomImage(options) {
+    const response = await import_axios.default.get("https://api.unsplash.com/photos/random", {
+      headers: {
+        Authorization: `Client-ID ${this.accessKey}`
+      },
+      params: {
+        query: options.query,
+        orientation: options.orientation
+      }
+    });
+    const data = response.data;
+    const photo = Array.isArray(data) ? data[0] : data;
+    const baseUrl = photo.urls.raw;
+    const sizeParams = new URLSearchParams();
+    if (options.height || options.width) {
+      sizeParams.append("fit", "crop");
+      sizeParams.append("crop", "entropy");
+    }
+    if (options.width) sizeParams.append("w", options.width.toString());
+    if (options.height) sizeParams.append("h", options.height.toString());
+    if (options.quality) sizeParams.append("q", options.quality.toString());
+    const finalUrl = `${baseUrl}&${sizeParams.toString()}`;
+    return {
+      url: finalUrl,
+      width: options.width || photo.width,
+      height: options.height || photo.height,
+      author: photo.user.name,
+      authorUrl: photo.user.links.html,
+      originalUrl: photo.links.html
+      // Link to photo page
+    };
+  }
+};
+
+// src/providers/pexels.ts
+var import_axios2 = __toESM(require("axios"));
+var PexelsProvider = class {
+  constructor(apiKey) {
+    this.apiKey = apiKey;
+  }
+  async fetchRandomImage(options) {
+    const endpoint = options.query ? "https://api.pexels.com/v1/search" : "https://api.pexels.com/v1/curated";
+    const randomPage = Math.floor(Math.random() * 100) + 1;
+    const params = {
+      per_page: 1,
+      page: randomPage
+    };
+    if (options.query) params.query = options.query;
+    const response = await import_axios2.default.get(endpoint, {
+      headers: {
+        Authorization: this.apiKey
+      },
+      params
+    });
+    const data = response.data;
+    if (!data.photos || data.photos.length === 0) {
+      throw new Error("No images found on Pexels");
+    }
+    const photo = data.photos[0];
+    const baseUrl = photo.src.original;
+    const sizeParams = new URLSearchParams();
+    sizeParams.append("auto", "compress");
+    sizeParams.append("cs", "tinysrgb");
+    if (options.width) sizeParams.append("w", options.width.toString());
+    if (options.height) sizeParams.append("h", options.height.toString());
+    const finalUrl = `${baseUrl}?${sizeParams.toString()}`;
+    return {
+      url: finalUrl,
+      width: options.width || photo.width,
+      height: options.height || photo.height,
+      author: photo.photographer,
+      authorUrl: photo.photographer_url,
+      originalUrl: photo.url
+    };
+  }
+};
+
+// src/providers/pixabay.ts
+var import_axios3 = __toESM(require("axios"));
+var PixabayProvider = class {
+  constructor(apiKey) {
+    this.apiKey = apiKey;
+  }
+  async fetchRandomImage(options) {
+    const params = {
+      key: this.apiKey,
+      q: options.query || "",
+      per_page: 20
+      // Fetch a few to pick randomly
+    };
+    if (options.orientation) {
+      params.orientation = options.orientation === "portrait" ? "vertical" : "horizontal";
+    }
+    const response = await import_axios3.default.get("https://pixabay.com/api/", {
+      params
+    });
+    const hits = response.data.hits;
+    if (!hits || hits.length === 0) {
+      throw new Error("No images found");
+    }
+    const randomHit = hits[Math.floor(Math.random() * hits.length)];
+    return {
+      url: randomHit.largeImageURL || randomHit.webformatURL,
+      width: randomHit.imageWidth || randomHit.webformatWidth,
+      height: randomHit.imageHeight || randomHit.webformatHeight,
+      author: randomHit.user,
+      authorUrl: `https://pixabay.com/users/${randomHit.user}-${randomHit.user_id}/`,
+      originalUrl: randomHit.pageURL
+    };
+  }
+};
+
+// src/image-fetcher.ts
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var import_axios4 = __toESM(require("axios"));
+var import_uuid = require("uuid");
+var RandomImage = class {
+  constructor(provider) {
+    this.provider = provider;
+  }
+  /**
+   * Fetches a random image based on the provided options.
+   * @param options - Configuration options for the image (width, height, query, etc.)
+   * @returns A promise that resolves to an ImageResult object.
+   */
+  async getRandom(options = {}) {
+    return this.provider.fetchRandomImage(options);
+  }
+  /**
+   * Downloads an image to a specified directory.
+   * @param imageUrl - The URL of the image to download (can be a string or ImageResult object)
+   * @param destinationPath - The directory path where the image will be saved
+   * @param options - Download options (filename, overwrite, etc.)
+   * @returns A promise that resolves to the full path of the downloaded file
+   */
+  async download(imageUrl, destinationPath, options = {}) {
+    const url = typeof imageUrl === "string" ? imageUrl : imageUrl.url;
+    if (!fs.existsSync(destinationPath)) {
+      fs.mkdirSync(destinationPath, { recursive: true });
+    }
+    let finalFilename;
+    if (options.filename) {
+      finalFilename = options.filename;
+    } else if (options.keepOriginalName) {
+      const urlPath = new URL(url).pathname;
+      const urlFilename = path.basename(urlPath);
+      if (urlFilename && urlFilename.length > 0 && urlFilename !== "/") {
+        finalFilename = urlFilename;
+      } else {
+        const ext = this.getExtensionFromUrl(url) || ".jpg";
+        finalFilename = `${(0, import_uuid.v7)()}${ext}`;
+      }
+    } else {
+      const ext = this.getExtensionFromUrl(url) || ".jpg";
+      finalFilename = `${(0, import_uuid.v7)()}${ext}`;
+    }
+    if (!path.extname(finalFilename)) {
+      finalFilename += ".jpg";
+    }
+    const fullPath = path.join(destinationPath, finalFilename);
+    if (fs.existsSync(fullPath) && !options.overwrite) {
+      throw new Error(`File already exists: ${fullPath}. Set overwrite: true to replace it.`);
+    }
+    try {
+      const response = await import_axios4.default.get(url, {
+        responseType: "stream",
+        maxRedirects: 5
+        // Automatically handle redirects
+      });
+      const writer = fs.createWriteStream(fullPath);
+      response.data.pipe(writer);
+      return new Promise((resolve3, reject) => {
+        writer.on("finish", () => {
+          resolve3(fullPath);
+        });
+        writer.on("error", (err) => {
+          fs.unlink(fullPath, () => {
+          });
+          reject(err);
+        });
+        response.data.on("error", (err) => {
+          writer.close();
+          fs.unlink(fullPath, () => {
+          });
+          reject(err);
+        });
+      });
+    } catch (error) {
+      if (import_axios4.default.isAxiosError(error)) {
+        throw new Error(`Failed to download image: ${error.message}`);
+      }
+      throw error;
+    }
+  }
+  /**
+   * Helper method to extract file extension from URL
+   * @param url - The URL to extract extension from
+   * @returns The file extension (e.g., '.jpg', '.png') or null
+   */
+  getExtensionFromUrl(url) {
+    try {
+      const urlPath = new URL(url).pathname;
+      const ext = path.extname(urlPath);
+      return ext || null;
+    } catch {
+      return null;
+    }
+  }
+};
+
+// src/cli.ts
+var import_chalk3 = __toESM(require("chalk"));
+
+// src/cli/env-loader.ts
+var path2 = __toESM(require("path"));
+var dotenv = __toESM(require("dotenv"));
+var fs2 = __toESM(require("fs"));
+function loadEnvironment() {
+  const possibleEnvPaths = [
+    path2.resolve(process.cwd(), ".env"),
+    // Current working directory
+    path2.resolve(__dirname, ".env"),
+    // Same directory as the CLI script (dist/)
+    path2.resolve(__dirname, "..", ".env")
+    // Parent directory (root of project)
+  ];
+  for (const envPath of possibleEnvPaths) {
+    if (fs2.existsSync(envPath)) {
+      dotenv.config({ path: envPath });
+      break;
+    }
+  }
+}
+function getApiKeys() {
+  return {
+    unsplash: process.env.UNSPLASH_KEY,
+    pexels: process.env.PEXELS_KEY,
+    pixabay: process.env.PIXABAY_KEY
+  };
+}
+
+// src/cli/display.ts
+var import_chalk = __toESM(require("chalk"));
+var import_boxen = __toESM(require("boxen"));
+function displayError(message) {
+  console.error(import_chalk.default.red(`
+\u274C ${message}`));
+}
+function displayInfo(message) {
+  console.log(import_chalk.default.blue(`
+\u2139\uFE0F  ${message}`));
+}
+function displayImageInfo(image, providerName) {
+  const content = [
+    `${import_chalk.default.bold("\u{1F3A8} Provider:")} ${import_chalk.default.cyan(providerName)}`,
+    `${import_chalk.default.bold("\u{1F4D0} Size:")} ${import_chalk.default.yellow(`${image.width}x${image.height}`)}`,
+    `${import_chalk.default.bold("\u{1F464} Author:")} ${import_chalk.default.magenta(image.author)}`,
+    image.authorUrl ? `${import_chalk.default.bold("\u{1F517} Author URL:")} ${import_chalk.default.gray(image.authorUrl)}` : "",
+    `${import_chalk.default.bold("\u{1F310} Original:")} ${import_chalk.default.gray(image.originalUrl)}`,
+    `${import_chalk.default.bold("\u{1F4F7} Image URL:")} ${import_chalk.default.gray(image.url)}`
+  ].filter(Boolean).join("\n");
+  console.log("\n" + (0, import_boxen.default)(content, {
+    padding: 1,
+    margin: 1,
+    borderStyle: "round",
+    borderColor: "green",
+    title: "\u{1F5BC}\uFE0F  Image Details",
+    titleAlignment: "center"
+  }));
+}
+function displayDownloadSuccess(filePath) {
+  const content = `${import_chalk.default.bold("\u{1F4C1} Saved to:")} ${import_chalk.default.cyan(filePath)}`;
+  console.log("\n" + (0, import_boxen.default)(content, {
+    padding: 1,
+    margin: 1,
+    borderStyle: "round",
+    borderColor: "blue",
+    title: "\u{1F4BE} Download Complete",
+    titleAlignment: "center"
+  }));
+}
+
+// src/cli/provider-manager.ts
+function selectRandomProvider(providers) {
+  const availableProviders = Object.entries(providers).filter(([_, key]) => key).map(([name]) => name);
+  if (availableProviders.length === 0) {
+    return null;
+  }
+  return availableProviders[Math.floor(Math.random() * availableProviders.length)];
+}
+function createProvider(providerName, apiKey) {
+  switch (providerName) {
+    case "unsplash":
+      return new UnsplashProvider(apiKey);
+    case "pexels":
+      return new PexelsProvider(apiKey);
+    case "pixabay":
+      return new PixabayProvider(apiKey);
+    default:
+      return null;
+  }
+}
+function getProviderInstance(providerName, providers) {
+  const name = providerName.toLowerCase();
+  const apiKey = providers[name];
+  if (!apiKey) {
+    displayError(`API key for ${providerName} not found.`);
+    console.log(`Please set ${providerName.toUpperCase()}_KEY environment variable.
+`);
+    return null;
+  }
+  const provider = createProvider(name, apiKey);
+  if (!provider) {
+    displayError(`Unknown provider "${providerName}"`);
+    console.log("Available providers: unsplash, pexels, pixabay, random\n");
+    return null;
+  }
+  return { provider, name };
+}
+
+// src/cli/options-builder.ts
+function buildFetchOptions(options) {
+  const fetchOptions = {};
+  if (options.query) fetchOptions.query = options.query;
+  if (options.width) fetchOptions.width = options.width;
+  if (options.height) fetchOptions.height = options.height;
+  if (options.quality) fetchOptions.quality = options.quality;
+  if (options.orientation) fetchOptions.orientation = options.orientation;
+  return fetchOptions;
+}
+function buildDownloadOptions(options) {
+  const downloadOptions = {
+    overwrite: options.overwrite,
+    keepOriginalName: options.keepOriginalName
+  };
+  if (options.filename) {
+    downloadOptions.filename = options.filename;
+  }
+  return downloadOptions;
+}
+function getDownloadPath(options) {
+  return typeof options.download === "string" ? options.download : "./downloads";
+}
+
+// src/cli/actions.ts
+var import_ora = __toESM(require("ora"));
+var import_chalk2 = __toESM(require("chalk"));
+var path3 = __toESM(require("path"));
+async function fetchImage(fetcher, providerName, fetchOptions) {
+  const spinner = (0, import_ora.default)({
+    text: import_chalk2.default.cyan("\u{1F50D} Searching for the perfect image..."),
+    spinner: "dots"
+  }).start();
+  try {
+    const image = await fetcher.getRandom(fetchOptions);
+    spinner.succeed(import_chalk2.default.green("\u2728 Image found!"));
+    return image;
+  } catch (error) {
+    spinner.fail(import_chalk2.default.red("Failed to fetch image"));
+    throw error;
+  }
+}
+async function downloadImage(fetcher, image, downloadPath, downloadOptions) {
+  const resolvedPath = path3.resolve(downloadPath);
+  displayInfo(`Downloading to: ${import_chalk2.default.cyan(resolvedPath)}`);
+  const spinner = (0, import_ora.default)({
+    text: import_chalk2.default.cyan("\u{1F4BE} Downloading image..."),
+    spinner: "dots"
+  }).start();
+  try {
+    const filePath = await fetcher.download(image, downloadPath, downloadOptions);
+    spinner.succeed(import_chalk2.default.green("\u{1F4E6} Download complete!"));
+    return filePath;
+  } catch (error) {
+    spinner.fail(import_chalk2.default.red("Download failed"));
+    throw error;
+  }
+}
+
+// src/cli.ts
+loadEnvironment();
+var program = new import_commander.Command();
+program.name("random-image").description("\u{1F3A8} CLI tool to fetch random images from various providers").version("1.2.0");
+program.command("fetch").description("\u{1F5BC}\uFE0F  Fetch a random image from image providers").option("-q, --query <search>", "Search query for the image").option("-w, --width <number>", "Width of the image", parseInt).option("-h, --height <number>", "Height of the image", parseInt).option("--quality <number>", "Quality of the image (0-100)", parseInt).option("--orientation <type>", "Image orientation (landscape or portrait)").option("-p, --provider <name>", "Provider to use (unsplash, pexels, pixabay, or random)", "random").option("-d, --download [path]", "Download the image to specified directory (default: ./downloads)").option("--filename <name>", "Custom filename for downloaded image").option("--overwrite", "Overwrite existing files", false).option("--no-keep-original-name", "Generate random UUID filename instead of keeping original").action(async (options) => {
+  try {
+    const providers = getApiKeys();
+    let providerName = options.provider.toLowerCase();
+    if (providerName === "random") {
+      const selectedProvider = selectRandomProvider(providers);
+      if (!selectedProvider) {
+        displayError("No API keys found in environment variables.");
+        console.log(import_chalk3.default.yellow("\n\u{1F4A1} Please set at least one of:"));
+        console.log(import_chalk3.default.cyan("   \u2022 UNSPLASH_KEY"));
+        console.log(import_chalk3.default.cyan("   \u2022 PEXELS_KEY"));
+        console.log(import_chalk3.default.cyan("   \u2022 PIXABAY_KEY\n"));
+        process.exit(1);
+      }
+      providerName = selectedProvider;
+      displayInfo(`Using random provider: ${import_chalk3.default.bold(providerName)}`);
+    }
+    const result = getProviderInstance(providerName, providers);
+    if (!result) {
+      process.exit(1);
+    }
+    const { provider, name } = result;
+    const fetcher = new RandomImage(provider);
+    const fetchOptions = buildFetchOptions(options);
+    const image = await fetchImage(fetcher, name, fetchOptions);
+    displayImageInfo(image, name);
+    if (options.download !== void 0) {
+      const downloadPath = getDownloadPath(options);
+      const downloadOptions = buildDownloadOptions(options);
+      const filePath = await downloadImage(
+        fetcher,
+        image,
+        downloadPath,
+        downloadOptions
+      );
+      displayDownloadSuccess(filePath);
+    }
+  } catch (error) {
+    if (error instanceof Error) {
+      displayError(error.message);
+    } else {
+      displayError("An unexpected error occurred");
+    }
+    process.exit(1);
+  }
+});
+program.parse(process.argv);

package/dist/cli.mjs

@@ -0,0 +1,527 @@
+#!/usr/bin/env node
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __commonJS = (cb, mod) => function __require() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+
+// src/types.ts
+var init_types = __esm({
+  "src/types.ts"() {
+    "use strict";
+  }
+});
+
+// src/providers/unsplash.ts
+import axios from "axios";
+var UnsplashProvider;
+var init_unsplash = __esm({
+  "src/providers/unsplash.ts"() {
+    "use strict";
+    UnsplashProvider = class {
+      constructor(accessKey) {
+        this.accessKey = accessKey;
+      }
+      async fetchRandomImage(options) {
+        const response = await axios.get("https://api.unsplash.com/photos/random", {
+          headers: {
+            Authorization: `Client-ID ${this.accessKey}`
+          },
+          params: {
+            query: options.query,
+            orientation: options.orientation
+          }
+        });
+        const data = response.data;
+        const photo = Array.isArray(data) ? data[0] : data;
+        const baseUrl = photo.urls.raw;
+        const sizeParams = new URLSearchParams();
+        if (options.height || options.width) {
+          sizeParams.append("fit", "crop");
+          sizeParams.append("crop", "entropy");
+        }
+        if (options.width) sizeParams.append("w", options.width.toString());
+        if (options.height) sizeParams.append("h", options.height.toString());
+        if (options.quality) sizeParams.append("q", options.quality.toString());
+        const finalUrl = `${baseUrl}&${sizeParams.toString()}`;
+        return {
+          url: finalUrl,
+          width: options.width || photo.width,
+          height: options.height || photo.height,
+          author: photo.user.name,
+          authorUrl: photo.user.links.html,
+          originalUrl: photo.links.html
+          // Link to photo page
+        };
+      }
+    };
+  }
+});
+
+// src/providers/pexels.ts
+import axios2 from "axios";
+var PexelsProvider;
+var init_pexels = __esm({
+  "src/providers/pexels.ts"() {
+    "use strict";
+    PexelsProvider = class {
+      constructor(apiKey) {
+        this.apiKey = apiKey;
+      }
+      async fetchRandomImage(options) {
+        const endpoint = options.query ? "https://api.pexels.com/v1/search" : "https://api.pexels.com/v1/curated";
+        const randomPage = Math.floor(Math.random() * 100) + 1;
+        const params = {
+          per_page: 1,
+          page: randomPage
+        };
+        if (options.query) params.query = options.query;
+        const response = await axios2.get(endpoint, {
+          headers: {
+            Authorization: this.apiKey
+          },
+          params
+        });
+        const data = response.data;
+        if (!data.photos || data.photos.length === 0) {
+          throw new Error("No images found on Pexels");
+        }
+        const photo = data.photos[0];
+        const baseUrl = photo.src.original;
+        const sizeParams = new URLSearchParams();
+        sizeParams.append("auto", "compress");
+        sizeParams.append("cs", "tinysrgb");
+        if (options.width) sizeParams.append("w", options.width.toString());
+        if (options.height) sizeParams.append("h", options.height.toString());
+        const finalUrl = `${baseUrl}?${sizeParams.toString()}`;
+        return {
+          url: finalUrl,
+          width: options.width || photo.width,
+          height: options.height || photo.height,
+          author: photo.photographer,
+          authorUrl: photo.photographer_url,
+          originalUrl: photo.url
+        };
+      }
+    };
+  }
+});
+
+// src/providers/pixabay.ts
+import axios3 from "axios";
+var PixabayProvider;
+var init_pixabay = __esm({
+  "src/providers/pixabay.ts"() {
+    "use strict";
+    PixabayProvider = class {
+      constructor(apiKey) {
+        this.apiKey = apiKey;
+      }
+      async fetchRandomImage(options) {
+        const params = {
+          key: this.apiKey,
+          q: options.query || "",
+          per_page: 20
+          // Fetch a few to pick randomly
+        };
+        if (options.orientation) {
+          params.orientation = options.orientation === "portrait" ? "vertical" : "horizontal";
+        }
+        const response = await axios3.get("https://pixabay.com/api/", {
+          params
+        });
+        const hits = response.data.hits;
+        if (!hits || hits.length === 0) {
+          throw new Error("No images found");
+        }
+        const randomHit = hits[Math.floor(Math.random() * hits.length)];
+        return {
+          url: randomHit.largeImageURL || randomHit.webformatURL,
+          width: randomHit.imageWidth || randomHit.webformatWidth,
+          height: randomHit.imageHeight || randomHit.webformatHeight,
+          author: randomHit.user,
+          authorUrl: `https://pixabay.com/users/${randomHit.user}-${randomHit.user_id}/`,
+          originalUrl: randomHit.pageURL
+        };
+      }
+    };
+  }
+});
+
+// src/image-fetcher.ts
+import * as fs from "fs";
+import * as path from "path";
+import axios4 from "axios";
+import { v7 as uuidv4 } from "uuid";
+var RandomImage;
+var init_image_fetcher = __esm({
+  "src/image-fetcher.ts"() {
+    "use strict";
+    RandomImage = class {
+      constructor(provider) {
+        this.provider = provider;
+      }
+      /**
+       * Fetches a random image based on the provided options.
+       * @param options - Configuration options for the image (width, height, query, etc.)
+       * @returns A promise that resolves to an ImageResult object.
+       */
+      async getRandom(options = {}) {
+        return this.provider.fetchRandomImage(options);
+      }
+      /**
+       * Downloads an image to a specified directory.
+       * @param imageUrl - The URL of the image to download (can be a string or ImageResult object)
+       * @param destinationPath - The directory path where the image will be saved
+       * @param options - Download options (filename, overwrite, etc.)
+       * @returns A promise that resolves to the full path of the downloaded file
+       */
+      async download(imageUrl, destinationPath, options = {}) {
+        const url = typeof imageUrl === "string" ? imageUrl : imageUrl.url;
+        if (!fs.existsSync(destinationPath)) {
+          fs.mkdirSync(destinationPath, { recursive: true });
+        }
+        let finalFilename;
+        if (options.filename) {
+          finalFilename = options.filename;
+        } else if (options.keepOriginalName) {
+          const urlPath = new URL(url).pathname;
+          const urlFilename = path.basename(urlPath);
+          if (urlFilename && urlFilename.length > 0 && urlFilename !== "/") {
+            finalFilename = urlFilename;
+          } else {
+            const ext = this.getExtensionFromUrl(url) || ".jpg";
+            finalFilename = `${uuidv4()}${ext}`;
+          }
+        } else {
+          const ext = this.getExtensionFromUrl(url) || ".jpg";
+          finalFilename = `${uuidv4()}${ext}`;
+        }
+        if (!path.extname(finalFilename)) {
+          finalFilename += ".jpg";
+        }
+        const fullPath = path.join(destinationPath, finalFilename);
+        if (fs.existsSync(fullPath) && !options.overwrite) {
+          throw new Error(`File already exists: ${fullPath}. Set overwrite: true to replace it.`);
+        }
+        try {
+          const response = await axios4.get(url, {
+            responseType: "stream",
+            maxRedirects: 5
+            // Automatically handle redirects
+          });
+          const writer = fs.createWriteStream(fullPath);
+          response.data.pipe(writer);
+          return new Promise((resolve3, reject) => {
+            writer.on("finish", () => {
+              resolve3(fullPath);
+            });
+            writer.on("error", (err) => {
+              fs.unlink(fullPath, () => {
+              });
+              reject(err);
+            });
+            response.data.on("error", (err) => {
+              writer.close();
+              fs.unlink(fullPath, () => {
+              });
+              reject(err);
+            });
+          });
+        } catch (error) {
+          if (axios4.isAxiosError(error)) {
+            throw new Error(`Failed to download image: ${error.message}`);
+          }
+          throw error;
+        }
+      }
+      /**
+       * Helper method to extract file extension from URL
+       * @param url - The URL to extract extension from
+       * @returns The file extension (e.g., '.jpg', '.png') or null
+       */
+      getExtensionFromUrl(url) {
+        try {
+          const urlPath = new URL(url).pathname;
+          const ext = path.extname(urlPath);
+          return ext || null;
+        } catch {
+          return null;
+        }
+      }
+    };
+  }
+});
+
+// src/index.ts
+var init_index = __esm({
+  "src/index.ts"() {
+    "use strict";
+    init_types();
+    init_unsplash();
+    init_pexels();
+    init_pixabay();
+    init_image_fetcher();
+  }
+});
+
+// src/cli/env-loader.ts
+import * as path2 from "path";
+import * as dotenv from "dotenv";
+import * as fs2 from "fs";
+function loadEnvironment() {
+  const possibleEnvPaths = [
+    path2.resolve(process.cwd(), ".env"),
+    // Current working directory
+    path2.resolve(__dirname, ".env"),
+    // Same directory as the CLI script (dist/)
+    path2.resolve(__dirname, "..", ".env")
+    // Parent directory (root of project)
+  ];
+  for (const envPath of possibleEnvPaths) {
+    if (fs2.existsSync(envPath)) {
+      dotenv.config({ path: envPath });
+      break;
+    }
+  }
+}
+function getApiKeys() {
+  return {
+    unsplash: process.env.UNSPLASH_KEY,
+    pexels: process.env.PEXELS_KEY,
+    pixabay: process.env.PIXABAY_KEY
+  };
+}
+var init_env_loader = __esm({
+  "src/cli/env-loader.ts"() {
+    "use strict";
+  }
+});
+
+// src/cli/display.ts
+import chalk from "chalk";
+import boxen from "boxen";
+function displayError(message) {
+  console.error(chalk.red(`
+\u274C ${message}`));
+}
+function displayInfo(message) {
+  console.log(chalk.blue(`
+\u2139\uFE0F  ${message}`));
+}
+function displayImageInfo(image, providerName) {
+  const content = [
+    `${chalk.bold("\u{1F3A8} Provider:")} ${chalk.cyan(providerName)}`,
+    `${chalk.bold("\u{1F4D0} Size:")} ${chalk.yellow(`${image.width}x${image.height}`)}`,
+    `${chalk.bold("\u{1F464} Author:")} ${chalk.magenta(image.author)}`,
+    image.authorUrl ? `${chalk.bold("\u{1F517} Author URL:")} ${chalk.gray(image.authorUrl)}` : "",
+    `${chalk.bold("\u{1F310} Original:")} ${chalk.gray(image.originalUrl)}`,
+    `${chalk.bold("\u{1F4F7} Image URL:")} ${chalk.gray(image.url)}`
+  ].filter(Boolean).join("\n");
+  console.log("\n" + boxen(content, {
+    padding: 1,
+    margin: 1,
+    borderStyle: "round",
+    borderColor: "green",
+    title: "\u{1F5BC}\uFE0F  Image Details",
+    titleAlignment: "center"
+  }));
+}
+function displayDownloadSuccess(filePath) {
+  const content = `${chalk.bold("\u{1F4C1} Saved to:")} ${chalk.cyan(filePath)}`;
+  console.log("\n" + boxen(content, {
+    padding: 1,
+    margin: 1,
+    borderStyle: "round",
+    borderColor: "blue",
+    title: "\u{1F4BE} Download Complete",
+    titleAlignment: "center"
+  }));
+}
+var init_display = __esm({
+  "src/cli/display.ts"() {
+    "use strict";
+  }
+});
+
+// src/cli/provider-manager.ts
+function selectRandomProvider(providers) {
+  const availableProviders = Object.entries(providers).filter(([_, key]) => key).map(([name]) => name);
+  if (availableProviders.length === 0) {
+    return null;
+  }
+  return availableProviders[Math.floor(Math.random() * availableProviders.length)];
+}
+function createProvider(providerName, apiKey) {
+  switch (providerName) {
+    case "unsplash":
+      return new UnsplashProvider(apiKey);
+    case "pexels":
+      return new PexelsProvider(apiKey);
+    case "pixabay":
+      return new PixabayProvider(apiKey);
+    default:
+      return null;
+  }
+}
+function getProviderInstance(providerName, providers) {
+  const name = providerName.toLowerCase();
+  const apiKey = providers[name];
+  if (!apiKey) {
+    displayError(`API key for ${providerName} not found.`);
+    console.log(`Please set ${providerName.toUpperCase()}_KEY environment variable.
+`);
+    return null;
+  }
+  const provider = createProvider(name, apiKey);
+  if (!provider) {
+    displayError(`Unknown provider "${providerName}"`);
+    console.log("Available providers: unsplash, pexels, pixabay, random\n");
+    return null;
+  }
+  return { provider, name };
+}
+var init_provider_manager = __esm({
+  "src/cli/provider-manager.ts"() {
+    "use strict";
+    init_index();
+    init_display();
+  }
+});
+
+// src/cli/options-builder.ts
+function buildFetchOptions(options) {
+  const fetchOptions = {};
+  if (options.query) fetchOptions.query = options.query;
+  if (options.width) fetchOptions.width = options.width;
+  if (options.height) fetchOptions.height = options.height;
+  if (options.quality) fetchOptions.quality = options.quality;
+  if (options.orientation) fetchOptions.orientation = options.orientation;
+  return fetchOptions;
+}
+function buildDownloadOptions(options) {
+  const downloadOptions = {
+    overwrite: options.overwrite,
+    keepOriginalName: options.keepOriginalName
+  };
+  if (options.filename) {
+    downloadOptions.filename = options.filename;
+  }
+  return downloadOptions;
+}
+function getDownloadPath(options) {
+  return typeof options.download === "string" ? options.download : "./downloads";
+}
+var init_options_builder = __esm({
+  "src/cli/options-builder.ts"() {
+    "use strict";
+  }
+});
+
+// src/cli/actions.ts
+import ora from "ora";
+import chalk2 from "chalk";
+import * as path3 from "path";
+async function fetchImage(fetcher, providerName, fetchOptions) {
+  const spinner = ora({
+    text: chalk2.cyan("\u{1F50D} Searching for the perfect image..."),
+    spinner: "dots"
+  }).start();
+  try {
+    const image = await fetcher.getRandom(fetchOptions);
+    spinner.succeed(chalk2.green("\u2728 Image found!"));
+    return image;
+  } catch (error) {
+    spinner.fail(chalk2.red("Failed to fetch image"));
+    throw error;
+  }
+}
+async function downloadImage(fetcher, image, downloadPath, downloadOptions) {
+  const resolvedPath = path3.resolve(downloadPath);
+  displayInfo(`Downloading to: ${chalk2.cyan(resolvedPath)}`);
+  const spinner = ora({
+    text: chalk2.cyan("\u{1F4BE} Downloading image..."),
+    spinner: "dots"
+  }).start();
+  try {
+    const filePath = await fetcher.download(image, downloadPath, downloadOptions);
+    spinner.succeed(chalk2.green("\u{1F4E6} Download complete!"));
+    return filePath;
+  } catch (error) {
+    spinner.fail(chalk2.red("Download failed"));
+    throw error;
+  }
+}
+var init_actions = __esm({
+  "src/cli/actions.ts"() {
+    "use strict";
+    init_display();
+  }
+});
+
+// src/cli.ts
+import { Command } from "commander";
+import chalk3 from "chalk";
+var require_cli = __commonJS({
+  "src/cli.ts"() {
+    init_index();
+    init_env_loader();
+    init_display();
+    init_provider_manager();
+    init_options_builder();
+    init_actions();
+    loadEnvironment();
+    var program = new Command();
+    program.name("random-image").description("\u{1F3A8} CLI tool to fetch random images from various providers").version("1.2.0");
+    program.command("fetch").description("\u{1F5BC}\uFE0F  Fetch a random image from image providers").option("-q, --query <search>", "Search query for the image").option("-w, --width <number>", "Width of the image", parseInt).option("-h, --height <number>", "Height of the image", parseInt).option("--quality <number>", "Quality of the image (0-100)", parseInt).option("--orientation <type>", "Image orientation (landscape or portrait)").option("-p, --provider <name>", "Provider to use (unsplash, pexels, pixabay, or random)", "random").option("-d, --download [path]", "Download the image to specified directory (default: ./downloads)").option("--filename <name>", "Custom filename for downloaded image").option("--overwrite", "Overwrite existing files", false).option("--no-keep-original-name", "Generate random UUID filename instead of keeping original").action(async (options) => {
+      try {
+        const providers = getApiKeys();
+        let providerName = options.provider.toLowerCase();
+        if (providerName === "random") {
+          const selectedProvider = selectRandomProvider(providers);
+          if (!selectedProvider) {
+            displayError("No API keys found in environment variables.");
+            console.log(chalk3.yellow("\n\u{1F4A1} Please set at least one of:"));
+            console.log(chalk3.cyan("   \u2022 UNSPLASH_KEY"));
+            console.log(chalk3.cyan("   \u2022 PEXELS_KEY"));
+            console.log(chalk3.cyan("   \u2022 PIXABAY_KEY\n"));
+            process.exit(1);
+          }
+          providerName = selectedProvider;
+          displayInfo(`Using random provider: ${chalk3.bold(providerName)}`);
+        }
+        const result = getProviderInstance(providerName, providers);
+        if (!result) {
+          process.exit(1);
+        }
+        const { provider, name } = result;
+        const fetcher = new RandomImage(provider);
+        const fetchOptions = buildFetchOptions(options);
+        const image = await fetchImage(fetcher, name, fetchOptions);
+        displayImageInfo(image, name);
+        if (options.download !== void 0) {
+          const downloadPath = getDownloadPath(options);
+          const downloadOptions = buildDownloadOptions(options);
+          const filePath = await downloadImage(
+            fetcher,
+            image,
+            downloadPath,
+            downloadOptions
+          );
+          displayDownloadSuccess(filePath);
+        }
+      } catch (error) {
+        if (error instanceof Error) {
+          displayError(error.message);
+        } else {
+          displayError("An unexpected error occurred");
+        }
+        process.exit(1);
+      }
+    });
+    program.parse(process.argv);
+  }
+});
+export default require_cli();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nghiavuive/random-image",
-  "version": "1.1.0",
-  "description": "",
+  "version": "1.2.1",
+  "description": "Fetch random images from Unsplash, Pexels, and Pixabay with CLI support",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -32,13 +32,20 @@
   "devDependencies": {
     "@types/node": "^25.2.0",
     "@types/uuid": "^10.0.0",
-    "dotenv": "^17.2.3",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
   "dependencies": {
     "axios": "^1.13.4",
+    "boxen": "^8.0.1",
+    "chalk": "^5.6.2",
+    "commander": "^12.1.0",
+    "dotenv": "^17.2.3",
+    "ora": "^9.1.0",
     "uuid": "^13.0.0"
+  },
+  "bin": {
+    "random-image": "./dist/cli.js"
   }
 }