Automation (AppleScript)¶

Alcove has a full AppleScript dictionary for automating imports, querying and updating metadata, managing tags and series, and controlling library operations. AppleScript support is Mac-only.

Opening the Dictionary¶

In Script Editor, choose File → Open Dictionary… and select Alcove from the list of scriptable applications. The dictionary documents every object, property, and command.

Object Model¶

Object	What it represents	Elements
`application`	The Alcove app	—
`document`	An open library	`book`, `tag`, `series`
`book`	A book in a library	`tag`
`tag`	A tag defined in a library	`book`
`series`	A series defined in a library	`book`

The front document property on application returns the frontmost open library.

The selection property on document returns the currently selected books as a list and accepts a book or list of books to change the selection programmatically.

Commands¶

Command	Target	Description
`create library`	application	Create a new library
`import books`	document	Import a file or folder of books
`export library`	document	Export the catalog as a JSON file
`open book`	book	Open in the default reader app
`export book`	book	Copy the book file to a path
`delete book`	book	Permanently remove the book and its file
`remove local copy`	book	Remove the local file, keep the iCloud record
`replace cover`	book	Replace the cover image
`look up metadata`	book	Trigger the metadata lookup sheet
`get book info`	book	Bring the detail pane into focus
`reveal book`	book	Reveal the book file in Finder

Examples¶

List all books in the frontmost library¶

tell application "Alcove"
    tell front document
        set bookList to name of every book
    end tell
end tell

Get books by reading status¶

tell application "Alcove"
    tell front document
        set unread to every book whose reading status is "unread"
    end tell
end tell

Set a rating¶

tell application "Alcove"
    tell front document
        set rating of book "Dune" to 5
    end tell
end tell

Assign tags to a book¶

tell application "Alcove"
    tell front document
        set tag names of book "Dune" to {"Science Fiction", "Classic"}
    end tell
end tell

Create a new tag and assign it¶

tell application "Alcove"
    tell front document
        make new tag with properties {name: "To Read", color: "#FF5733"}
        set tag names of book "Dune" to (tag names of book "Dune") & {"To Read"}
    end tell
end tell

Set series name and position¶

tell application "Alcove"
    tell front document
        set series name of book "Dune" to "Dune Chronicles"
        set series index of book "Dune" to 1
    end tell
end tell

Get all books in a series¶

tell application "Alcove"
    tell front document
        set duneBooks to every book of series "Dune Chronicles"
    end tell
end tell

Import a folder of books¶

tell application "Alcove"
    tell front document
        set count to import books from POSIX file "/Users/me/Downloads/ebooks"
    end tell
end tell

Export a book file¶

tell application "Alcove"
    tell front document
        export book "Dune" to POSIX file "/Users/me/Desktop/Dune.epub"
    end tell
end tell

Export the library catalog¶

tell application "Alcove"
    tell front document
        export library to POSIX file "/Users/me/Downloads/Library Backup.json"
    end tell
end tell

Note: Due to App Sandbox restrictions, the export destination must be in ~/Downloads, ~/Desktop, or a location the user has previously granted access to.

Replace a cover from a file¶

tell application "Alcove"
    tell front document
        replace cover of book "Dune" from file POSIX file "/Users/me/covers/dune.jpg"
    end tell
end tell

Create a new library¶

tell application "Alcove"
    set newLib to create library named "Work Reading" syncing via icloud true
end tell

Reading Status Values¶

Use these tokens in scripts regardless of the app's display language:

Token	Meaning
`"unread"`	Not started
`"reading"`	In progress
`"read"`	Finished
`"did not finish"`	Abandoned

Book Properties Reference¶

Property	Type	Access	Notes
`id`	text	r	Stable UUID
`name`	text	rw	Book title
`author`	text	rw	Comma-separated author names
`rating`	integer	rw	0–5 (0 = unrated)
`reading status`	text	rw	See Reading Status Values above
`ISBN`	text	rw	Empty string if not set
`publisher`	text	rw	Empty string if not set
`format`	text	r	`epub`, `mobi`, `azw3`, or `pdf`
`cover`	file	r	JPEG file URL, or `missing value`
`synopsis`	text	rw	Stored as Markdown; empty string if not set
`language`	text	rw	BCP-47 tag, e.g. `"en"`, `"fr"`
`published date`	date	rw	Edition publication date, or `missing value`
`published year`	integer	rw	Edition year (0 = unset); preserves existing month/day on write
`original publication date`	date	rw	Date of first publication, or `missing value`
`file size`	integer	r	File size in bytes, or `missing value`
`file path`	file	r	Location of the book file on disk
`series name`	text	rw	Empty string if not in a series; creates the series if it doesn't exist
`series index`	number	rw	Reading-order position (0 = unset); requires `series name` to be set first
`tag names`	list of text	rw	Replaces the full tag set on write; creates tags as needed