What Is Obsidian: From Installation to Opening the Knowledge Base via the Command Line

What Is Obsidian: From Installation to Opening the Knowledge Base via the Command Line

If this is your first time hearing about Obsidian, don’t overcomplicate it just yet.

At its core, it’s a note-taking tool designed to manage local Markdown files. Every note you write is typically a file on your computer named something like .md;These files are stored in a regular folder, which Obsidian calls a “Vault.”

So Obsidian isn’t just “another cloud-based note-taking app”—it’s more like a knowledge base built around a file system: the content is stored locally, the format is open, the directory structure is visible to you, and notes can be linked together.

What Problems Does Obsidian Solve?

Typical note-taking software usually emphasizes recording: write down whatever comes to mind today. Obsidian is better suited for long-term accumulation: content you write today can still be searched, linked, organized, and reused in the future.

It has several key features.

First, notes are local files.Your knowledge isn’t confined to the database of some online service—it’s stored in folders on your own computer. You can back it up, sync it, migrate it, or open it with other editors.

Second, the format is Markdown. Markdown is a very lightweight text format that’s easy for both humans to read and machines to process. Headings, lists, code blocks, citations, and links can all be expressed using plain text.

Third, notes can be linked to one another. In Obsidian, typing [[项目复盘]] creates a link to another note. Over time, you won’t end up with just a collection of isolated documents—you’ll build an interconnected network of knowledge.

Fourth, it integrates well with automation tools. Since notes are essentially files, scripts, agents, and command-line tools can all read and write this content. This is also why it’s well-suited to serve as the foundation for a personal knowledge base.

A Few Basic Concepts

Understanding a few terms before installation will make things much easier.

Vault

A Vault is an entire knowledge base managed by Obsidian. You can think of it as a regular folder, for example:

我的知识库/
├── 工作/
├── 学习/
├── 项目/
└── 日记/

Obsidian doesn’t open a single note; it opens the entire Vault. A person can have multiple Vaults, but it’s recommended to start with just one.

Note

A Note is a single note, typically corresponding to a .md file.

For example, if you create a note called 什么是 Agent in Obsidian, you’ll usually see the following in your file system:

什么是 Agent.md

This is important: Obsidian doesn’t lock your content into a proprietary format.

Link

A Link is a connection between notes.

这篇文章和 [[Agent 与 Obsidian 工作流]] 有关。

When you click this link, Obsidian opens the corresponding note. If the note doesn’t exist yet, it will create it on the spot.

Graph View

Graph View is Obsidian’s graph view. It represents notes as nodes and links as lines.

Many people are drawn to the graph when they first encounter Obsidian, but the graph isn’t the core feature. What’s truly valuable is the connections you actively create while writing notes; the graph is simply a visualization of those connections.

Installing Obsidian

The safest way is to download it from the official Obsidian website:

https://obsidian.md/download

Select the version for your operating system:

• macOS: Download .dmg and drag it to the Applications folder.
• Windows: Download the installer and follow the setup wizard to complete the installation.
• Linux: Choose AppImage, deb, rpm, or another format based on your distribution.

Once installed, open Obsidian. The first time you launch it, you’ll be prompted to either create a new Vault or open an existing folder.

If you’re a new user, we recommend creating a new Vault.

Creating Your First Vault

I suggest not designing a complex directory structure at first; just set up a basic structure that works.

For example, create a Vault named:

My Knowledge Base

Then create a few directories inside it:

Inbox/
Projects/
Knowledge/
Outputs/

These four directories are enough to get started:

• Inbox: Temporary notes—use this for content that hasn’t been organized yet.
• Projects: Project processes, meeting minutes, and troubleshooting logs.
• Knowledge: Concepts, methods, and lessons learned for long-term reuse.
• Outputs: Content to be published as blog posts, documentation, or proposals.

Your directory structure doesn’t have to be perfect from the start. The beauty of Obsidian is that it’s essentially a set of folders—you can adjust them at any time later.

Writing Your First Note

Start by creating a very simple note, such as:

我的第一篇 Obsidian 笔记

. The content could look like this:

# 我的第一篇 Obsidian 笔记

今天开始用 Obsidian 管理自己的知识库。

## 我想解决的问题

- 不想让有价值的讨论只留在聊天记录里。
- 希望项目经验下次还能被找回来。
- 希望长期积累可以变成文章、文档或方案。

## 相关笔记

- [[个人知识管理]]
- [[Agent 与 Obsidian 工作流]]

By writing this, you’ve already utilized Obsidian’s core capabilities: Markdown, files, and links.

What Is the Obsidian CLI

The desktop version of Obsidian is primarily designed for human use: opening the app, editing notes, searching for content, and viewing links.

The CLI, on the other hand, is designed for command-line and automation scenarios: reading, creating, and searching for notes, as well as appending content in the terminal. This allows agents or scripts to interact with your knowledge base.

One thing to note: Obsidian supports two common automation entry points.

The first is the obsidian:// URI. It allows you to open a Vault, open a note, create a note, or trigger a search via a link, making it suitable for cross-application integration.

The second is the Obsidian CLI, which involves using obsidian commands in the terminal. It’s suitable for scripts, agents, and more complex automation workflows.

To enable the CLI, first ensure you have a recent version of the Obsidian desktop app installed, then open the following in Obsidian:

General -> Command line interface

Settings -> General -> Command line interface

Once enabled, follow the on-screen prompts to add the CLI to your system PATH. After adding it, restart your terminal.

On macOS, this entry is typically created after registration:

/usr/local/bin/obsidian

On Windows, the installer provides a terminal shortcut; on Linux, the CLI is usually placed in ~/.local/bin/obsidian, so you’ll need to verify that ~/.local/bin is already in PATH.

You can check first:

command -v obsidian
obsidian help

If command -v obsidian produces no output, you can also check:

ls -l /usr/local/bin/obsidian
/usr/local/bin/obsidian help

If none of these commands exist, it means your system does not yet have a directly executable Obsidian CLI. In this case, first ensure that the desktop version of Obsidian is properly installed and running, then return to Settings to enable and register the CLI.

Additionally, the Obsidian app itself must be running when executing CLI commands.

Viewing Vaults with the CLI

Once the CLI is running properly, you can start by seeing what commands are available:

obsidian help

If you have multiple Vaults, you can specify a Vault name:

obsidian vault="My Knowledge Base" files

After listing the files, you can read a specific note:

obsidian vault="My Knowledge Base" read path="Knowledge/个人知识管理.md"

You can also view information about a specific file:

obsidian vault="My Knowledge Base" file path="Knowledge/个人知识管理.md"

There are two common parameters to distinguish between:

• file= is more like searching by note name, similar to the wikilink experience in Obsidian.
• path= specifies the exact file path, suitable for scripts and Agents.

In automated scenarios, I recommend using path= because it’s more explicit.

Creating and Appending Notes via the CLI

Create a new note:

obsidian vault="My Knowledge Base" create path="Inbox/今天的想法.md" content="今天开始整理 Obsidian 工作流。"

Append content to an existing note:

obsidian vault="My Knowledge Base" append path="Inbox/今天的想法.md" content="\n\n## 后续行动\n\n- 整理目录结构\n- 建立第一组链接"

Read and verify:

obsidian vault="My Knowledge Base" read path="Inbox/今天的想法.md"

Combined, these three commands form the smallest command-line loop: create, append, read.

Searching for Notes via the CLI

As your Vault grows, searching becomes crucial.

obsidian vault="My Knowledge Base" search query="Agent"

If you want the Agent to help you find historical context, you can usually have it search first, then read the relevant notes, and finally summarize existing conclusions.

This process is much more reliable than relying solely on chat logs, because knowledge is stored where you can see it, edit it, and verify it.

Recommended Getting Started Sequence

If you’re new to Obsidian, I recommend following this sequence:

1. Install the desktop version of Obsidian.
2. Create a Vault.
3. Write your first Markdown note.
4. Learn how to create links using [[笔记名]].
5. Verify that obsidian help runs on your machine.
6. Use the CLI to create, read, and search for a note.
7. Then consider using an Agent to help with organization and reuse.

Don’t install too many plugins right away, and don’t design a complex categorization system from the start. First, go through the entire process of inputting, organizing, saving, and reusing a piece of real information.

Next Step: Getting the Agent to Use Obsidian

Once you understand Vaults, Markdown, links, and the CLI, the integration of the Agent with Obsidian becomes straightforward.

Obsidian stores long-term knowledge, while the Agent is responsible for reading, distilling, connecting, and rewriting it. You can organize a discussion into a note, or have the Agent retrieve context from old notes to generate new articles, documents, or proposals.

Continue reading in the next post: Agent and Obsidian: Turning Your Personal Knowledge Base into an Actionable Second Brain.