opindex 0.1.3

Linux-first command snippet manager for markdown notes

OpIndex

OpIndex is a Linux-first command memory tool for markdown notes. It parses reusable command blocks from your notes, lets you search them from a launcher, and copies the selected command to the clipboard.

The current UI is optimized for rofi on X11, but the note format and CLI are useful independently of the launcher.

What it does

• searches reusable commands from markdown files
• organizes sources into named workspaces
• supports quick workspace switching from a launcher
• shows source-document context while browsing
• lints notes against the OpIndex authoring standard
• copies selected commands to the clipboard

Platform

OpIndex currently targets Linux. It expects one of:

• rofi for the interactive launcher flow
• xclip, xsel, or wl-copy for clipboard access

Installation

System dependencies

Debian or Ubuntu:

sudo apt install rofi xclip

Wayland clipboard support:

sudo apt install wl-clipboard

Python package

pipx install opindex

This installs the opindex command.

For local development from this repository:

pipx install .

Quick start

Create a config:

opindex --create-config

Run the selector in the default workspace:

opindex

Open the workspace picker first:

opindex --workspace-menu

Search a specific workspace:

opindex --workspace notes

Search all workspaces:

opindex --all

Browse by workspace, then document:

opindex --browse

Configuration

The config file lives at:

~/.config/opindex/config.yaml

Example:

default_workspace: notes

workspaces:
  notes:
    directories:
      - "~/notes/commands"
    files: []
    recursive: true
    file_patterns:
      - "*.md"
      - "*.markdown"

  cheatsheets:
    directories:
      - "~/notes/reference"
    files: []
    recursive: true
    file_patterns:
      - "*.md"
      - "*.markdown"

rofi:
  max_lines: 15
  prompt: "Commands"
  window_width: 60
  element_height: 2

cache:
  enabled: true
  directory: null

substitute_variables: false
variables: {}

Markdown format

Minimal parseable format:

# Azure CLI

## Login with device code
```bash
az login --use-device-code
```

OpIndex parses:

• # as the category
• ## as the searchable task heading
• fenced code blocks as command content

Supported command block languages:

• empty language
• bash
• sh
• shell
• powershell
• ps1
• cmd
• bat
• batch

For the stricter durable-note format, see:

• docs/opindex-note-standard.md
• docs/opindex-agent-skill-spec.md

Linting

Lint a specific note:

opindex --lint-files path/to/file.md

Lint the selected workspace sources:

opindex --lint-files

CLI

Common commands:

opindex --help
opindex --list-workspaces
opindex --list-files
opindex --list-commands
opindex --clear-cache
opindex --config-path

Development

Enter the dev shell:

direnv allow

Or without direnv:

nix develop

Run tests:

pytest -q

Run the parser against a file:

python -m cmd_manager.parser test_data/sample.md

Lint a note during development:

./opindex --lint-files test_data/sample.md

Publishing

Release notes for maintainers:

• PUBLISHING.md

Releases publish to PyPI from pushed tags in the form v<semver>.

License

MIT