Keep It AppleScript Tips

Contents

Terminology

While the Keep It app refers to folders, bundles and things like All Items collectively as “lists”, a list is a class in AppleScript, and so Keep It’s scripting terminology uses “groups” instead.

Similarly, “item” is a generic term in AppleScript, and so items in Keep It are referred to as ”Keep It items” in AppleScript.

Open Keep It’s dictionary in Script Editor and look at the Keep It suite to see all its terminology.

Keep It dictionary in Script Editor

Scripts That Launch the App

Keep It loads its library asynchronously; the app will launch quickly, but the library may not be available for another second or so.

If your script could potentially launch Keep It, you can test whether the top level folder is available before proceeding:

tell application "Keep It"

repeat until top level folder is not missing value

delay 1

end repeat

-- Start your script here

end tell


Getting Objects

Keep It provides convenient ways to get the currently selected group or items:

get selected group

get selected items

And the standard groups:

get all items group

get recents group

get favorite items group

get top level folder 

get deleted items folder

get unfiled group

get no label group

Along with some useful things:

get default import destination

get untagged items

And collections of items:

get every bundle

get every tag

get every folder

get every saved search

get every label

get every Keep It item

Being flat lists, almost none of those things are guaranteed to have a unique name. For folders, you can safely assume that a child folder of a particular folder has a unique name, and you could fetch that by walking the path. For example, if you have a folder at the top level called “Folder”, and it has a child folder called “Subfolder”:

get folder "Subfolder" of folder "Folder" of top level folder

…but there is no guarantee that a bundle in a folder, or a Keep It item in a folder or bundle will have a unique name. If that is an issue, and your script is only targeting your own library and not other people’s, then get the folder, bundle or Keep It item is by its identifier.

When using identifiers it doesn’t matter where something is located, or what its name is. To get a group’s identifier:

You can then use the identifier as follows:

get folder id "E770E3C5-5958-4FB5-BE75-59DCF075DC94"

For Keep It items hold on the Option key and choose Item > Copy Item Identifier from the menu, and the you can get the item like this:

get Keep It item id "52F2513B-6EF1-4AA9-8E5C-6EBC65E36D79"

Tags always have a unique name in Keep It, and so it is possible to do this:

get tag "tag name"

In most cases, Keep It lets you use tags and tag names interchangeably.

Creating, Moving and Removing

It’s possible to create folders and bundles with the standard “make” command. A location must be specified, along with a name:

make new bundle in top level folder with properties {name:"New Bundle Name"}

And it’s possible to move folders, bundles, saved searches and Keep It items with the standard “move” command:

move theBundle to theFolder

You can delete a bundle no matter where it’s stored with the standard “delete” command:

delete theBundle

…but folders and Keep It items need to be in Deleted Items first:

move theFolder to deleted items folder

delete theFolder

Keep It items can be in many bundles, so there is a special command for that:

add items selected items to theBundle

And a corresponding command to remove them:

remove items selected items from theBundle

Tags cannot be created with a “make” command. Instead, you create tags by applying them to items. Tags are the only thing in Keep It that can be uniquely identified by name, therefore Keep It allows you to use the name of a tag for convenience in many places:

add tags {"tag 1", "tag 2", "tag 3"} to selected items

remove tags {"tag 1", "tag 2", "tag 3"} from selected items


Adding Files

Keep It is a sandboxed app, which means you can’t pass it file paths as text such as this, because it won’t have permission to access the files:

set theFile to "/Users/account/Desktop/Document.pdf"

Instead, you either need to create a POSIX file path, like this:

set theFile to POSIX file "/Users/account/Desktop/Document.pdf"

…or an alias, using a colon-separated path like this:

set theFile to alias "Macintosh HD:Users:account:Desktop:Document.pdf"

You can also use folder actions, the “choose file” dialog, drag and drop a file onto an AppleScript app, and so on.

To add files using your default settings:

add files theFiles

Or include options to specify how to add the files, where to store them, tags to add, and whether or not to convert text files to notes:

set targetFolder to folder "Inbox" of top level folder

add files theFiles by copying to targetFolder with tags {"tag 1", "tag 2", "tag 3"} without converting text files


Adding Links

To add a link using your default settings:

add link "http://reinventedsoftware.com/keepit/"

Or include options that specify where to store the web link, its name, whether or not save it for offline and in which format, along with any tags to add:

add link "http://reinventedsoftware.com/keepit/" with name "Keep It by Reinvented Software" to targetFolder as web archive with tags {"tag 1", "tag 2", "tag3"} with save for offline


Adding Text and Attachments

To add a note with some text:

add text "The text to save"

Or add options to specify the format, destination for the new file, tags and name:

add text "The Markdown text to save" as plain text file in targetFolder with tags {"tag 1", "tag 2", "tag 3"} with name "Markdown Text File.md"

To append text to a specific item:

add text "The quick brown fox" to item theItem

And to add an attachment:

attach file theFile to theItem


Exporting

Keep It can either export an individual Keep It item, or a group. The item or group’s filename will be made unique in the destination. Keep It will prompt to decrypt encrypted items, and notes will be exported as rich text files, either with or without attachments. See “Adding Files” above for important information about how to specify files when working with Keep It.

To export an individual Keep It item to a folder chosen by the user:

set destinationFolder to choose folder

export theItem to destinationFolder

The exported file will be returned once the export is complete.

To export a group:

export theGroup to destinationFolder

For groups, the exported folder will be returned immediately, but the export operation will continue in the background.

When exporting "All Items" the top level folder will actually be exported, and so the folder hierarchy will be preserved.