I scan pretty much everything — bills, old photos, mortgage documents, tax stuff, etc. It can be tedious, but it makes finding things much easier when you need to remember whether you filed in 83(b) election in 2006 or what exactly the previous owners disclosed about the condition of the roof.

Having a good scanner with a document feeder helps a lot, but the standard scanning UI in Mac OS X isn’t exactly efficient for quickly scanning a whole bunch of stuff into labeled directories. What I really wanted was a way that I could just type out something quickly on the command line to control the scanner, but I couldn’t find anything out there. So I wrote scanline, which I’m now making available as an MIT-licensed open source project.

Using scanline

The basic way to use scanline is to just invoke it on the command line with no arguments (or hit up-arrow if you just scanned something previously):

airica:~ klep$ scanline

This will scan the current document(s) in the document feeder of the default scanner into ~/Documents/Archive/[year]/scan_[hms].pdf

But there’s a whole lot more you can do. scanline uses directories as labels, so if the document you’re scanning is your auto registration, you can specify that scanline should put it in the “car” directory:

airica:~ klep$ scanline car

This puts the document into ~/Documents/Archive/car/[year]/scan_[hms].pdf

If you also want your registration to show up in your directory for taxes (so you remember to deduct the VLF), you can specify multiple labels:

airica:~ klep$ scanline car taxes

This creates an alias of the scanned document in ~/Documents/Archive/taxes/[year]/scan_[hms].pdf in addition to the original in the car directory.

If it’s a double-sided document (and your scanner supports it), use -duplex to scan both sides:

airica:~ klep$ scanline -duplex car taxes

Want to scan from the flatbed scanner instead of the document feeder?

airica:~ klep$ scanline -flatbed

Want to scan into a different root directory instead of ~/Documents/Archive?

airica:~ klep$ scanline -dir ~/Desktop

Here’s a good one — got lots of items to scan on the flatbed but want them all put together into a single PDF?

airica:~ klep$ scanline -batch -flatbed

Want to name the document something that isn’t generic?

airica:~ klep$ scanline -flatbed -name registration car

The above command will scan the item on the flatbed into ~/Documents/Archive/car/[year]/registration.pdf

If you have multiple scanners connected to your computer, you can select them by name:

airica:~ klep$ scanline -scanner "Epson 565655"

If you’re not sure what scanners are available, list them:

airica:~ klep$ scanline -list

Obtaining scanline

If you’d like to build scanline from source, enhance it, or tweak it for your needs, get it from:


If you just want the binary (it’s a debug build but plenty fast and stable for real use), you can download it here.


How It Works

scanline was created using the ImageCaptureCore framework. It uses Lumberjack for logging and XCTest/OCMock for unit tests. It’s my first Mac app in quite some time, so go easy on me if you look at the source.






64 thoughts on “scanline – Command-line Document Scanning for Mac OS X

  1. mike

    Big thank you Scott!

    That was exactly the missing part in my home-grown-document-management system. Applescript and the image capture worked, but was too flacky.

    Works great!

  2. […] searching around online I ran across scanline.  It looks like Scott Kleper is the creator and his post describes the software pretty well.  He provides a binary build as well as GitHub reference […]

  3. Dainius Šileika

    Hello Scott,

    As of last year, every time I scan, scanline either scans twice, or doesn’t scan the first time, I’m forced to press a key again, and then have a double scan.

    Here’s the verbose output:

    %scanline -flatbed -res 300 -v


  4. klep

    Hmm… Are you saying that there’s one document but it has two pages?

  5. John Winfield


    I dowloaded the scanline .dms, binary, how do I install it on a Mac OS X 10.12 El Captain?

    Will scanline work with ScanSnap S1500m?

    Thank you


  6. Oliver

    Just discovered this after getting tired of clicking through UIs and thinking that someone might have already come up with a better solution to mass scanning. Seems to work great with my Brother MFC-7440 and High Sierra. Thank you so much for creating it and releasing it as open source!

  7. Kristian

    Thanks for an excellent tool!

    A very nice-to-have feature suggestion: Could you implement a ‘-beep’ that makes the computer beep for half a second every time a scan is done in batch mode?

  8. Andrew

    Hi, thank you for publishing this tool. I’m getting an error (Big Sur 11.6).

    “Available scanners:
    * EPSON WP-4510/4520/4530/4540
    * EPSON WP-4535 Series

    “Starting scan…
    Failed to scan document.

  9. klep

    Hi Andrew – By default, scanline will attempt to use the document feeder. If you are using the flatbed, add the `-flatbed` option.

  10. Jason

    This is just what I need!
    I’ve started using a self-hosted instance of Papermerge to manage various important documents. I was really hoping to find a way to scan and upload files automatically, saving me the step of making the PDF and then dragging it into the Papermerge UI by hand. I was looking at the Mac Automator tool, but it doesn’t appear to have a way to interface with a scanner. Scanline lets me do exactly what I want with some simple bash scripting.

  11. klep

    Glad it’s working for you!

  12. MarkDM

    I downloaded the scanline 2.0 version here https://github.com/klep/scanline/blob/master/scanline-2.0.pkg?raw=true

    It will not install into OSX10.15 Catalina

    Other than that looks very useful for what I need. I have no idea how to build it though.

  13. klep

    What error do you get on Catalina?

  14. lakitu

    Catalina: “This package is incompatible with this version of macOS.”

Leave A Comment

Recommended Posts