pngpaste Documentation

# Install via curl (recommended)
curl -fsSL https://raw.githubusercontent.com/yriveiro/pngpaste/main/scripts/install.sh | bash

# Or with explicit confirmation skip
curl -fsSL https://raw.githubusercontent.com/yriveiro/pngpaste/main/scripts/install.sh | bash -s -- --yes

# Custom install directory
curl -fsSL https://raw.githubusercontent.com/yriveiro/pngpaste/main/scripts/install.sh | bash -s -- --bin-dir ~/.local/bin

# Verify installation
pngpaste --version

# Clone the repository
git clone https://github.com/yriveiro/pngpaste.git
cd pngpaste

# Build (debug)
swift build

# Build (release)
swift build -c release

# Run directly
swift run pngpaste output.png

# Install to /usr/local/bin
cp .build/release/pngpaste /usr/local/bin/

# Save clipboard image to PNG file
pngpaste screenshot.png

# Save as JPEG (format determined by extension)
pngpaste photo.jpg

# Save as GIF
pngpaste animation.gif

# Output to stdout (pipe to another command)
pngpaste - | convert - -resize 50% smaller.png

# Output as base64 (useful for embedding)
pngpaste -b | pbcopy

# Combine with other tools
pngpaste - | base64 | curl -X POST -d @- api.example.com/upload

# Check if clipboard has an image
if pngpaste /tmp/test.png 2>/dev/null; then
    echo "Image saved successfully"
else
    echo "No image on clipboard"
fi

# Example error messages:
# pngpaste: no image data found on the clipboard
# pngpaste: failed to write to '/path': Permission denied
# pngpaste: clipboard contains unsupported image format

private func performPaste(
    mode: OutputMode,
    format: OutputFormat,
    clipboardService: some ClipboardReading = ClipboardService(),
    renderService: some ImageRendering = ImageRenderService(),
    outputService: some OutputWriting = OutputService()
) async throws(PngPasteError) {
    let image = try clipboardService.readImage()
    let imageType = try clipboardService.imageType(for: image)
    let data = try await renderService.render(image, imageType: imageType, as: format)

    try outputService.write(data, to: mode)
}

import AppKit
import ArgumentParser

@main
struct PngPaste: AsyncParsableCommand {
    static let configuration = CommandConfiguration(
        commandName: "pngpaste",
        abstract: "Paste PNG into files, much like pbpaste does for text.",
        discussion: """
        Supported input formats: PNG, PDF, GIF, TIF, JPEG, HEIC
        Supported output formats: PNG, GIF, JPEG, TIFF
        Output format is determined by the file extension, defaulting to PNG.
        """,
        version: "1.0.0"
    )

    @Flag(name: .short, help: "Output to stdout as base64 encoded PNG")
    var base64 = false

    @Argument(help: "Output file path (use '-' for binary stdout)")
    var outputPath: String?
}

mutating func run() async throws {
    guard let mode = determineOutputMode() else {
        throw CleanExit.helpRequest()
    }

    let format = determineOutputFormat(for: mode)

    do {
        try await performPaste(mode: mode, format: format)
    } catch {
        fputs("pngpaste: \(error.description)\n", stderr)
        throw ExitCode.failure
    }
}

private func determineOutputMode() -> OutputMode? {
    if base64 {
        return .base64
    }

    guard let path = outputPath else {
        return nil
    }

    return path == "-" ? .stdout : .file(path: path)
}

private func determineOutputFormat(for mode: OutputMode) -> OutputFormat {
    switch mode {
    case let .file(path):
        OutputFormat(fromFilename: path)
    case .stdout, .base64:
        .png
    }
}

import AppKit

enum OutputFormat: String, CaseIterable, Sendable, Equatable {
    case png
    case gif
    case jpeg
    case tiff

    private static let jpegCompressionQuality: Double = 0.9

    var bitmapType: NSBitmapImageRep.FileType {
        switch self {
        case .png: .png
        case .gif: .gif
        case .jpeg: .jpeg
        case .tiff: .tiff
        }
    }

    var displayName: String {
        rawValue.uppercased()
    }
}

init(fromExtension ext: String) {
    switch ext.lowercased() {
    case "gif":
        self = .gif
    case "jpg", "jpeg":
        self = .jpeg
    case "tif", "tiff":
        self = .tiff
    default:
        self = .png
    }
}

init(fromFilename filename: String) {
    let ext = URL(fileURLWithPath: filename).pathExtension
    self.init(fromExtension: ext)
}

enum OutputMode: Sendable, Equatable {
    case file(path: String)
    case stdout
    case base64
}

enum ImageType: Sendable {
    case bitmap
    case pdf
}

import Foundation

enum PngPasteError: Error, CustomStringConvertible, Sendable, Equatable {
    case noImageOnClipboard
    case unsupportedImageFormat
    case conversionFailed(format: String)
    case writeFailure(path: String, reason: String)
    case stdoutWriteFailure(reason: String)

    var description: String {
        switch self {
        case .noImageOnClipboard:
            "no image data found on the clipboard"
        case .unsupportedImageFormat:
            "clipboard contains unsupported image format"
        case let .conversionFailed(format):
            "failed to convert image to \(format)"
        case let .writeFailure(path, reason):
            "failed to write to '\(path)': \(reason)"
        case let .stdoutWriteFailure(reason):
            "failed to write to stdout: \(reason)"
        }
    }
}

import AppKit

protocol ClipboardReading: Sendable {
    func readImage() throws(PngPasteError) -> NSImage

    func imageType(for image: NSImage) throws(PngPasteError) -> ImageType
}

import AppKit

@MainActor
protocol ImageRendering: Sendable {
    func render(
        _ image: NSImage,
        imageType: ImageType,
        as format: OutputFormat
    ) throws(PngPasteError) -> Data
}

import Foundation

protocol OutputWriting: Sendable {
    func write(_ data: Data, to mode: OutputMode) throws(PngPasteError)
}

import AppKit

struct ClipboardService: ClipboardReading {
    private static let supportedTypes: [NSPasteboard.PasteboardType] = [
        .png,
        .tiff,
        NSPasteboard.PasteboardType("public.heic"),
        NSPasteboard.PasteboardType("public.jpeg"),
        NSPasteboard.PasteboardType("com.compuserve.gif"),
        .pdf,
    ]

    func readImage() throws(PngPasteError) -> NSImage {
        let pasteboard = NSPasteboard.general

        if let availableType = pasteboard.availableType(from: Self.supportedTypes),
           let data = pasteboard.data(forType: availableType),
           let image = NSImage(data: data),
           isValidImage(image) {
            return image
        }

        if pasteboard.canReadItem(withDataConformingToTypes: NSImage.imageTypes),
           let image = NSImage(pasteboard: pasteboard),
           isValidImage(image) {
            return image
        }

        throw .noImageOnClipboard
    }
}

func imageType(for image: NSImage) throws(PngPasteError) -> ImageType {
    guard isValidImage(image) else {
        throw .unsupportedImageFormat
    }

    if image.representations.contains(where: { $0 is NSPDFImageRep }) {
        return .pdf
    }

    if image.representations.contains(where: { $0 is NSBitmapImageRep }) {
        return .bitmap
    }

    if image.tiffRepresentation != nil {
        return .bitmap
    }

    throw .unsupportedImageFormat
}

private func isValidImage(_ image: NSImage) -> Bool {
    image.size.width > 0 && image.size.height > 0 && !image.representations.isEmpty
}

import AppKit

@MainActor
struct ImageRenderService: ImageRendering {
    private let pdfScaleFactor: CGFloat = 2.0

    func render(
        _ image: NSImage,
        imageType: ImageType,
        as format: OutputFormat
    ) throws(PngPasteError) -> Data {
        let data: Data? = switch imageType {
        case .bitmap:
            renderBitmap(image, as: format)
        case .pdf:
            renderPDF(image, as: format)
        }

        guard let data else {
            throw .conversionFailed(format: format.displayName)
        }

        return data
    }
}

private func renderBitmap(_ image: NSImage, as format: OutputFormat) -> Data? {
    if let data = NSBitmapImageRep.representationOfImageReps(
        in: image.representations,
        using: format.bitmapType,
        properties: format.encodingProperties
    ), !data.isEmpty {
        return data
    }

    guard let tiffData = image.tiffRepresentation,
          let bitmapRep = NSBitmapImageRep(data: tiffData)
    else {
        return nil
    }

    return bitmapRep.representation(using: format.bitmapType, properties: format.encodingProperties)
}

private func renderPDF(_ image: NSImage, as format: OutputFormat) -> Data? {
    guard let pdfRep = image.representations
        .compactMap({ $0 as? NSPDFImageRep }).first else {
        return nil
    }

    let scaledWidth = Int(pdfRep.bounds.width * pdfScaleFactor)
    let scaledHeight = Int(pdfRep.bounds.height * pdfScaleFactor)

    guard scaledWidth > 0, scaledHeight > 0 else { return nil }

    guard let bitmapRep = NSBitmapImageRep(
        bitmapDataPlanes: nil,
        pixelsWide: scaledWidth,
        pixelsHigh: scaledHeight,
        bitsPerSample: 8,
        samplesPerPixel: 4,
        hasAlpha: true,
        isPlanar: false,
        colorSpaceName: .deviceRGB,
        bytesPerRow: 0,
        bitsPerPixel: 0
    ) else { return nil }

    NSGraphicsContext.saveGraphicsState()
    defer { NSGraphicsContext.restoreGraphicsState() }

    guard let context = NSGraphicsContext(bitmapImageRep: bitmapRep) else {
        return nil
    }

    NSGraphicsContext.current = context
    NSColor.white.setFill()
    NSRect(x: 0, y: 0, width: scaledWidth, height: scaledHeight).fill()

    let drawRect = NSRect(x: 0, y: 0, width: scaledWidth, height: scaledHeight)
    pdfRep.draw(in: drawRect)

    return bitmapRep.representation(using: format.bitmapType, properties: format.encodingProperties)
}

import Foundation

struct OutputService: OutputWriting {
    func write(_ data: Data, to mode: OutputMode) throws(PngPasteError) {
        switch mode {
        case let .file(path):
            try writeToFile(data, path: path)
        case .stdout:
            try writeToStdout(data)
        case .base64:
            try writeBase64ToStdout(data)
        }
    }
}

private func writeToFile(_ data: Data, path: String) throws(PngPasteError) {
    let url = URL(fileURLWithPath: path).standardized

    do {
        try data.write(to: url, options: .atomic)
    } catch {
        let reason = (error as NSError).localizedDescription
        throw .writeFailure(path: path, reason: reason)
    }
}

private func writeToStdout(_ data: Data) throws(PngPasteError) {
    let stdout = FileHandle.standardOutput

    do {
        try stdout.write(contentsOf: data)
    } catch {
        throw .stdoutWriteFailure(reason: error.localizedDescription)
    }
}

private func writeBase64ToStdout(_ data: Data) throws(PngPasteError) {
    let base64Data = data.base64EncodedData()
    try writeToStdout(base64Data)
}