Automating Traverse with Shortcuts and URLs

Traverse can be automated from macOS Shortcuts and from traverse:// URLs. Use these options to create outlines from text, Markdown, or OPML, add nodes to existing outlines, read the current selection, find nodes, update node text, notes, and attributes, or open a specific outline or node.

Automation surfaces

Traverse supports two related automation surfaces:

Shortcuts actions, available in the Shortcuts app through Traverse App Intents (Traverse Pro required).
URL actions, using the traverse://x-callback-url/... scheme.

Shortcuts are usually easier when building local workflows. URL actions are useful for launchers, scripts, callback-driven apps, and integrations that already understand x-callback-url.

Shortcut actions

Create Outline: creates a new outline from supplied content.
Append to Outline: appends text, Markdown, or OPML to an existing outline without applying attributes to the first appended node.
Add Node: adds one node, or parses supplied outline content into multiple nodes, and can apply a note and attributes to the first new node.
Get Current Node: returns the currently selected node from Traverse.
Get Node: returns a specific node by node ID or Traverse node link.
Get Node Attributes: returns a node's attributes as JSON.
Find Nodes: returns matching nodes by text, parent node, and/or attributes.
Find Node: returns the first matching node.
Update Node: changes node text, note, and/or attributes.
Open Outline: opens an outline in Traverse.
Open Node: opens a specific node in Traverse.

Content formats

Create, append, and parsed add-node operations accept these formats:

plainText: imports indented plain text as an outline.
markdown: imports Markdown into Traverse nodes.
opml: imports OPML directly.

If parsing fails, Traverse falls back to creating a simple outline with the supplied content as a child node. Empty content is rejected.

Node references

Actions that target a node accept either a raw node UUID or a Traverse node link. A node link has this shape:

traverse://open?document=DOCUMENT-UUID&node=NODE-UUID

URL actions also accept the node link through nodeLink or url parameters where supported.

URL actions

All URL actions use the traverse://x-callback-url host. Query parameters should be URL encoded.

Get the current node

traverse://x-callback-url/getCurrentNode?x-success=CALLBACK-URL

On success, Traverse calls x-success with title, text, note, url, node, document, and file when available.

Create an outline

traverse://x-callback-url/createOutline?title=TITLE&content=CONTENT&format=plainText

Required: title. Content may be supplied as content or text. Optional: format.

Append to an outline

traverse://x-callback-url/append?document=DOCUMENT-UUID&content=CONTENT&format=markdown

Target an outline with document or file. If no target is supplied, Traverse uses the selected outline. Optional node appends the parsed content under that parent node. Use append when you only need to add content; it does not apply a note or attributes to the first new node.

Add a node

traverse://x-callback-url/addNode?document=DOCUMENT-UUID&text=TEXT&note=NOTE&attributes=ATTRIBUTES

Use parent or node to add beneath an existing node. The default mode is singleNode. Use mode=parseOutline with format=plainText, markdown, or opml to parse the supplied text into multiple nodes. The supplied note and attributes are applied to the first new node; this is the main difference from append.

Get a node

traverse://x-callback-url/getNode?document=DOCUMENT-UUID&node=NODE-UUID&x-success=CALLBACK-URL

On success, Traverse returns title, text, note, document, file, node, and url.

Get node attributes

traverse://x-callback-url/getNodeAttributes?document=DOCUMENT-UUID&node=NODE-UUID&x-success=CALLBACK-URL

On success, Traverse returns an attributes parameter containing JSON.

Update a node

traverse://x-callback-url/updateNode?document=DOCUMENT-UUID&node=NODE-UUID&text=TEXT&note=NOTE&appendNote=true

Supply any of text, note, and attributes. If appendNote=true, the supplied note is appended to the existing note instead of replacing it.

Success and error callbacks

Most URL actions support x-success and x-error. When x-success is omitted for create, append, add, get, and update actions, Traverse opens the resulting node when it can. When an error occurs and x-error is supplied, Traverse calls it with errorCode and errorMessage. Without an error callback, Traverse beeps.

Attributes payloads

Actions that accept attributes can receive either JSON or line-based key/value text. Add Node applies the payload to the first new node. Update Node applies it to the targeted existing node.

{"task": true, "mark": "blue", "type": "Heading", "url": "https://example.com"}

task: done
mark: green
status: Waiting
due: 2026-10-01

Attribute names may match either the stored key or the visible label, as long as the match is unambiguous. Values are validated against the attribute type before being applied.

Built-in attribute names and values

Task: accepts true, yes, 1, on, checked, done, complete, or completed; and false, no, 0, off, unchecked, todo, or open.
Mark: accepts none, clear, or the mark names red, orange, yellow, green, blue, and purple. Numbers 0 through 6 are also accepted.
Type: accepts editable Traverse Type values by raw value or display name.
Fountain: accepts editable Fountain element values by raw value or display name.
URL: requires an absolute URL with a scheme.

Custom attributes are validated according to their configured type. Dates accept Traverse date values or ISO 8601 dates. Lookup values must match existing lookup options when the attribute defines a fixed list.

Opening links directly

Use traverse://open links to open a saved outline or node:

traverse://open?document=DOCUMENT-UUID
traverse://open?document=DOCUMENT-UUID&node=NODE-UUID

The selected node link can be copied from Traverse with Option-Command-C.