ito-cli 糸

Navigate your Obsidian vault from the command line. The companion tool to the Ito Obsidian plugin.

---

What this is for

You have an Obsidian vault full of notes, images, audio, and PDFs. You want to ask questions like:

• "What do I know about developer experience?"
• "Find everything I've written about embeddings"
• "What notes relate to knowledge management?"

Instead of opening Obsidian, you run:

ito "developer experience"

It searches your vault graph, follows links and backlinks, reads the relevant notes, and compiles the full context — ready for you to read or feed directly into any AI.

---

The Two-Part System

Ito works as a pair:

1. Ito Obsidian Plugin (install first)

• Indexes your vault using Gemini multimodal embeddings
• Automatically exports vault-graph.json — a live map of every note's links, backlinks, tags, and summaries
• Keeps the graph fresh whenever you add or edit notes

2. ito-cli (this tool)

• Reads vault-graph.json
• Searches and navigates the graph by query
• Fetches and compiles the actual note content
• Works from any terminal, with any AI tool

---

Using with an AI (Claude, Cursor, or any LLM)

This is the most powerful use case. Configure your AI to use ito as a knowledge retrieval tool.

Claude Code / Claude Desktop

Add this to your Claude system prompt or CLAUDE.md:

When the user asks "what do I know about X" or "find my notes on X" or 
"what have I written about X", run:

  python3 /path/to/ito.py "X"

Read the output and answer from the actual vault content.

Now when you ask Claude "what do I know about developer experience?" it runs ito "developer experience", reads your notes, and answers from your actual knowledge — not its training data.

Manual use

ito "knowledge management"
ito "what do I know about embeddings"
ito "developer experience"

Output is compiled markdown — pipe it anywhere:

ito "embeddings" | pbcopy          # copy to clipboard
ito "embeddings" > context.md      # save to file

---

Setup

1. Install the Ito Obsidian plugin

Follow instructions at https://github.com/heetvadiya/ito — install, add your Gemini API key, let it index your vault. This generates vault-graph.json in your vault root.

2. Get ito-cli

curl -O https://raw.githubusercontent.com/heetvadiya/ito-cli/main/ito.py

Or clone:

git clone https://github.com/heetvadiya/ito-cli.git
cd ito-cli

3. Set your default vault

python3 ito.py --config-vault ~/obsidian/MyVault

Saved permanently to ~/.ito/config.json. Only needed once.

4. Make it available everywhere

Add to ~/.bashrc or ~/.zshrc:

alias ito="python3 /path/to/ito.py"

Then reload:

source ~/.bashrc   # or source ~/.zshrc

Now ito works from any directory.

---

Commands

# Search default vault
ito "your query"

# Search a different vault (one-off)
ito --vault ~/obsidian/OtherVault "your query"

# Change default vault
ito --config-vault ~/obsidian/NewVault

# Options
ito "query" --depth 2   # follow links 2 hops deep (default: 1)
ito "query" --max 20    # include up to 20 notes (default: 10)

---

How it works

1. Reads vault-graph.json from your vault
2. Scores every note against your query — title, summary, tags
3. Follows links and backlinks from top matches
4. Reads the actual .md files
5. Compiles everything into one clean markdown output

Output is structured markdown — headers, paths, tags, links, and full note content. This makes it directly consumable by any LLM without preprocessing. Paste it into a conversation, pipe it to a model, or let Claude run the command and read it in context.

No database. No API calls. No server. Just JSON and file reads.

---

Requirements

• Python 3.10+
• Ito Obsidian plugin installed and indexed

---

Part of the Ito ecosystem. The threads were always there.