GoodLinks CLI

The GoodLinks CLI lets you read and update your GoodLinks library from Terminal or AI assistants. GoodLinks needs to be running with API access turned on in Settings > API.

Use the Command-Line Tool

The CLI is bundled inside the GoodLinks app. You can run it from anywhere by using its full path inside the app bundle:

/Applications/GoodLinks.app/Contents/MacOS/CLI/goodlinks -h

If GoodLinks is installed somewhere else, replace /Applications/GoodLinks.app with the actual app path.

To avoid typing the full path each time, you can create a symlink at /usr/local/bin/goodlinks that points to the CLI:

sudo mkdir -p /usr/local/bin && sudo ln -sfh "/path/to/GoodLinks.app/Contents/MacOS/CLI/goodlinks" "/usr/local/bin/goodlinks"

After creating the symlink, check that Terminal can find it:

goodlinks -h

What It Supports

The CLI is organized into command groups:

• goodlinks link retrieves, searches, adds, edits, and deletes links.
• goodlinks list retrieves the visible lists in your library.
• goodlinks tag retrieves tags.
• goodlinks highlight searches, edits, and exports highlights.

Run goodlinks -h to see all top-level commands, or add -h after any command group to see its options:

goodlinks link -h
goodlinks highlight -h

Links

Use goodlinks link add to save a new link, or update an existing link with the same URL:

goodlinks link add "https://example.com/article" --tag reading --starred

Use goodlinks link list to retrieve links from a main list. Supported list names are unread, read, starred, untagged, highlighted, and all.

goodlinks link list unread --limit 10
goodlinks link list starred --include-read

Use goodlinks link search for full-library search and filtering. It can search titles, summaries, content, URLs, and author names.

goodlinks link search --q "swift" --tag programming --highlighted

You can also retrieve a single link by ID or URL, get the currently selected link in GoodLinks, export article content, edit metadata, or move links to trash:

goodlinks link id LINK_ID
goodlinks link url "https://example.com/article"
goodlinks link current
goodlinks link content LINK_ID --format markdown
goodlinks link edit LINK_ID --read --add-tag archived
goodlinks link delete LINK_ID

Deleted links are moved to trash and can be recovered in GoodLinks.

Highlights

Use goodlinks highlight search to find highlights across your library. It supports text search, filtering by link ID, content, note, creation date, sorting, and pagination.

goodlinks highlight search --q "important" --limit 20
goodlinks highlight search --link-id LINK_ID

Use goodlinks highlight edit to update a highlight note:

goodlinks highlight edit HIGHLIGHT_ID --note "Follow up on this section"

Use goodlinks highlight export to export highlights from a link using the export format template configured in GoodLinks settings:

goodlinks highlight export LINK_ID

Lists and Tags

Use goodlinks list to retrieve the visible lists in your GoodLinks library:

goodlinks list

Use goodlinks tag to retrieve tags:

goodlinks tag