Initial commit

skills/obsidian-vault-manager/references/obsidian-cli-reference.md

@@ -0,0 +1,380 @@
+# obsidian-cli Command Reference
+
+Complete reference for `obsidian-cli` commands and advanced usage patterns.
+
+## Installation
+
+```bash
+npm install -g @johnlindquist/obsidian-cli
+```
+
+Verify installation:
+```bash
+obsidian-cli --version
+```
+
+## Core Commands
+
+### print-default
+
+Display current vault information.
+
+```bash
+obsidian-cli print-default
+```
+
+**Flags:**
+- `--path-only` - Output only the vault path (useful for scripting)
+
+**Output:**
+- Vault name
+- Vault path
+- Vault status
+
+**Usage:**
+```bash
+# Get vault info
+obsidian-cli print-default
+
+# Get path for scripts
+VAULT_PATH=$(obsidian-cli print-default --path-only)
+echo "Vault location: $VAULT_PATH"
+```
+
+### print
+
+Read note contents by name or path.
+
+```bash
+obsidian-cli print "Note Name"
+obsidian-cli print "folder/Note Name"
+```
+
+**Behavior:**
+- Searches by note name first (without path)
+- Falls back to path-based lookup
+- Returns full note contents including frontmatter
+- Case-sensitive matching
+
+**Examples:**
+```bash
+# Read by name
+obsidian-cli print "Project Plan"
+
+# Read by path
+obsidian-cli print "Work/Projects/Project Plan"
+
+# Pipe to other tools
+obsidian-cli print "Note" | grep "TODO"
+```
+
+### create
+
+Create new notes or update existing ones.
+
+```bash
+obsidian-cli create "Note Name" --content "content"
+```
+
+**Required Flags:**
+- `--content "text"` - Note content (supports `\n` for newlines)
+
+**Optional Flags:**
+- `--append` - Add content to end of existing note (safe for existing files)
+- `--overwrite` - Replace entire note (destructive)
+- `--open` - Open note in Obsidian after creation
+
+**Content Syntax:**
+- Use `\n` for newlines
+- Include Obsidian syntax: `[[wiki-links]]`, `#tags`, `- [ ]` checkboxes
+- Frontmatter can be included in content
+
+**Examples:**
+```bash
+# Create new note
+obsidian-cli create "Meeting Notes" --content "# Meeting\n\nAttendees: [[John]], [[Sarah]]"
+
+# Append to existing
+obsidian-cli create "Daily Log" --content "\n## 3pm Update\n- Completed task" --append
+
+# Replace existing (caution!)
+obsidian-cli create "Draft" --content "# New Draft\n\nStarting over" --overwrite
+
+# Create and open in Obsidian
+obsidian-cli create "Quick Note" --content "# Note" --open
+```
+
+**Frontmatter Example:**
+```bash
+obsidian-cli create "Book Review" --content "---\ntitle: Book Title\nauthor: Author Name\nrating: 5\n---\n\n# Review\n\nExcellent book about [[Topic]]"
+```
+
+### move
+
+Move or rename notes while preserving all wiki-links.
+
+```bash
+obsidian-cli move "old/path" "new/path"
+```
+
+**Behavior:**
+- Automatically updates ALL links to moved note throughout entire vault
+- Updates bidirectional links
+- Maintains frontmatter and note content
+- Creates destination folder if needed
+
+**Path Formats:**
+- Vault-relative paths (no leading `/`)
+- With or without `.md` extension
+- Folder paths for organizing
+
+**Examples:**
+```bash
+# Move note to different folder
+obsidian-cli move "Inbox/Idea" "Projects/New Idea"
+
+# Rename note
+obsidian-cli move "Draft Title" "Final Title"
+
+# Reorganize with folders
+obsidian-cli move "Random/Design Doc" "Projects/Mobile/Design Doc"
+
+# Move with .md extension (works the same)
+obsidian-cli move "note.md" "folder/note.md"
+```
+
+**Critical:** This is the ONLY safe way to move notes. Using `mv`, `Write`, or file operations will break all links.
+
+### search-content
+
+Search note contents for text.
+
+```bash
+obsidian-cli search-content "search term"
+```
+
+**Behavior:**
+- Full-text search across all notes
+- Returns matching note paths
+- Case-insensitive by default
+- Searches note content, not just titles
+
+**Examples:**
+```bash
+# Find notes about a topic
+obsidian-cli search-content "API design"
+
+# Find todos
+obsidian-cli search-content "- [ ]"
+
+# Find tagged notes
+obsidian-cli search-content "#important"
+
+# Combine with other commands
+for note in $(obsidian-cli search-content "refactor"); do
+  echo "Found in: $note"
+  obsidian-cli print "$note"
+done
+```
+
+### search
+
+Interactive fuzzy search for note names.
+
+```bash
+obsidian-cli search
+```
+
+**Behavior:**
+- Opens interactive picker
+- Fuzzy matching on note names
+- Navigate with arrow keys
+- Press Enter to select
+
+**Usage:**
+- Run command
+- Type to filter notes
+- Select note with Enter
+- Use selected note path in scripts
+
+**Note:** This is interactive and may not work in all automation contexts. Use `search-content` for scripting.
+
+### daily
+
+Create or open daily note.
+
+```bash
+obsidian-cli daily
+```
+
+**Behavior:**
+- Creates note with today's date (YYYY-MM-DD format by default)
+- Opens in Obsidian if it already exists
+- Uses vault's daily note template if configured
+
+**Examples:**
+```bash
+# Open today's note
+obsidian-cli daily
+
+# Create with custom content
+obsidian-cli daily && obsidian-cli create "$(date +%Y-%m-%d)" --content "\n## Evening Review\n- Accomplishments" --append
+```
+
+## Advanced Usage Patterns
+
+### Scripting with obsidian-cli
+
+```bash
+#!/bin/bash
+
+# Get vault path for reference
+VAULT_PATH=$(obsidian-cli print-default --path-only)
+
+# Search and process notes
+obsidian-cli search-content "TODO" | while read -r note; do
+  echo "Processing: $note"
+  content=$(obsidian-cli print "$note")
+  # Process content...
+done
+
+# Bulk reorganization
+for note in $(obsidian-cli search-content "#archive"); do
+  obsidian-cli move "$note" "Archive/$note"
+done
+```
+
+### Combining with Standard Tools
+
+```bash
+# Use obsidian-cli for vault operations, then standard tools for processing
+obsidian-cli print "Note" > /tmp/note.md
+# Edit with standard tools
+sed -i 's/old/new/g' /tmp/note.md
+# Write back to vault
+obsidian-cli create "Note" --content "$(cat /tmp/note.md)" --overwrite
+```
+
+### Template-Based Note Creation
+
+```bash
+# Read template
+TEMPLATE=$(cat templates/project-template.md)
+
+# Create note with template
+obsidian-cli create "New Project" --content "$TEMPLATE"
+
+# Create with substitutions
+TEMPLATE=$(cat templates/meeting-template.md | sed "s/DATE/$(date +%Y-%m-%d)/g")
+obsidian-cli create "Meeting - Team Sync" --content "$TEMPLATE"
+```
+
+### Batch Operations
+
+```bash
+# Rename multiple notes with pattern
+for note in Project-*; do
+  new_name=$(echo "$note" | sed 's/Project-/Archived-Project-/')
+  obsidian-cli move "$note" "Archive/$new_name"
+done
+
+# Add tag to multiple notes
+obsidian-cli search-content "machine learning" | while read -r note; do
+  content=$(obsidian-cli print "$note")
+  obsidian-cli create "$note" --content "$content\n\n#machine-learning" --append
+done
+```
+
+### Working with Frontmatter
+
+```bash
+# Create note with complex frontmatter
+obsidian-cli create "Article" --content "---
+title: Article Title
+date: $(date +%Y-%m-%d)
+tags:
+  - article
+  - published
+author: John Doe
+---
+
+# Article Title
+
+Content here with [[Wiki Links]]"
+```
+
+### Link Integrity Verification
+
+```bash
+# After bulk operations, verify links
+# (obsidian-cli handles this automatically, but for validation:)
+VAULT_PATH=$(obsidian-cli print-default --path-only)
+
+# Use standard tools to find broken links
+grep -r "\[\[.*\]\]" "$VAULT_PATH" | while read -r line; do
+  # Check if target exists
+  # obsidian-cli move ensures this isn't needed
+done
+```
+
+## Troubleshooting
+
+### Command Not Found
+
+```bash
+# Install globally
+npm install -g @johnlindquist/obsidian-cli
+
+# Or use npx
+npx @johnlindquist/obsidian-cli print-default
+```
+
+### No Default Vault
+
+Error: "No default vault set"
+
+**Solution:**
+- Open Obsidian application
+- Vault must be opened at least once
+- obsidian-cli reads from Obsidian's configuration
+
+### Path Issues
+
+**Problem:** Note not found by name
+
+**Solution:**
+```bash
+# Use full path
+obsidian-cli print "folder/subfolder/Note Name"
+
+# Or search first
+obsidian-cli search-content "unique phrase in note"
+```
+
+### Newlines Not Working
+
+**Problem:** `\n` appears literally in notes
+
+**Solution:**
+```bash
+# Use echo with -e flag
+obsidian-cli create "Note" --content "$(echo -e "Line 1\nLine 2")"
+
+# Or use $'...' syntax
+obsidian-cli create "Note" --content $'Line 1\nLine 2'
+```
+
+## Best Practices
+
+1. **Always check vault first:** Run `print-default` before operations
+2. **Use obsidian-cli move exclusively:** Never use `mv` for notes
+3. **Preserve Obsidian syntax:** Maintain `[[links]]`, `#tags`, frontmatter
+4. **Test on copies:** For bulk operations, test on duplicate notes first
+5. **Use --append safely:** Append is safe for existing files, overwrite is destructive
+6. **Script defensively:** Check command success before proceeding
+7. **Backup regularly:** obsidian-cli is safe, but backups prevent mistakes
+
+## See Also
+
+- [Obsidian Syntax Reference](./obsidian-syntax.md) - Wiki-link and markdown syntax
+- [Note Templates](../assets/templates/) - Ready-to-use note templates

skills/obsidian-vault-manager/references/obsidian-syntax.md

@@ -0,0 +1,567 @@
+# Obsidian Markdown Syntax Reference
+
+Complete reference for Obsidian-specific markdown syntax, including wiki-links, tags, frontmatter, and extended markdown features.
+
+## Wiki-Links
+
+Obsidian's primary linking syntax for internal note connections.
+
+### Basic Wiki-Links
+
+```markdown
+[[Note Name]]
+```
+
+Links to a note named "Note Name.md" anywhere in the vault.
+
+**Characteristics:**
+- Case-sensitive
+- Extension not required
+- Searches entire vault by name
+- Creates link even if note doesn't exist (shown in different color in Obsidian)
+
+### Wiki-Links with Aliases
+
+```markdown
+[[Actual Note Name|Display Text]]
+```
+
+Display custom text while linking to the actual note.
+
+**Examples:**
+```markdown
+See the [[Project Requirements|requirements]] for details.
+Read [[Albert Einstein|Einstein's]] biography.
+Check [[2024-01-15|yesterday's notes]].
+```
+
+### Wiki-Links to Headings
+
+```markdown
+[[Note Name#Heading]]
+[[Note Name#Heading|Custom Text]]
+```
+
+Link to specific section within a note.
+
+**Examples:**
+```markdown
+Review [[Meeting Notes#Action Items]]
+See [[API Documentation#Authentication|auth docs]]
+```
+
+**Heading Link Rules:**
+- Heading text must match exactly (case-sensitive)
+- Use heading text without the `#` prefix
+- Spaces in headings are preserved
+- Works with any heading level
+
+### Wiki-Links to Blocks
+
+```markdown
+[[Note Name#^block-id]]
+```
+
+Link to specific block within a note.
+
+**Block ID Syntax:**
+```markdown
+This is a paragraph with an ID. ^block-123
+
+- List item with ID ^item-456
+```
+
+**Example:**
+```markdown
+Reference: [[Research#^key-finding]]
+```
+
+### Wiki-Links with Paths
+
+```markdown
+[[folder/subfolder/Note Name]]
+```
+
+Specify path when multiple notes share the same name.
+
+**Examples:**
+```markdown
+[[Work/Projects/Project Plan]]
+[[Personal/Projects/Project Plan]]
+```
+
+### Embedding Notes
+
+```markdown
+![[Note Name]]
+```
+
+Embed the entire content of another note.
+
+**Examples:**
+```markdown
+![[Meeting Template]]
+![[Quote Collection#Favorite Quotes]]
+```
+
+### Embedding Images
+
+```markdown
+![[image.png]]
+![[image.png|200]]
+![[image.png|200x100]]
+![[folder/image.png|Custom Alt Text|300]]
+```
+
+**Size Specifications:**
+- `|width` - Set width, maintain aspect ratio
+- `|widthxheight` - Set both dimensions
+- Add alt text before dimensions
+
+## Tags
+
+Flexible categorization and filtering system.
+
+### Basic Tags
+
+```markdown
+#tag
+#tag-name
+#tag_name
+```
+
+**Rules:**
+- Start with `#`
+- No spaces (use `-` or `_`)
+- Alphanumeric characters
+- Case-sensitive
+- Can appear anywhere in note
+
+**Examples:**
+```markdown
+#project #work #important
+
+This note is about #machine-learning concepts.
+
+Status: #in-progress
+```
+
+### Nested Tags
+
+```markdown
+#parent/child
+#parent/child/grandchild
+```
+
+Creates tag hierarchy.
+
+**Examples:**
+```markdown
+#project/work/client-a
+#project/personal/side-hustle
+#status/active
+#status/archived
+```
+
+**In Obsidian UI:**
+- Tags displayed as hierarchy
+- Filter by parent shows all children
+- Organize tags logically
+
+### Inline Tags
+
+Tags can appear anywhere in text:
+
+```markdown
+Discussed #meeting-notes with team about #q1-planning.
+
+#review-required
+```
+
+### Multi-Word Tags
+
+```markdown
+#multi-word-tag
+#multi_word_tag
+```
+
+Use hyphens or underscores, not spaces.
+
+## Frontmatter (YAML)
+
+Structured metadata at the start of notes.
+
+### Basic Frontmatter
+
+```markdown
+---
+title: Note Title
+author: Author Name
+date: 2024-01-15
+---
+
+# Note Content
+```
+
+**Rules:**
+- Must be at very start of file
+- Enclosed in `---` delimiters
+- YAML syntax
+- Key-value pairs
+
+### Common Fields
+
+```markdown
+---
+title: Document Title
+date: 2024-01-15
+tags:
+  - tag1
+  - tag2
+aliases:
+  - Alternative Name
+  - Shorthand
+author: John Doe
+status: draft
+---
+```
+
+### Array Values
+
+```markdown
+---
+tags:
+  - project
+  - important
+categories: [work, planning]
+---
+```
+
+Both syntaxes work (YAML list or inline array).
+
+### Nested Objects
+
+```markdown
+---
+metadata:
+  created: 2024-01-15
+  modified: 2024-01-20
+  version: 1.2
+project:
+  name: Project Alpha
+  status: active
+  team:
+    - Alice
+    - Bob
+---
+```
+
+### Obsidian-Specific Fields
+
+```markdown
+---
+aliases:
+  - Alt Name 1
+  - Alt Name 2
+tags:
+  - vault-tag
+cssclasses:
+  - custom-theme
+  - wide-page
+---
+```
+
+**Special Fields:**
+- `aliases` - Alternative names for wiki-links
+- `tags` - Tags (alternative to inline `#tags`)
+- `cssclasses` - Custom CSS classes for styling
+
+## Task Lists (Checkboxes)
+
+Extended checkbox syntax beyond standard markdown.
+
+### Standard Checkboxes
+
+```markdown
+- [ ] Unchecked task
+- [x] Completed task
+- [X] Completed task (capital X works too)
+```
+
+### Extended Checkbox Types
+
+```markdown
+- [ ] To do
+- [x] Done
+- [>] Forwarded/Rescheduled
+- [<] Scheduled
+- [-] Cancelled
+- [?] Question
+- [!] Important
+- [*] Star
+- ["] Quote
+- [l] Location
+- [b] Bookmark
+- [i] Information
+- [S] Amount/Money
+- [I] Idea
+- [p] Pro
+- [c] Con
+- [f] Fire
+- [k] Key
+- [w] Win
+- [u] Up
+- [d] Down
+```
+
+**Note:** Extended types require Obsidian or plugins. Rendered specially in Obsidian UI.
+
+### Nested Tasks
+
+```markdown
+- [ ] Parent task
+  - [ ] Subtask 1
+  - [x] Subtask 2
+  - [ ] Subtask 3
+    - [ ] Sub-subtask
+```
+
+## Callouts (Admonitions)
+
+Styled information blocks.
+
+### Basic Callout
+
+```markdown
+> [!note]
+> This is a note callout.
+
+> [!info]
+> This is an info callout.
+```
+
+### Callout Types
+
+```markdown
+> [!note]
+> Note content
+
+> [!abstract] / [!summary] / [!tldr]
+> Summary content
+
+> [!info] / [!todo]
+> Information
+
+> [!tip] / [!hint] / [!important]
+> Helpful tip
+
+> [!success] / [!check] / [!done]
+> Success message
+
+> [!question] / [!help] / [!faq]
+> Question content
+
+> [!warning] / [!caution] / [!attention]
+> Warning message
+
+> [!failure] / [!fail] / [!missing]
+> Error message
+
+> [!danger] / [!error]
+> Danger warning
+
+> [!bug]
+> Bug report
+
+> [!example]
+> Example content
+
+> [!quote] / [!cite]
+> Quoted text
+```
+
+### Callout with Title
+
+```markdown
+> [!note] Custom Title
+> Content goes here.
+
+> [!warning] Important Warning
+> This is critical information.
+```
+
+### Foldable Callouts
+
+```markdown
+> [!note]- Collapsed by default
+> Content hidden initially.
+
+> [!note]+ Expanded by default
+> Content visible initially.
+```
+
+### Nested Callouts
+
+```markdown
+> [!info] Outer callout
+> Information here.
+>
+> > [!warning] Nested callout
+> > Nested warning.
+```
+
+## Code Blocks
+
+### Basic Code Blocks
+
+````markdown
+```
+Plain code block
+```
+
+```javascript
+console.log("JavaScript code");
+```
+
+```python
+print("Python code")
+```
+````
+
+### With Line Numbers
+
+Obsidian doesn't natively support line numbers, but some plugins do.
+
+## Tables
+
+### Basic Tables
+
+```markdown
+| Column 1 | Column 2 | Column 3 |
+| -------- | -------- | -------- |
+| Row 1    | Data     | Data     |
+| Row 2    | Data     | Data     |
+```
+
+### Alignment
+
+```markdown
+| Left | Center | Right |
+| :--- | :----: | ----: |
+| L1   | C1     | R1    |
+| L2   | C2     | R2    |
+```
+
+### Tables with Links
+
+```markdown
+| Project | Status | Notes |
+| ------- | ------ | ----- |
+| [[Project A]] | #active | See [[Notes]] |
+| [[Project B]] | #done | Complete |
+```
+
+## Comments
+
+```markdown
+%%
+This is a comment.
+Multi-line comments are supported.
+%%
+
+Regular text. %% Inline comment %%
+```
+
+**Rules:**
+- Enclosed in `%%`
+- Not rendered in reading view
+- Can be inline or multi-line
+
+## Footnotes
+
+```markdown
+Here's a sentence with a footnote[^1].
+
+[^1]: This is the footnote content.
+
+Another reference[^note].
+
+[^note]: Named footnotes work too.
+```
+
+## Obsidian URI
+
+Link to open notes in Obsidian app:
+
+```markdown
+obsidian://open?vault=VaultName&file=NoteName
+
+[Open Note](obsidian://open?vault=MyVault&file=folder/note)
+```
+
+## Combining Syntax
+
+### Complex Examples
+
+```markdown
+---
+title: Project Plan
+tags:
+  - project
+  - planning
+status: active
+---
+
+# [[Projects|Project]]: Mobile App Redesign
+
+## Overview
+
+This project focuses on #ui-ux improvements. See [[Design System]] for details.
+
+## Tasks
+
+- [ ] Review [[Requirements#Functional|functional requirements]]
+- [x] Create [[Wireframes]]
+- [>] Schedule meeting with #stakeholders
+- [ ] Update [[Project Timeline]]
+
+## References
+
+![[Design Principles#Core Values]]
+
+> [!tip] Best Practice
+> Always link to [[Style Guide]] when implementing designs.
+
+## Related
+
+- [[Previous Projects#Mobile|Past mobile work]]
+- [[Team Members|Team]]
+
+#project/mobile #status/in-progress
+```
+
+## Best Practices
+
+1. **Use wiki-links liberally** - Create connections between related notes
+2. **Consistent tag hierarchy** - Use nested tags for organization (`#project/work/client`)
+3. **Frontmatter for metadata** - Structure data that's queried frequently
+4. **Aliases for flexibility** - Add aliases for common alternative names
+5. **Descriptive link text** - Use aliases when natural reading flow matters
+6. **Block links sparingly** - For specific references within longer notes
+7. **Comments for drafts** - Use `%%` for notes to self that shouldn't be published
+8. **Callouts for emphasis** - Highlight important information visually
+
+## Compatibility Notes
+
+- Standard markdown works everywhere
+- Wiki-links are Obsidian-specific (convert to regular links for export)
+- Extended checkboxes may need plugins outside Obsidian
+- Callouts are Obsidian-specific (render as blockquotes elsewhere)
+- Frontmatter is standard YAML (works in most markdown processors)
+- Comments (`%%`) are Obsidian-specific
+- Tags work in Obsidian; may be ignored elsewhere
+
+## See Also
+
+- [obsidian-cli Reference](./obsidian-cli-reference.md) - Command-line vault operations
+- [Note Templates](../assets/templates/) - Ready-to-use note structures