# NotesMD CLI: Obsidian Vault Automation Without the Desktop App > NotesMD CLI is a Go command-line client for managing Obsidian vaults from terminals, scripts, containers, and headless systems. It works directly with vault files and does not require Obsidian to be running, but users must understand its configuration file and editor boundaries. **Yakitrak/notesmd-cli** — Obsidian CLI (Community) - Interact with Obsidian in the terminal! - Repository: https://github.com/Yakitrak/notesmd-cli - Stars: 1,600 · Forks: 83 - Language: Go - License: MIT - Published: 2026-10-16 · Updated: 2026-10-16 · Language: en - Canonical page: https://hysenlabs.com/projects/yakitrak-notesmd-cli ## What NotesMD CLI Changes for Obsidian Vaults NotesMD CLI addresses a specific gap between Obsidian's desktop-oriented workflow and shell-based note handling. Obsidian stores notes as plain Markdown files in local vaults, but the README describes NotesMD CLI as a terminal interface for opening, searching, listing, creating, updating, moving, and deleting those notes. The target users are people who already use Obsidian vaults but need repeatable command-line operations, especially on servers, in containers, or in environments without a graphical interface. The repository was originally named Obsidian CLI and was renamed because an official Obsidian CLI now exists. That distinction matters when searching documentation or comparing tools. The repository's Go module is `github.com/Yakitrak/notesmd-cli`, and the command name used throughout the documentation is `notesmd-cli`. It is not a plugin that runs inside Obsidian, and it does not require the Obsidian application to remain open. The README specifically describes it as suitable for scripting, automation, and terminal-only environments. That model has a clear boundary. NotesMD CLI works with the Markdown vault and Obsidian's vault registration configuration. The documentation does not claim that it invokes Obsidian plugins, reproduces the Obsidian user interface, or provides a substitute for every desktop feature. Its value comes from treating a vault as a directory of files that can be inspected and changed through commands. ## Vault Registration and Headless Operation The central operational distinction is that NotesMD CLI can operate without an Obsidian installation. In a normal desktop setup, the README says Obsidian registers vaults automatically when they are opened. On a headless server or in a container, that automatic registration is unavailable, so the CLI registers a vault by writing the relevant Obsidian configuration. The `add-vault` command accepts a vault directory. The `set-default-vault` command selects a named vault for later operations. A combined form registers the directory and makes it the default. The README also documents manual configuration through `~/.config/obsidian/obsidian.json`. In that file, the vault name is derived from the directory name, while the path must be absolute. The documentation explicitly warns against using `~`, because the CLI does not expand it. This approach is useful in CI jobs and containers, where an Obsidian process cannot be started. It also makes configuration reproducible if a deployment creates the same directory structure each time. The trade-off is that NotesMD CLI must preserve Obsidian's configuration conventions rather than maintain an entirely independent vault database. A manually edited configuration can therefore affect behavior across both applications. Vault changes require care. The README says to fully quit Obsidian before adding or removing vaults. Closing its windows is not sufficient on macOS, where it specifically calls for `Cmd+Q`. A running Obsidian process may overwrite external registry changes, causing a newly added vault to disappear or a removed vault to reappear. For those changes, Obsidian's vault manager is the documented alternative. ## Terminal Editing and Obsidian Configuration NotesMD CLI separates file operations from the interface used to open notes. The `open`, `daily`, `search`, `search-content`, `create`, and `move` commands accept `--editor`, also shortened to `-e`. With that flag, the command uses the configured text editor rather than opening the note through Obsidian. This is the path intended for terminal-only work. The editor comes from the `EDITOR` environment variable. The README gives `vim`, `code`, and `code -w` as examples. If `EDITOR` is unset, NotesMD CLI uses `vim`. Supported terminal editors include `vim`, `nano`, and `emacs`. The documentation also lists GUI-oriented editors such as VSCode, Sublime Text, Atom, and TextMate. For supported GUI editors, the CLI adds a wait flag so the editor process remains open until the file is closed. A one-time default can be stored in the vault configuration with `set-default-vault --open-type editor`. That avoids repeating `--editor` for every operation. The choice is operational rather than cosmetic. In a server environment, a GUI editor may not exist at all, while in a desktop shell it may be more convenient than launching Obsidian. The README does not describe a graphical file picker or an Obsidian-native editor session. The distinction also affects automation. A command that edits through `EDITOR` depends on the editor's process behavior, environment, and wait semantics. A headless job should use a terminal editor that is actually installed. NotesMD CLI supplies the file operation and editor invocation, but it does not remove that external dependency. ## Search, Note Lifecycle, and Scriptable Output The command set is oriented around a note lifecycle rather than Obsidian's full interface. According to the README, NotesMD CLI can open notes, create daily notes, search notes by name, search note content, list vault contents, print a note, create or update a note, move or rename a note, and delete a note. These operations map directly to common shell tasks. The CLI also includes frontmatter support, and the Go dependencies include a frontmatter parser and YAML support. That indicates a Markdown-oriented data path: notes remain files, and metadata can be handled as part of note processing. The README excerpt does not document the exact syntax of every frontmatter operation, so an adopter should inspect the command help before building a script around fields. Output and interaction are not fully described in the available documentation. The project includes a fuzzy finder dependency, `github.com/ktr0731/go-fuzzyfinder`, and a screenshot generation target in the Makefile. The screenshot command uses `freeze`, but the README excerpt does not state that this is required for normal operation. Therefore, scripts should be designed around documented flags and outputs, not around assumptions about interactive prompts. Deletion is the sharpest operational boundary. A CLI can remove a Markdown file, but the documentation excerpt does not describe confirmation prompts, trash behavior, undo, or a recoverable backup workflow. The user should verify deletion behavior against `notesmd-cli --help` and the command-specific documentation before placing it in an unattended script. ## Installation Choices for Windows, Unix, and Source Builds The README provides separate installation paths for Windows, macOS, Linux, Arch Linux, and source builds. Windows users install through Scoop after adding the `scoop-yakitrak` bucket. macOS and Linux users can add the `yakitrak/yakitrak` Homebrew tap and install the formula. Arch Linux users can use an AUR helper for the prebuilt `notesmd-cli-bin` package or install the source package. A source build clones the repository, changes into its directory, builds the Go binary, and installs it under `/usr/local/bin`. The README states that Go 1.19 or later is required. The repository's `go.mod`, however, declares `go 1.26.1`. That difference should be treated as a build compatibility issue to verify before publishing installation instructions for a specific environment. The README's documented build command is the following. ```bash 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/ ``` After installation, verify that the command is on `PATH` before registering a vault. The command help is the first concrete check available from the README. It should list the supported subcommands, including `add-vault`, `set-default-vault`, `open`, `search-content`, `create`, and `move`. ```bash notesmd-cli --help ``` The repository includes a Makefile with `build-all`, `test`, and `test-coverage` targets. Those targets are useful for source-based maintenance, but they are repository development commands rather than end-user installation instructions. The release process documented by the Makefile builds Darwin, Linux, and Windows binaries and updates the version in `cmd/root.go`. ## Headless Vault Setup and First Note Operations For a server or container, the first useful workflow is to register the vault and choose a default. The following command assumes that `/home/user/vaults/my-brain` exists and is the intended vault directory. The CLI creates the Obsidian configuration file when it does not already exist. ```bash notesmd-cli add-vault /home/user/vaults/my-brain notesmd-cli set-default-vault "my-brain" ``` The combined form performs both operations in one command. For an isolated environment, this is the shortest documented path from an unregistered vault to a usable default. ```bash notesmd-cli add-vault /home/user/vaults/my-brain --set-default ``` After registration, list the available vaults or inspect a note before editing it. The README names listing vaults and printing a note as available operations, but the complete flag syntax is not shown in the excerpt. Use the command help to confirm the exact arguments before placing either operation in a script. A terminal-only workflow can create or open a note through the editor flag. The documented command pattern is: ```bash export EDITOR="vim" notesmd-cli create "note.md" --open --editor ``` The `EDITOR` value determines which program opens the file. In a container, `vim` must be present. For a noninteractive process, the documentation does not specify whether `create` waits for editor exit or how errors are reported, so that behavior should be checked with a disposable note first. The available repository entries include `mocks/`, `pkg/`, `cmd/`, `main.go`, and a `vendor/` directory, which indicates a structured Go CLI with separate command, package, and test areas. ## Limits of the Obsidian-Compatible File Workflow NotesMD CLI is the wrong tool when the requirement is to control Obsidian plugins, canvas files, or application-specific commands through the Obsidian runtime. The README frames the project around local Markdown notes and Obsidian vault configuration. It does not document a plugin API, plugin installation, command palette integration, graph operations, or synchronization with Obsidian Sync. Those features should not be inferred from the fact that the tool is named after Obsidian. It is also unsuitable for a user who wants the Obsidian desktop experience without changing their workflow. The CLI can open notes in an external editor, but that is not the same as using Obsidian's own rendering, navigation, and extension environment. The absence of a required Obsidian process improves headless compatibility but removes the application as a runtime dependency, including any behavior that would have come from it. The vault registration process has another constraint. NotesMD CLI writes or removes entries in Obsidian's configuration, so a running Obsidian instance can undo those changes. This makes concurrent registration unsafe according to the README. Teams should treat vault registration as a setup step performed while Obsidian is stopped, then use the registered vault for subsequent note commands. Finally, the source documentation does not provide a rollback guide for note deletion or migration instructions for every prior command. `MIGRATION.md` is specifically documented for upgrades from `obsidian-cli` v0.2.3 or earlier, but the available excerpt does not describe rollback behavior for file operations. Users who need transactional changes should keep their own backups. ## NotesMD CLI Versus Direct Markdown Automation A real alternative is to treat the Obsidian vault as a normal directory and use ordinary shell tools or a dedicated Markdown tool. For example, a shell script can use `find`, `grep`, and `mv` to locate and rename files, while a text editor can open them directly. That approach avoids changing Obsidian's configuration and does not require a CLI-specific vault registry, but it does not provide NotesMD CLI's named commands, default-vault handling, editor integration, or Obsidian-specific frontmatter behavior. The difference is not merely syntax. NotesMD CLI presents note operations as one application-level interface and is designed to register vaults for headless use. Direct filesystem automation gives the operator total control over paths and patterns, yet requires the script to understand vault structure and handle Obsidian's configuration independently. It may also make it easier to operate on files that are not notes in the user's normal workflow. For users who already depend on a larger script ecosystem, the direct approach can be easier to inspect and compose. For users who want repeatable commands with a consistent vault name, NotesMD CLI removes some of that custom scripting. The trade-off is that NotesMD CLI becomes another component whose configuration and deletion behavior must be understood. A more distant alternative is to use Obsidian's desktop application and its vault manager. That is the documented choice when Obsidian is already running for vault registration changes. It does not satisfy a headless or terminal-only requirement, so the appropriate alternative depends on whether the job needs automation or desktop integration. ## Maintenance Signals and Upgrade Boundaries The repository is not archived, and its last push was on 2026-10-13. The listed releases include `v0.3.8` on 2026-10-13, `v0.3.7` on 2026-09-01, and `v0.3.6` on 2026-05-05. These are maintenance signals, but they do not by themselves establish compatibility with a particular vault configuration or operating system. Upgrade testing remains necessary because the CLI writes files and modifies Obsidian's registry. The project is licensed under MIT. That permits use and modification under the license's conditions, but this review does not interpret the license or provide legal guidance. Users distributing a modified binary should review the repository's `LICENSE` file and preserve the required notices. Upgrading from the old `obsidian-cli` name is a separate concern. The README points users on `obsidian-cli` v0.2.3 or earlier to `MIGRATION.md` for uninstall, installation, and configuration migration steps. It does not claim that every old command maps directly to the renamed tool. The deprecated-command section should be checked before relying on an existing script. The Go version mismatch between the README and `go.mod` is another upgrade boundary. A source builder should use a Go toolchain that satisfies the module declaration, not assume that the older documented minimum is sufficient. The available documentation does not state a backward-compatibility policy for vault configuration changes, so a pre-upgrade backup of `obsidian.json` and note files is the concrete precaution to take. ## Conclusion Adopt NotesMD CLI when automation, CI containers, or terminal-only access to Obsidian vaults matters more than Obsidian's desktop interface. Do not choose it when you need undocumented plugin behavior or expect a full replacement for Obsidian's vault manager. Verify first that your vault paths are absolute, the `EDITOR` setting is correct, and your Obsidian process is stopped before changing vault registration. ## FAQ ### Does NotesMD CLI require Obsidian to be running? No. The README states that NotesMD CLI works without requiring Obsidian to be running, which makes it suitable for headless systems, containers, and terminal-only environments. ### How do I register a vault in NotesMD CLI? Run `notesmd-cli add-vault` with the vault directory. You can use `--set-default` to register it and select it as the default, or set it later with `notesmd-cli set-default-vault`. ### Which editor does NotesMD CLI use? The CLI uses the `EDITOR` environment variable when `--editor` or `-e` is supplied. If `EDITOR` is not set, it defaults to `vim`. ### Can NotesMD CLI change vault registration while Obsidian is open? The README advises fully quitting Obsidian before adding or removing vaults. A running Obsidian process may overwrite the external configuration change. ## Sources - [Issues](https://github.com/Yakitrak/notesmd-cli/issues) - [License: MIT](https://github.com/Yakitrak/notesmd-cli/blob/main/LICENSE) - [README](https://github.com/Yakitrak/notesmd-cli/blob/main/README.md) - [Releases](https://github.com/Yakitrak/notesmd-cli/releases) - [Yakitrak/notesmd-cli on GitHub](https://github.com/Yakitrak/notesmd-cli) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/yakitrak-notesmd-cli