App Intents

Curio includes an App Intents integration for Apple’s Shortcuts app on macOS. This gives you a native automation surface for opening projects, finding items, reading the current selection, navigating to results, exporting content, and importing files into the current idea space.

Unlike the Curio CLI, App Intents is designed for Shortcuts, Siri, Spotlight suggestions, and other system-driven app automation. The actions are presented as user-friendly verbs and nouns instead of command-line flags and JSON.

Getting Started

Open the Shortcuts app and search for Curio in the action library. You can then add Curio actions to any shortcut just like actions from Finder, Calendar, or Notes.

In general:

  • Open Project lets you pick a .curio file using the standard file picker.
  • Find Items searches the frontmost Curio project using Curio’s full query language.
  • Selection-based actions work from Curio’s current live UI state.
  • Export actions return files directly to Shortcuts.
  • Import adds a file to the current idea space and returns the created item.

Important

Most Curio App Intents work with the running Curio app and its current UI state. If your shortcut depends on a specific project, idea space, or selection, start by opening that project in Curio.

Available Actions

Curio currently includes these Shortcuts actions:

Action What it does
Open Project Opens a .curio project using the standard system file picker.
Find Items Searches the frontmost project and returns matching items plus scripting-friendly item metadata.
Get Selected Figure Returns the single currently selected figure.
Get Selected Figures Returns all currently selected figures.
Get Current Idea Space Returns the currently active idea space.
Navigate Navigates to a curio:// deep link.
Export Selected Figures Exports the current figure selection as a file.
Export Selected Idea Spaces Exports the selected Organizer idea spaces as a file.
Import Into Current Idea Space Imports a file into the active idea space as a file, text figure, or collection.

Finding Items

Find Items takes a Curio query string and searches the current project using the same query language used by Curio’s Search and Quick Find.

Examples:

#active due soon sort:priority
meeting notes
kind=image #reference
priority>3 group:priority

The result contains:

  • a flat list of matching items
  • a dialog summary showing the count and, for grouped queries, the grouping labels
  • per-item metadata suitable for downstream Shortcuts actions

Each returned item includes helpful automation fields such as:

  • title
  • kind
  • plain_text
  • tags
  • priority
  • due_date and done_date
  • organizer_path
  • section_path
  • link
  • group

The link field is especially useful because it is a curio:// deep link that can be passed into the Navigate action.

Note

Dates in the current App Intents surface are returned as Curio date strings, not native Shortcuts date values.

Note

Grouped queries such as group:priority still return a flat list of items in the current App Intents surface, which is more compatible with the Get Item from List Shortcuts action. The grouping is exposed through each item’s group property, not as a nested list-of-groups result payload.

Working With the Current Selection

Curio includes three read actions for the current UI context:

  • Get Selected Figure
  • Get Selected Figures
  • Get Current Idea Space

These are useful when your shortcut depends on what you currently have selected in Curio rather than what a query finds.

For example:

  • export the selected figures
  • inspect the selected figure’s tags or deep link
  • grab the current idea space and navigate back to it later

The Navigate action accepts a curio:// link and jumps Curio directly to that target.

This makes it easy to build shortcuts like:

  1. Find Items
  2. choose a result
  3. pass its Link value into Navigate

You can also save those links elsewhere and use them later to jump back to a specific figure or idea space.

On macOS, Shortcuts does not always expose string parameters as obvious drag-and-drop variable targets. If you want to pass a found item’s Link into Navigate, use the field’s contextual variable picker.

For example:

  1. Add Find Items
  2. Add Get Item from List
  3. In the Get Item from List action, click the input variable and choose the Link field from the Find Items result
  4. Add Navigate
  5. Right-click inside the Navigate action’s Link field
  6. Choose Select Variable or Insert Variable
  7. Pick the Item from List output

That inserts the curio:// string returned by the previous step into Navigate.

Note

If you simply click into the Navigate field, Shortcuts may behave as though it only accepts typed text. On macOS, the correct way to bind a previous text result is often to right-click in the field and insert the variable from there.

Note

Navigate intentionally uses a required string parameter. When used by itself, Shortcuts will prompt for a link if you have not already supplied one. When used after Find Items, bind the previous Link result into that field using the contextual variable menu.

Exporting

Curio currently provides two export actions:

  • Export Selected Figures
  • Export Selected Idea Spaces

These actions return an exported file directly to Shortcuts. You can then:

  • save it with Finder actions
  • attach it to Mail
  • send it with Messages
  • upload it to cloud storage
  • hand it to another app action in the same shortcut

Supported export formats are:

  • PNG
  • JPEG
  • PDF
  • Plain Text
  • Markdown
  • Rich Text

Importing

Import Into Current Idea Space takes a file from Shortcuts and inserts it into Curio’s active idea space.

The As parameter lets you choose how the file should be interpreted:

As Behavior
File Imports the file as a normal file or asset figure.
Text Reads the file as UTF-8 text and creates a text figure.
List Parses the file as a list collection.
Mind Map Parses the file as a mind map collection.
Stack Parses the file as a stack collection.
Table Parses the file as a table collection.

For parsed imports, Curio infers the content format from the incoming filename extension where possible, such as Markdown, CSV, TSV, TaskPaper, or OPML.

The action returns the created item, which means a shortcut can immediately inspect its title, kind, link, or file-related fields.

Example Shortcuts

Find and Jump

  1. Use Find Items with a query such as #active due soon sort:priority
  2. Use Get Item from List to pick one result and set that action to return the item’s Link
  3. Right-click the Navigate action’s Link field and insert the Item from List variable

Export Current Selection

  1. Select one or more figures in Curio
  2. Run Export Selected Figures
  3. Save or share the returned file

Capture a File Into Curio

  1. Receive a file from Finder, Safari, Mail, or a Share Sheet
  2. Run Import Into Current Idea Space
  3. Choose As: File or a parsed type like List

Build a Query-Driven Report

  1. Run Find Items
  2. Repeat over the returned items
  3. Pull fields such as Title, Tags, Due Date, Organizer Path, or Asset File
  4. Build text, CSV, or another exported summary

When To Use App Intents vs the CLI

Use App Intents when:

  • you want to build a Shortcut
  • you want native Shortcuts file passing and result handling
  • you want to automate Curio using current UI state such as the live selection

Use the Curio CLI when:

  • you want scripting from Terminal
  • you want direct JSON responses
  • you need broader low-level automation control
  • you want to work directly against a .curio file in read-only mode without launching Curio

See Also