# 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](cli.md), 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](search.md).

Examples:

```text
#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.

`section_path` and `organizer_path` are separate absolute, title-based paths. Both begin with `/` and include their final component. `section_path` ends with the current or containing section, including in single-section projects; `organizer_path` is rooted within that section and ends with the Organizer item or, for a figure, its containing idea space. Keep the fields separate because concatenating them loses the boundary between the section and Organizer hierarchies.

!!! 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

## Navigating to Results

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.

### Piping a Link Into Navigate in Shortcuts

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`
1. Add `Get Item from List`
1. In the `Get Item from List` action, click the input variable and choose the `Link` field from the `Find Items` result
1. Add `Navigate`
1. Right-click inside the `Navigate` action's `Link` field
1. Choose `Select Variable` or `Insert Variable`
1. 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`
1. Use `Get Item from List` to pick one result and set that action to return the item's `Link`
1. 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
1. Run `Export Selected Figures`
1. Save or share the returned file

### Capture a File Into Curio

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

### Build a Query-Driven Report

1. Run `Find Items`
1. Repeat over the returned items
1. Pull fields such as `Title`, `Tags`, `Due Date`, `Organizer Path`, or `Asset File`
1. 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](cli.md) 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

- [Curio CLI](cli.md)
- [Search and Quick Find](search.md)
- [Sharing](sharing.md)
- [Projects](projects.md)