Automation

Mudlark accepts inbound mudlark:// URLs from any app on the system. Use them to script note creation, retrieval, search, export, and CRUD from Apple Shortcuts, Raycast, AppleScript (open location), curl, browser bookmarks, or any other tool that can open a URL. The same surface is also exposed as App Intents, so pick whichever fits your tool. URL scheme is best for callback-driven flows (chained x-callback-url exports between apps, scripted pipelines that need to read results). App Intents are best for Shortcuts authoring.

Allow automation from other apps

Inbound URLs are gated by a setting in Settings › General. Read-only actions (open, get, list, search) always pass through, so cross-app discovery links keep working. Mutating actions (create, add-text, update, delete, move, export) are blocked with an x-error callback when the toggle is off. Default is off, so a fresh install never executes mutations from another app until you opt in.

Resolving notes

Actions that act on an existing note accept a name parameter. name is the note’s vault path: subfolder plus title, no extension, with / as separator. For a root-level note titled Inbox, name=Inbox. For Projects/Q1/Plan.mudlark, name=Projects/Q1/Plan. Identity follows the filename, so renaming the file in Finder breaks links. If name doesn’t resolve a row, the action errors with errorMessage="Note not found".

The pre-2026 shape carried uuid, id, and title alternates. Those still parse so a stale Shortcut won’t fail URL parsing, but they’re ignored and the action falls through to Note not found. Saved Shortcuts using the old shape need to be re-recorded against name=.

Actions

Each action is a path in the URL. Parameters are passed as query string values. All text values should be percent-encoded. Both mudlark://action?… and mudlark://x-callback-url/action?… are accepted.

`/create`

Make a new note.

Parameter	Type	Default	Notes
title	string	Untitled	Note title.
text	string	empty	Body content.
type	string	none	Wraps text with the given type’s prefix. See type aliases below.
clipboard	yes \| no	no	Use clipboard contents as text (overrides text=).
open	yes \| no	yes	Bring Mudlark to the foreground.
active-note	yes \| no	mirrors open	Select the new note in the active editor. Set open=no&active-note=yes to populate without focus-stealing.

Returns on x-success: name, title

mudlark://create?title=Tasks&text=Buy%20milk&type=task&open=no

`/open`

Resolve a note and activate it in the editor.

Parameter	Type	Default	Notes
name*	string	required	Vault path. See Resolving notes above.

Returns on x-success: name, title

mudlark://open?name=Daily%20Log

`/add-text`

Append or prepend text to a note. If no note is specified, falls back to the configured Quick Capture target, then the current editor note.

Parameter	Type	Default	Notes
name	string	-	Optional vault path. If omitted, see fallback above.
text*	string	required	Required (or clipboard=yes).
clipboard	yes \| no	no	Use clipboard contents as text.
mode	append \| prepend	append	Insertion mode.
type	string	none	See type aliases below.

Returns on x-success: name, title

When the target is the active editor note and mode=append, the insertion is editor-aware (preserves cursor, integrates with Quick Capture).

mudlark://add-text?name=Inbox&text=Look%20into%20this&type=task

`/get`

Read a note’s content.

Parameter	Type	Default	Notes
name*	string	required	Vault path. See Resolving notes above.
format	raw \| markdown \| html	raw	raw returns the literal Mudlark markup, while markdown and html render via the automation renderer.

Returns on x-success: name, title, createdAt (ISO-8601), updatedAt, text

mudlark://get?name=Today&format=markdown&x-success=myapp://callback

`/list`

List notes, optionally filtered, paginated.

Parameter	Type	Default	Notes
query	string	none	Title substring (case-insensitive).
limit	int	100	Clamped to [1, 500].
offset	int	0	Skip this many results.

Returns on x-success: notes (JSON array of {name, title, createdAt, updatedAt}), total, offset, hasMore

mudlark://list?query=project&limit=25&offset=0

`/search`

Open the note browser with a query pre-filled. Activates the app.

Parameter	Type	Default	Notes
query	string	empty	Search query.

Returns on x-success: nothing meaningful (no callback params)

mudlark://search?query=deadline

`/export`

Trigger configured exports for a note. Without destination=, runs every destination configured in Settings. With destination=, filters to the matching one(s).

Parameter	Type	Default	Notes
name	string	-	Optional vault path. If omitted, exports the active note.
destination	string	none	Matches presetId (bear, obsidian, notion, …) or the destination’s display name, case-insensitive.

Returns on x-success: name, title of the exported note

If destination= is provided but matches no configured destination, the action errors with errorMessage="No configured export destination matches ‘<value>’".

mudlark://export?name=Inbox&destination=bear

`/update`

Rename a note and/or replace its body. At least one of new-title or text must be provided. Renames the vault file on disk if the title changes.

Parameter	Type	Default	Notes
name*	string	required	Vault path. See Resolving notes above.
new-title	string	none	New note title (newTitle is also accepted).
text	string	none	New body content.

Returns on x-success: name, title (post-update)

mudlark://update?name=Daily%20Log&new-title=2026%20Plan

`/delete`

Move the note to Mudlark’s trash. Recoverable from the Trash section for 30 days (matches ⌘ ⇧ Backspace in the editor).

Parameter	Type	Default	Notes
name*	string	required	Vault path. See Resolving notes above.

Returns on x-success: name, title of the deleted note

mudlark://delete?name=Inbox

`/move`

Move a note to a different vault subfolder. Empty or missing folder moves the note to the vault root.

Parameter	Type	Default	Notes
name*	string	required	Vault path. See Resolving notes above.
folder	string	empty (root)	Vault-relative path.

Returns on x-success: name, title

mudlark://move?name=Inbox&folder=Archive/2026

Type aliases

The type= parameter on create and add-text accepts the values below. Unknown values pass through as-is, with no prefix added.

Pass	Resolves to
task, completion, removal, heading, bullet, numbered, code, math, timer, loopingTimer, table, highlight, question, quotation, callout	the named item type
image, media	media (@)
hardBreak, horizontalRule, horizontal-rule, hr	horizontal rule (~)
loop-timer, looping-timer, loopingtimer	looping timer (;)
writeto, write-to	write-to (.)
plain, plain-text, text	plain text (no prefix)

Multi-line wrapping

When text= contains newlines, wrapping depends on the type:

Per-line types (task, completion, bullet, numbered, highlight, question, quotation, heading) prefix every non-empty line. text=A%0AB&type=task becomes + A\n+ B.
Block types (code, math) wrap the body with paired delimiters: <prefix>\n<body>\n<prefix>.

Single-line text always renders as <prefix> <text> regardless of style.

x-callback-url

Mudlark supports the x-callback-url convention. Add these parameters to any action to control what happens after it completes:

Parameter	Description
x-success	URL opened on success. Result params (e.g. `name`, `title`) are appended as query items.
x-error	URL opened on failure. Receives `errorCode=-1` and `errorMessage=<string>` query items.
x-cancel	URL opened if the user cancels.

mudlark://create?title=Log&x-success=shortcuts://

This creates a note called “Log” and returns to Shortcuts when done.

Callback URLs are sanitized for safety. file:, javascript:, data:, vbscript:, about:, blob: schemes are dropped silently. https:, http:, and custom app schemes (bear://, myapp://) pass through.

Using from the terminal

Use the open command to trigger actions from a shell script:

open "mudlark://add-text?text=Hello%20world"