Tauri Commands Reference

This page documents all Tauri commands available in Scratch. Commands are organized by category and invoked from the frontend using invoke() from @tauri-apps/api/core.

​

Note Management

Commands for creating, reading, updating, and deleting notes.

​

list_notes

Returns all notes in the configured notes folder. Parameters: None Returns: Notes:

• Walks the notes folder recursively (max depth 10)
• Excludes .git, .scratch, .obsidian, .trash, and assets directories
• Results are sorted: pinned notes first (by date), then unpinned notes (by date descending)
• Updates internal notes cache

---

​

read_note

Reads the full content of a note by ID. Parameters: Returns: Errors:

• "Notes folder not set" - No notes folder configured
• "Note not found" - File doesn’t exist
• "Invalid note ID: ..." - ID contains path traversal or invalid characters

---

​

save_note

Saves note content. Creates new note if id is null, or updates existing note. Handles automatic renaming when title changes. Parameters: Returns: Behavior:

• Extracts title from content (first # Heading)
• Sanitizes title to create filename
• For existing notes: renames file if title changed (preserves subfolder location)
• For new notes: creates in root folder
• Handles filename collisions with -1, -2 suffixes
• Updates search index
• Deletes old file after successful write (for renames)

---

​

delete_note

Deletes a note by ID. Parameters: Returns: null on success Behavior:

• Removes file from disk
• Updates search index
• Removes from notes cache

---

​

create_note

Creates a new note with template-based name. Parameters: None Returns: Behavior:

• Uses defaultNoteName setting as template (default: "Untitled")
• Supports template tags:
  • {timestamp} - Unix timestamp
  • {date} - YYYY-MM-DD
  • {year} - YYYY
  • {month} - MM
  • {day} - DD
  • {time} - HH-MM-SS (dashes for filename safety)
  • {counter} - Auto-incrementing number
• Sanitizes filename
• Handles collisions with counter suffix
• Creates parent directories for nested templates (e.g., {year}/{month}/{day})
• Initializes content with # Title\n\n

---

​

Configuration

Commands for managing app and folder-level settings.

​

get_notes_folder

Returns the currently configured notes folder path. Parameters: None Returns:

---

​

set_notes_folder

Sets the notes folder path and initializes folder structure. Parameters: Returns: null on success Behavior:

• Normalizes path (handles file:// URIs from older versions)
• Creates folder if it doesn’t exist
• Creates assets/ subfolder for images
• Creates .scratch/ subfolder for settings
• Verifies write access
• Loads per-folder settings from .scratch/settings.json
• Updates app config in {APP_DATA}/config.json
• Adds folder to asset protocol scope (for image serving)
• Initializes and rebuilds search index

---

​

get_settings

Returns per-folder settings. Parameters: None Returns:

---

​

update_settings

Updates per-folder settings. Parameters: Returns: null on success Behavior:

• Replaces entire settings object in memory
• Saves to .scratch/settings.json in notes folder

---

​

Search

Commands for full-text search using Tantivy.

​

search_notes

Searches notes using full-text search with fallback. Parameters: Returns: Behavior:

• Uses Tantivy full-text search (searches title and content)
• Falls back to prefix query (query*) if parsing fails
• Falls back to substring search if Tantivy returns no results or errors
• Fallback: title matches score 50, content matches score 10
• Results sorted by score descending

---

​

rebuild_search_index

Rebuilds the Tantivy search index from scratch. Parameters: None Returns: null on success Behavior:

• Deletes all documents from index
• Walks notes folder and re-indexes all .md files
• Index stored in {APP_DATA}/search_index/

---

​

File Watching

Commands for monitoring external file changes.

​

start_file_watcher

Starts watching the notes folder for file changes. Parameters: None Returns: null on success Behavior:

• Uses notify crate with recursive watching
• Debounces events per file (500ms)
• Emits "file-change" events with payload:
  {
    kind: "created" | "modified" | "deleted",
    path: string,  // absolute path
    changed_ids: string[]  // array of note IDs
  }
  
• Updates search index automatically
• Cleans up debounce map (removes entries older than 5 seconds)

---

​

Git Operations

Commands for Git integration.

​

git_is_available

Checks if Git CLI is installed. Parameters: None Returns:

---

​

git_get_status

Returns Git repository status. Parameters: None Returns:

---

​

git_init_repo

Initializes a Git repository. Parameters: None Returns: null on success Runs: git init

---

​

git_commit

Stages all changes and creates a commit. Parameters: Returns: Runs: git add -A && git commit -m "message"

---

​

git_push

Pushes to remote. Parameters: None Returns: GitResult Runs: git push with timeouts (10s connect, 10s low-speed)

---

​

git_fetch

Fetches from remote. Parameters: None Returns: GitResult Runs: git fetch --quiet with timeouts

---

​

git_pull

Pulls from remote. Parameters: None Returns: GitResult Runs: git pull with pull.rebase=false and timeouts Behavior:

• Parses “Already up to date” message
• Provides user-friendly error messages for:
  • Authentication failures
  • Network issues
  • Merge conflicts
  • Diverged histories

---

​

git_add_remote

Adds ‘origin’ remote. Parameters: Returns: GitResult Runs: git remote add origin <url>

---

​

git_push_with_upstream

Pushes and sets upstream tracking. Parameters: None Returns: GitResult Runs: git push -u origin <current-branch>

---

​

AI Integration

Commands for AI-assisted editing via CLI tools.

​

ai_check_claude_cli

Checks if Claude CLI is installed. Parameters: None Returns: Notes:

• Expands PATH to include common Node.js version managers (nvm, fnm, volta, mise)
• Checks ~/.local/bin, /usr/local/bin, /opt/homebrew/bin

---

​

ai_check_codex_cli

Checks if Codex CLI is installed. Parameters: None Returns:

---

​

ai_execute_claude

Executes Claude CLI to edit a file. Parameters: Returns: Runs: claude <file_path> --dangerously-skip-permissions --print Behavior:

• Writes prompt to stdin
• 5-minute timeout
• Kills process on timeout
• Expands PATH to find CLI in Node version managers

---

​

ai_execute_codex

Executes Codex CLI to edit a file. Parameters: Returns: AiExecutionResult Runs: codex exec --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox - Behavior:

• Wraps prompt with instructions to edit only the specified file
• Same timeout and PATH expansion as Claude CLI

---

​

Utilities

Miscellaneous helper commands.

​

copy_to_clipboard

Copies text to system clipboard. Parameters: Returns: null on success

---

​

copy_image_to_assets

Copies an image file to the notes folder’s assets/ directory. Parameters: Returns: Behavior:

• Preserves original filename (sanitized)
• Handles collisions with -1, -2 suffixes
• Maintains file extension

---

​

save_clipboard_image

Saves a base64-encoded image from clipboard to assets folder. Parameters: Returns: Behavior:

• Generates filename: screenshot-<timestamp>.png
• Handles collisions with counter suffix
• Guards against empty data

---

​

open_folder_dialog

Opens a native folder picker dialog. Parameters: Returns:

---

​

open_in_file_manager

Opens a directory in the system file manager. Parameters: Returns: null on success Platform Commands:

• macOS: open <path>
• Windows: explorer <path>
• Linux: xdg-open <path>

---

​

open_url_safe

Opens a URL in the default browser (with scheme validation). Parameters: Returns: null on success Behavior:

• Only allows http://, https://, and mailto: schemes
• Rejects other schemes (e.g., file://, javascript:) for security

---

​

Preview Mode

Commands for editing standalone markdown files outside the notes folder.

​

read_file_direct

Reads a markdown file directly by path. Parameters: Returns: Security:

• Only allows .md and .markdown extensions
• Resolves symlinks to canonical path

---

​

save_file_direct

Saves content to a markdown file directly by path. Parameters: Returns: FileContent Security:

• File must already exist
• Only allows .md and .markdown extensions

---

​

import_file_to_folder

Imports a markdown file from preview mode into the notes folder. Parameters: Returns: NoteMetadata Behavior:

• Derives note ID from title (falls back to filename)
• Copies content atomically (create + write)
• Handles filename collisions
• Updates search index
• Emits "select-note" event to main window
• Focuses main window

---

​

open_file_preview

Opens a markdown file in preview mode. Parameters: Returns: null on success Behavior:

• If file is inside notes folder: selects it in main window
• Otherwise: creates a new preview window
• Preview windows use hashed labels (preview-<hash>)
• Focuses existing window if already open

---

​

preview_note_name

Previews the filename that would be generated from a template. Parameters: Returns: Notes:

• Expands template tags (see create_note for supported tags)
• Sanitizes result
• Useful for settings UI to show real-time preview

---

​

write_file

Writes raw bytes to a file path. Parameters: Returns: null on success Note: Used internally for exporting PDFs and other binary formats.