DOCSEARCHbyAlgolia
Submit Docs

NotesMD CLI

repository·main·Indexed 22 days ago

https://github.com/yakitrak/notesmd-cli

A Go-based command-line tool for managing, searching, and editing Obsidian markdown notes. It enables interaction with Obsidian vaults directly from the terminal, supporting headless environments where Obsidian is not running. Key features include vault registration, daily note management, YAML frontmatter modification, and content searching with JSON output for automation.

Tokens
7.1K
Snippets
21
Records
44
Agent score
81%

What's inside notesmd-cli

  1. Install NotesMD CLI on Mac and Linux

    main

    To install NotesMD CLI on macOS or Linux, use Homebrew. Run the following commands:

    1. Tap the yakitrak repository: brew tap yakitrak/yakitrak
    2. Install the CLI: brew install yakitrak/yakitrak/notesmd-cli
    brew tap yakitrak/yakitrak
brew install yakitrak/yakitrak/notesmd-cli

  2. Build NotesMD CLI from Source

    main

    To build the CLI from source, you must have Go 1.19 or later installed. Follow these steps:

    1. Clone the repository.
    2. Build the binary.
    3. Install it to /usr/local/bin/.
    git clone https://github.com/yakitrak/notesmd-cli.git
cd notesmd-cli
go build -o notesmd-cli .
sudo install -m 755 notesmd-cli /usr/local/bin/

  3. Migrate from obsidian-cli to notesmd-cli

    main

    If you are upgrading from obsidian-cli (v0.2.3 and earlier) to notesmd-cli (v0.3.0+), you must perform several steps to update the binary, configuration, and dependencies. The project has been renamed to avoid confusion with the Official Obsidian CLI. A key advantage of notesmd-cli is that it works without requiring Obsidian to be running.

    Summary of Changes

    • Binary name: obsidian-cli $\rightarrow$ notesmd-cli
    • Config directory: ~/.config/obsidian-cli $\rightarrow$ ~/.config/notesmd-cli
    • Go module path: github.com/Yakitrak/obsidian-cli $\rightarrow$ github.com/Yakitrak/notesmd-cli

  4. Install NotesMD CLI on Arch Linux

    main

    You can install the official binary using an AUR helper like yay:

    • To install the pre-built binary: yay -S notesmd-cli-bin
    • To build from source: yay -S notesmd-cli
    yay -S notesmd-cli-bin
# OR
yay -S notesmd-cli

  5. Migrate configuration from obsidian-cli to notesmd-cli

    main

    You can migrate your existing preferences.json settings to the new CLI using one of two methods.

    Option A: Copy the Old Config (Preserves All Settings)

    Linux/Mac:

    # Create new config directory
mkdir -p ~/.config/notesmd-cli

# Copy your old config
cp ~/.config/obsidian-cli/preferences.json ~/.config/notesmd-cli/preferences.json

    Note: If your config was in your home directory on Mac, use:

    mkdir -p ~/.notesmd-cli
cp ~/.obsidian-cli/preferences.json ~/.notesmd-cli/preferences.json

    Windows:

    # Create new config directory
New-Item -ItemType Directory -Force -Path "$env:APPDATA\notesmd-cli"

# Copy your old config
Copy-Item "$env:APPDATA\obsidian-cli\preferences.json" "$env:APPDATA\notesmd-cli\preferences.json"

    Option B: Set Your Default Vault Again (Fresh Start)

    If you only had a default vault configured, simply re-run the set command:

    notesmd-cli set-default "{vault-name}"
    notesmd-cli set-default "{vault-name}"

  6. Install notesmd-cli

    main

    Install the new notesmd-cli using your preferred package manager:

    Windows (Scoop)

    scoop bucket add scoop-yakitrak https://github.com/yakitrak/scoop-yakitrak.git
scoop install notesmd-cli

    Mac/Linux (Homebrew)

    brew tap yakitrak/yakitrak
brew install yakitrak/yakitrak/notesmd-cli

    Arch Linux (AUR)

    # Using yay
yay -S notesmd-cli-bin

# Using paru
paru -S notesmd-cli-bin
    scoop install notesmd-cli

  7. Verify notesmd-cli installation

    main

    After installation and migration, verify that the CLI is working correctly by checking the version and your default vault settings:

    # Check version
notesmd-cli --version

# Verify your default vault
notesmd-cli print-default
    notesmd-cli --version

  8. Configure the default text editor for NotesMD CLI

    main

    You can open notes in a terminal or GUI editor instead of the Obsidian application using the --editor (or -e) flag. This flag is supported by the open, daily, search, search-content, create, and move commands.

    The CLI determines the editor from the EDITOR environment variable. If not set, it defaults to vim. For GUI editors like VSCode (code) or Sublime Text (subl), the CLI automatically adds the --wait flag to ensure the command blocks until you close the file.

    To make an editor the default for all commands that support --open, set the default open type to editor using set-default-vault --open-type editor.

    # Set your preferred editor
export EDITOR="code"

# Use with supported commands
notesmd-cli open "note.md" --editor
notesmd-cli daily --editor
notesmd-cli search --editor
notesmd-cli search-content "term" --editor
notesmd-cli create "note.md" --open --editor
notesmd-cli move "old.md" "new.md" --open --editor

# Set as default to avoid passing --editor every time
notesmd-cli set-default-vault --open-type editor

  9. Configure Vaults in Headless Environments

    main

    In headless environments (servers, containers, or systems without Obsidian installed), you must manually register your vaults using the CLI, as Obsidian cannot automatically detect them.

    Registering and Setting a Default Vault

    Use add-vault to register a directory. You can use the --set-default flag to register and set it as the default in one step.

    # Register a vault
notesmd-cli add-vault /home/user/vaults/my-brain

# Set a specific vault as default
notesmd-cli set-default-vault "my-brain"

# Register and set as default in one step
notesmd-cli add-vault /home/user/vaults/my-brain --set-default

    Targeting a Specific Vault

    If you have multiple vaults registered, use the --vault flag to target a specific one:

    notesmd-cli add-vault /home/user/vaults/personal
notesmd-cli add-vault /home/user/vaults/work
notesmd-cli set-default-vault "personal"

# Use the 'work' vault specifically
notesmd-cli <command> --vault "work"
    # Register your vault directory
notesmd-cli add-vault /home/user/vaults/my-brain

# Set it as default
notesmd-cli set-default-vault "my-brain"

# Or do both in one step
notesmd-cli add-vault /home/user/vaults/my-brain --set-default

  10. Install NotesMD CLI on Windows

    main

    To install NotesMD CLI on Windows, use the Scoop package manager. Run the following commands in PowerShell:

    1. Add the yakitrak bucket: scoop bucket add scoop-yakitrak https://github.com/yakitrak/scoop-yakitrak.git
    2. Install the CLI: scoop install notesmd-cli
    scoop bucket add scoop-yakitrak https://github.com/yakitrak/scoop-yakitrak.git
scoop install notesmd-cli

  11. Uninstall obsidian-cli

    main

    Before installing notesmd-cli, uninstall the old obsidian-cli version using the method corresponding to your installation type:

    Windows (Scoop)

    scoop uninstall obsidian-cli

    Mac/Linux (Homebrew)

    brew uninstall obsidian-cli

    Arch Linux (AUR)

    # Using yay
yay -R obsidian-cli-bin

# Using paru
paru -R obsidian-cli-bin

    Manual Installation

    If you installed the binary manually, find its location and remove it:

    # Find location
which obsidian-cli

# Remove (common locations)
sudo rm /usr/local/bin/obsidian-cli
# or
rm ~/bin/obsidian-cli
    scoop uninstall obsidian-cli

  12. Manual Vault Configuration (without CLI)

    main

    If you prefer not to use the CLI for setup, you can manually create the Obsidian configuration file.

    1. Create the directory: mkdir -p ~/.config/obsidian
    2. Create obsidian.json with the following structure:
    {
  "vaults": {
    "any-unique-id": {
      "path": "/home/user/vaults/my-brain"
    }
  }
}

    Important Notes:

    • The key (any-unique-id) can be any string. The CLI uses the directory name (e.g., my-brain) as the vault name.
    • Use absolute paths only. The CLI does not expand the tilde (~) character.