Links and other apps

Every note, canvas and chat in Canto has its own link, such as canto://note/3f2a…. Paste it into a calendar event, a to-do in another app, Hookmark or another note, and a click on it brings you straight back to that note in Canto. Links are free on every plan.

A link holds nothing but an id: no text, no key, no permission. It opens only on a Mac that has your vault, so sharing a link shares nothing.

Copy a link#

With a note, canvas or chat in front:

• Edit › Copy Link (⇧⌘C) copies its link. In apps that take a rich link, such as Mail, Notes or a calendar, it pastes as the note's title, linked. In a plain text field, such as Terminal, it pastes as the address.
• Edit › Copy Markdown Link (⌥⇧⌘C) copies [Title](canto://note/…) for apps that write Markdown.

You'll find the same in more places:

• the note's Share menu: Copy link and Copy Markdown link,
• the menus in the sidebar, in Pinned and in All notes: Copy link,
• ⌘K: Copy link to this note and Copy Markdown link to this note (or canvas, or chat),
• a canvas's ✨ menu, a chat's ⋯ and its menu in the sidebar: Copy link.

Canto says Link copied: "Opens this note in Canto on Macs with this vault."

Paste a note's link into another Canto note and it becomes a link to that note.

What a link holds#

A canto:// link names one note, canvas or chat by its id:

The id never changes, so a link keeps working after you rename the note or move it to another folder. It works on every Mac that has your vault, your other Macs too when iCloud sync is on. A note in the Trash still opens.

A link doesn't open its note:

• after the note was deleted for good,
• in another vault (a Markdown export imported into another vault makes new notes with new ids),
• on another Mac before sync has brought the note there.

Canto then says This link's note isn't here: "It may be in another vault, deleted for good, or not on this Mac yet."

A published page's link is a different thing. Publishing puts a copy of the note on the web at an https:// address that anyone who has it can read. A canto:// link is a pointer into your own vault, useless to anyone else. A published note's Share menu has both: Copy public link and Copy link. See Publishing a page.

Open a link#

Click a canto:// link anywhere on your Mac and Canto shows what it names, even with Canto's window closed or minimized: Canto opens the window and brings it to the front. If Canto isn't running, macOS starts it first.

Links other apps can call#

Apps that drive other apps, such as Hookmark, Shortcuts, Raycast and Alfred, can call Canto with an x-callback-url link:

canto://x-callback-url/<action>?<parameters>

Percent-encode the values. Canto reads + as a plus sign, so send a space as %20. For example, canto://x-callback-url/open?title=Trip%20to%20Kyoto opens the note called Trip to Kyoto.

For get-current, url is the canto://note/<id> link (or canvas or chat) and markdown is [title](url).

Capture. canto://x-callback-url/capture?title=Call%20Ana&text=Ask%20about%20the%20budget opens Quick capture with the title and text filled in, below anything you had already typed there, and says it was filled in by a link from another app. Nothing is saved until you press ↩ in it. The link itself writes nothing.

Callbacks#

Only get-current and hook-get-address answer, because only they return something. open, search, open-tag, open-folder and capture never call back, not even for an app you always allow, so leave x-success, x-error and x-cancel off them. If a link to one of them names a note that isn't here, Canto says so on your screen only, so a link can't test which notes you have.

For get-current and hook-get-address:

• x-success: where Canto sends the answer, with title, url and markdown added. Without it there is nothing to answer.
• x-error: where Canto sends a refusal, with errorCode and errorMessage added.
• x-cancel: accepted and checked like the others. Canto doesn't call it in beta 10.
• x-source: your app's name. Canto doesn't rely on it: the app it answers is the one macOS opens the callback with.

Callbacks never go to the web. Canto refuses a callback that is a web address or could open one: http, https, file, javascript, data, blob, about, mailto, a browser's own scheme, or canto itself. A callback must be another app's own scheme (such as hook://…), on one line and at most 2,000 characters. x-error and x-cancel go only to the same app as x-success. A link with a callback Canto refuses is ignored, unanswered.

Shortcuts' own answers only. For Shortcuts, Canto opens only the answers its Open X-Callback URL action supplies (shortcuts://x-callback-url/ic-success, ic-error and ic-cancel). A custom X-Success URL that runs another shortcut or imports one is refused.

Only apps you allowed hear back. Canto answers only an app you allowed, always or for this one question. For any other app, or after Don't allow, nothing goes back, not even an error.

Errors. An allowed app's x-error gets one of these as errorCode, with a sentence saying the same as errorMessage, such as "No note, canvas or chat is open in Canto."

Limits. A title is at most 300 characters, captured text 20,000 and a search 500. Canto asks about one get-current at a time and takes at most ten a minute from one app; a question nobody answers goes away after two minutes. While Canto opens its window, at most five links wait; more are dropped.

When an app asks for the open note#

The first time an app asks for the open note with get-current or hook-get-address, Canto asks you. The sheet says, for example, "Hookmark wants the link to “Trip to Kyoto”" and "It gets the note's title and its canto:// link. It doesn't get the note's text." Then:

• Always allow (↩) answers now and every time after, without asking. The app is listed in Settings.
• Allow once answers this time. Canto asks again next time.
• Don't allow (Esc) sends nothing back, not even an error.

The sheet names the app, with its icon, as macOS knows it: the app that will receive the answer, never the name the link gives itself. With Home or another place in front, nothing is asked and nothing is sent.

Settings › Connections › Links from other apps holds the rest:

• Open notes from links: always on. canto:// links open notes, chats and canvases.
• Let apps ask for the open note's link: on unless you turn it off. Off, no app can ask Canto which note is open, and an allowed app gets turned-off.
• Apps you allowed: every app you always allow, each with Remove. After Remove, Canto asks that app again.
• Link formats for other apps: Guide opens this page.

Nothing destructive happens from a link#

A link can open things, search, and fill in Quick capture. It can't:

• delete, move, rename or change a note, a folder or a tag,
• change a setting or turn on sync,
• run a model or a web search,
• save anything without your press.

The only action that adds anything is capture, and it waits for you to save in Quick capture. Only a title and a link ever go back to another app, never a note's text, tags, folders or a list of notes. No action returns search results.

Hookmark#

Hookmark links any item to a Canto note. It asks two things of an app, and Canto has both:

• Get Address: with Canto's integration, Hookmark asks Canto for the open note with hook-get-address (the same as get-current) and gets its title and link. The first time, Canto asks you; allow it once, or choose Always allow so it doesn't ask every time.
• Open Item needs nothing from Canto: Hookmark hands the canto:// link to macOS, which opens the note in Canto.

Edit › Copy Markdown Link copies the same title and link by hand.

Shortcuts, Raycast and Alfred#

They need nothing from Canto beyond the links on this page:

• Shortcuts: an Open URLs action opens any canto:// link, and the shortcut goes on by itself. To capture a shortcut's text, put it through URL Encode, then open canto://x-callback-url/capture?text= followed by the encoded text. To bring the open note's link into a shortcut, use Open X-Callback URL with canto://x-callback-url/get-current; Shortcuts adds its own answer addresses, and Canto asks you the first time.
• Raycast: a Quicklink with the link canto://x-callback-url/search?query={Query} searches Canto from Raycast.
• Alfred: a custom search, or a workflow's Open URL, with canto://x-callback-url/search?query={query}. Have Alfred encode spaces as %20, not +.

Only get-current needs an answer, so only it asks you anything.

Keys for any menu command#

Settings › Keyboard changes Canto's own shortcuts (see Keyboard shortcuts), and it won't take keys a menu command already has: it tells you which, such as "⇧⌘G is Vault Graph." For any command in Canto's menu bar, macOS can add keys of your own. For example, ⌘G for Vault Graph:

1. Open System Settings › Keyboard and click Keyboard Shortcuts….
2. Choose App Shortcuts, then press +.
3. For Application, choose Canto. For Menu title, type Vault Graph, exactly as Canto's Go menu shows it. For Keyboard shortcut, press ⌘G. Click Done.
4. If Canto was open, quit it and open it again.

⇧⌘G keeps working too. In Canto, Settings › Keyboard › Menu commands › Keys for any menu command has Open Keyboard Settings…, which opens that pane of System Settings.

A few things to know:

• It works only for commands in Canto's menu bar.
• Type the title exactly as the menu shows it. A title that ends in "…" needs three periods, such as Quick Capture.... For a command in a submenu, type the path with -> between the names.
• A key Canto's window already uses, such as ⌘K, ⌘J or ⇧⌘H, wins over an App Shortcut. Choose keys Canto doesn't use.

The same from Terminal, in one line (@ is ⌘, $ is ⇧, ~ is ⌥ and ^ is ⌃). Quit Canto and open it again afterwards.

defaults write io.lonelyduck.canto NSUserKeyEquivalents -dict-add "Vault Graph" "@g"

What leaves Canto#

Nothing leaves your Mac through a link.

• A link you copy holds only an id. Where you paste it is up to you.
• When an app asks with get-current and you allow it, Canto hands that app, on this Mac, the title and the canto:// link of what's in front. Never the note's text, tags or folder. What the app does with the title and link is up to that app.
• Without your answer on the sheet, or Always allow before, nothing goes to any app.

Settings › Memory & privacy › What leaves this Mac lists this as Other apps (links), with the same switch as Let apps ask for the open note's link. See What leaves this Mac. For apps that read your notes themselves, see Other apps (MCP).