Oculus Common Usage Patterns

A practical guide for working with Oculus nodes - tested patterns that work.

Pattern 1: Creating a New Node

Basic node creation:

oculus create my-node-slug --title "My Node Title" --content "Initial content here"

Create from file:

oculus create my-node --from-file /path/to/content.md --no-prompt

With metadata:

oculus create my-node --title "My Node" --tag documentation --tag reference --author "Your Name"

Pattern 2: Reading Node Content

View current or specified node:

oculus look                    # View current node
oculus look my-node            # View specific node

Navigate to a node:

oculus goto my-node            # Navigate and view

Inspect structure:

oculus headers my-node         # List all section headers
oculus headers --plain         # Plain list for scripting
oculus tree my-node            # Show hierarchical structure
oculus tree --depth 3          # Control depth

Pattern 3: Adding New Sections to a Node

Append a new section:

echo "Content for new section" > /tmp/content.md
oculus poke my-node:"New Section Name" --file /tmp/content.md --mode append

Replace existing section:

oculus poke my-node:"Existing Section" --file /tmp/new-content.md --mode set

Prepend to section:

oculus poke my-node:"Section Name" --file /tmp/content.md --mode prepend

Pattern 4: Working with Structured Data

Create node with YAML configuration:

# My Configuration Node

## config

\`\`\`yaml
app_name: "MyApp"
version: "1.0.0"
settings:
  debug: true
  max_users: 100
\`\`\`

## description

This node contains app configuration.

Note: Direct manipulation of YAML values (e.g., poke config.version "2.0.0") is not currently working via standard CLI/MCP. To update YAML data, replace the entire section.

Pattern 5: Executable Nodes with Python

Create reactive node with executable Python:

# Status Dashboard

## config

\`\`\`yaml
refresh_interval: 60
enabled: true
\`\`\`

## status

\`\`\`python[execute=true]
import datetime

refresh = config.get("refresh_interval", 60)
is_enabled = config.get("enabled", False)

current_time = datetime.datetime.now().isoformat()
status_message = f"Status check at {current_time} - Refresh every {refresh}s"
\`\`\`

The Python fence can access YAML data from other sections via the config variable.

Pattern 6: Interactive TODO Lists (Virtual Fences)

Create a TODO list:

# Project Tasks

## Tasks [my-tasks]
- [ ] First task
- [ ] Second task
- [ ] Third task

Manipulate via execute commands:

oculus fence list my-node      # List all virtual fences
oculus execute my-tasks add --content "New task"
oculus execute my-tasks toggle --item 0

Pattern 7: Linking Nodes

Create directional links:

oculus link my-node north target-node
oculus link my-node --direction east --target related-node
oculus link my-node south detail-node --backlink  # Auto-creates reverse link

View connections:

oculus edges my-node

Pattern 8: Searching and Discovery

Search for nodes:

oculus search "keyword"        # Fuzzy search
oculus list                    # List all nodes
oculus list --source mcp       # Filter by source

Find by tag:

oculus find-tag documentation
oculus list-tags              # See all tags

Pattern 9: Editing Nodes

Open in editor:

export EDITOR=vim  # or your preferred editor
oculus edit my-node

Update from file:

oculus edit my-node --file /tmp/updated-content.md

Pattern 10: Node Metadata and Tagging

Add tags:

oculus add-tag my-node documentation
oculus add-tag my-node reference howto

View tags:

oculus tags my-node

Remove tags:

oculus remove-tag my-node old-tag

Common Gotchas

Issue: "Section not found" when poking

Solution: Use oculus headers my-node to see exact section names. Section names are case-sensitive and must match exactly (or use the slug format shown in headers).

Issue: Need to update a value in YAML

Current workaround: Replace the entire section content with updated YAML. Direct path-based updates (e.g., poke config.key value) are not currently functional.

Issue: Peek returns empty string

Explanation: The peek command behavior for prose sections is unclear in testing. Use oculus look or file reading for reliable content access.

Summary: Most Common Operations

Create a node:

oculus create slug --from-file /path/to/content.md --no-prompt

View a node:

oculus goto slug && oculus look

Add a section:

echo "New content" > /tmp/section.md
oculus poke slug:"Section Name" --file /tmp/section.md --mode append

Update a section:

echo "Updated content" > /tmp/section.md
oculus poke slug:"Section Name" --file /tmp/section.md --mode set

Link nodes:

oculus link source-node north target-node

Search:

oculus search "term"