# Obsidian URI Scheme Reference The `obsidian://` URI protocol enables deep linking and cross-app automation. ## URI Format ``` obsidian://action?param1=value1¶m2=value2 ``` ## Encoding Rules | Character | Encoding | |---|---| | Space | `%20` | | `/` | `%2F` | | `&` | `%26` | | `=` | `%3D` | | `?` | `%3F` | | `#` | `%23` | | `\n` | `%0A` | | `"` | `%22` | **Always encode parameter values.** Use Python's `urllib.parse.quote()` or equivalent. --- ## Core Actions ### 1. Open Vault or File **Open vault by name:** ``` obsidian://open?vault=My%20Vault ``` **Open vault by ID:** ``` obsidian://open?vault=ef6ca3e3b524d22f ``` **Open specific file:** ``` obsidian://open?vault=My%20Vault&file=My%20Note ``` **Open file by absolute path:** ``` obsidian://open?path=%2Fhome%2Fuser%2FMy%20Vault%2Fpath%2Fto%2FMy%20Note ``` **Open file with heading anchor:** ``` obsidian://open?vault=MyVault&file=My%20Note%23Section%20Title ``` **Open file with block anchor:** ``` obsidian://open?vault=MyVault&file=My%20Note%23%5Eblock-id ``` ### Parameters for `open` | Parameter | Description | |---|---| | `vault` | Vault name or ID | | `file` | Relative file path (without .md extension) | | `path` | Absolute file path | | `new-window` | Open in new window (true/false) | --- ### 2. Create or Append to Note **Create new note:** ``` obsidian://new?vault=MyVault&name=Idea&content=Hello%20world ``` **Append to existing note:** ``` obsidian://new?vault=MyVault&name=Ideas&content=%0ANew%20idea&append=true ``` **Overwrite existing note:** ``` obsidian://new?vault=MyVault&name=Draft&content=New%20content&overwrite=true ``` ### Parameters for `new` | Parameter | Description | |---|---| | `vault` | Vault name | | `name` | Note name (creates if missing) | | `content` | Content to insert | | `append` | Append instead of overwrite (true/false) | | `overwrite` | Overwrite existing content (true/false) | | `silent` | Don't open the note after creation (true/false) | --- ### 3. Open Daily Note ``` obsidian://daily?vault=MyVault ``` **With content appended:** ``` obsidian://daily?vault=MyVault&content=Morning%20reflection%3A%20...&append=true ``` --- ### 4. Create Unique Note (Zettelkasten) ``` obsidian://unique?vault=MyVault ``` **With template:** ``` obsidian://unique?vault=MyVault&template=Zettel ``` --- ### 5. Open Search ``` obsidian://search?vault=MyVault&query=meeting%20notes ``` ### Parameters for `search` | Parameter | Description | |---|---| | `vault` | Vault name | | `query` | Search query string | --- ### 6. Open Vault Manager ``` obsidian://choose-vault ``` --- ## Advanced URI Plugin Actions If the Advanced URI plugin is installed, additional actions are available: ### Execute Command ``` obsidian://advanced-uri?commandid=app%3Aopen-settings ``` **Get command ID:** ``` # In Obsidian: Settings -> Hotkeys -> gear icon -> Copy command ID ``` ### Open File with Data Insertion ``` obsidian://advanced-uri?filepath=My%20Note&data=Hello&mode=append ``` **Modes:** | Mode | Effect | |---|---| | `append` | Append to end | | `prepend` | Prepend to beginning | | `overwrite` | Replace entire content | | `new` | Only if file doesn't exist | ### Search and Open First Result ``` obsidian://advanced-uri?search=keyword ``` ### Open Workspace ``` obsidian://advanced-uri?workspace=My%20Workspace ``` ### Evaluate JavaScript ``` obsidian://advanced-uri?eval=app.workspace.activeLeaf.view.sourceMode ``` ### Navigation ``` obsidian://advanced-uri?navigation=back obsidian://advanced-uri?navigation=forward ``` ### Daily Note Operations ``` obsidian://advanced-uri?daily=true&data=content&mode=append obsidian://advanced-uri?daily=true&filepath=YYYY-MM-DD ``` ### File Operations ``` # Move file obsidian://advanced-uri?filepath=Old&filepathmove=New # Rename file obsidian://advanced-uri?filepath=Old&rename=New # Delete file obsidian://advanced-uri?filepath=Note&delete=true ``` --- ## Platform-Specific Invocation ### Linux (xdg-open) ```bash # Basic open xdg-open "obsidian://open?vault=MyVault&file=Note" # With encoding xdg-open "obsidian://new?name=Idea&content=$(python3 -c "import urllib.parse; print(urllib.parse.quote('Hello world'))")" ``` ### macOS ```bash # Basic open open "obsidian://open?vault=MyVault&file=Note" # From AppleScript osascript -e 'open location "obsidian://daily?vault=MyVault"' ``` ### Windows ```powershell # PowerShell Start-Process "obsidian://open?vault=MyVault&file=Note" # CMD start obsidian://open?vault=MyVault&file=Note ``` ### From Python ```python import urllib.parse import subprocess def build_obsidian_uri(action, **params): query = "&".join(f"{k}={urllib.parse.quote(str(v))}" for k, v in params.items()) return f"obsidian://{action}?{query}" # Open note uri = build_obsidian_uri("open", vault="My Vault", file="My Note") print(uri) # -> obsidian://open?vault=My%20Vault&file=My%20Note # Create note uri = build_obsidian_uri("new", vault="MyVault", name="Idea", content="Hello world") subprocess.run(["xdg-open", uri]) # Linux # subprocess.run(["open", uri]) # macOS ``` ### From JavaScript/Node.js ```javascript const { exec } = require('child_process'); function buildObsidianUri(action, params) { const query = Object.entries(params) .map(([k, v]) => `${k}=${encodeURIComponent(v)}`) .join('&'); return `obsidian://${action}?${query}`; } const uri = buildObsidianUri('open', { vault: 'My Vault', file: 'My Note' }); exec(`xdg-open "${uri}"`); // Linux ``` --- ## URI in Web Browsers When `obsidian://` links are clicked in a browser: - **Registered handler**: Obsidian opens with the action - **Not registered**: Browser may show "Open with Obsidian?" prompt or error **Force open in new window:** ```html Open in Obsidian ``` --- ## URI in Alfred/Raycast Alfred workflows and Raycast extensions commonly use these URIs: ``` # Alfred "search Obsidian vault" workflow obsidian://search?vault={vault}&query={query} # Raycast "create quick note" obsidian://new?vault={vault}&name={title}&content={text} ``` --- ## Common URI Recipes ### Quick Capture (Append to Inbox) ``` obsidian://new?vault=PKM&name=Inbox&content=%0A- %s&append=true ``` ### Meeting Note from Calendar ``` obsidian://new?vault=Work&name=Meeting%20-%20Client%20Sync&content=##%20Attendees%0A%0A##%20Agenda%0A%0A##%20Notes%0A&folder=Meetings/ ``` ### Daily Journal Entry ``` obsidian://daily?vault=Journal&content=%0A##%20Morning%0A%0A##%20Afternoon%0A%0A##%20Evening%0A&append=true ``` ### Open Project Dashboard ``` obsidian://open?vault=Work&file=Projects%2FDashboard ``` ### Search for Tag ``` obsidian://search?vault=PKM&query=tag%3A%23review ``` --- *All actions require Obsidian to be installed and the vault to exist. The Advanced URI plugin actions require that plugin to be installed.*