leo-cub

leo-cub is an experimental Rust library and command-line tool for reading, validating, browsing, and modifying Leo Editor outlines.

The installed command is cub; the Rust library namespace is leo.

Screenshot

image

Why

Leo outlines are not ordinary XML trees. A GNX identifies shared vnode content, while an outline position identifies one occurrence of that vnode. Cloned nodes can therefore appear in several places. leo-cub keeps those concepts separate and exposes transactional operations intended for scripts and AI tools.

Current features

  • Parse and validate .leo XML outlines.
  • Preserve XML outside the rewritten <vnodes> and <tnodes> sections.
  • Represent clone identity separately from outline positions.
  • Apply atomic JSON operation batches with optional text preconditions.
  • Parse Leo 5 thin derived-file sentinels.
  • Reconstruct @file, @thin, and @file-thin hierarchies and bodies.
  • Resolve ancestor @path directives in the TUI.
  • Browse outlines with a small Ratatui interface.
  • Highlight node bodies with Syntect, using @language or source extensions.
  • Open a derived node's full source file at its sentinel line using $VISUAL or $EDITOR.

Install

The recommended installation method is uv:

uv tool install leo-cub

This installs the cub command. You can also use pip install leo-cub, or download the appropriate archive from the latest GitHub release.

Installation from source

From the repository root, install the cub command with Cargo:

cargo install --path .

TUI

cub tui outline.leo

The browser resolves external thin files in memory.

TUI keybindings

Browsing and display

Key Action
j, ↓ / k, ↑ Select next/previous node
l, →, Enter Expand selected node
h, ← Collapse selected node
Home / End Select the first/last visible node
PageUp / PageDown Scroll the selected node's body by one page
Ctrl-P Find a headline incrementally; use ↑/↓ to cycle matches
o Edit the node body in $VISUAL/$EDITOR; for derived nodes, open the real source at its sentinel
y Toggle syntax highlighting
? Show command help

Outline editing

Key Action
Ctrl-I or Tab Insert a new sibling and enter headline editing
Ctrl-H or Backspace Edit the selected headline
Ctrl-↑, Ctrl-↓ Move among siblings
Ctrl-←, Ctrl-→ Promote or demote the selected node
Ctrl-S Save outline changes
q or Esc Quit; press twice to discard unsaved changes

Headline editing

Key Action
Printable characters Append to the headline
Backspace Delete the previous character
Enter Accept the headline
Esc Cancel editing; a newly inserted node is removed

Use --no-derived to display only the hierarchy physically present in the .leo XML file.

For source navigation, cub recognizes common position arguments for Vim, Neovim, Nano, Emacs, VS Code, Microsoft Edit, Helix, and Kakoune. Other editors receive the file path without a line argument.

Headless commands

cub inspect outline.leo
cub validate outline.leo
cub sync outline.leo
cub sync outline.leo src/main.rs --dry-run
cub sync outline.leo --gnx ekr.20260811210000.1
cub diff before.leo after.leo
cub inspect-derived path/to/derived.py --summary
cub apply outline.leo operations.json --dry-run

An operation batch is a JSON object:

{
  "operations": [
    {
      "op": "set-body",
      "node": "ekr.20260811210000.1",
      "expected": "old body",
      "body": "new body"
    }
  ]
}

Operations are applied to a copy and committed only if the complete batch is valid. expected provides optimistic conflict detection for headline and body edits.

Status and safety

This project is early and the file format support is incomplete. In particular, it does not yet write thin derived files, dynamically interpret every @comment/@delims change, or fully reconstruct all doc-part forms. Keep backups and use --dry-run when testing write operations on important outlines.

The TUI overlays derived files without modifying either the outline or external source files. Derived descendants are read-only in the outline editor; use o to edit their full external source. Unsaved outline changes require a second q before they are discarded.

License

MIT

Project links

Data verified by PyPI on Aug 12, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.3.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for vivainio from gravatar.com vivainio

Credits

Author: Ville Vainio

GitHub Statistics

Data verified by PyPI on Aug 12, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

Apache Software License, MIT License (MIT OR Apache-2.0)

Requires

Python >=3.10

Tags

leo-editor outline cli tui automation

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

leo_cub-0.1.0-py3-none-win_amd64.whl (2.0 MB view details)

Uploaded Python 3Windows x86-64

leo_cub-0.1.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.3 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

leo_cub-0.1.0-py3-none-macosx_11_0_arm64.whl (2.1 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

leo_cub-0.1.0-py3-none-macosx_10_12_x86_64.whl (2.2 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

Details for the file leo_cub-0.1.0-py3-none-win_amd64.whl.

File metadata

  • Download URL: leo_cub-0.1.0-py3-none-win_amd64.whl
  • Upload date:
  • Size: 2.0 MB
  • Tags: Python 3, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for leo_cub-0.1.0-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 1036fcc74449b257ae503c3f7b860bc547a36e4e918ad4f50792a828d3197bd2
MD5 6e8de289d35e4611abeeb16968bbb18c
BLAKE2b-256 9071a5fb6aab3977b2eb694642a022752b81d394702a82b92e692273ef0b4dcf

See more details on using hashes here.

Provenance

The following attestation bundles were made for leo_cub-0.1.0-py3-none-win_amd64.whl:

Publisher: release.yml on vivainio/leo-cub

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file leo_cub-0.1.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for leo_cub-0.1.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 9cb82c47b5293aee829129f84598c97519ad911699e187b49a98739ec5688948
MD5 9cc0c23653df59063189f2acfc3f515b
BLAKE2b-256 18f7e87fa91a337b2e9506e1cc670dfdf6181597cedca644fa4a4387c53515a6

See more details on using hashes here.

Provenance

The following attestation bundles were made for leo_cub-0.1.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on vivainio/leo-cub

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file leo_cub-0.1.0-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for leo_cub-0.1.0-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 7c545da3efadb82915bd0a969f13eea69d2509e88c611f77269f10481bdb14a1
MD5 26e53b4f990fde433ce12347e33458b7
BLAKE2b-256 2d0072579468694d3226603314bb1343c2b7e280d81888665323a3ecb49c7e49

See more details on using hashes here.

Provenance

The following attestation bundles were made for leo_cub-0.1.0-py3-none-macosx_11_0_arm64.whl:

Publisher: release.yml on vivainio/leo-cub

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file leo_cub-0.1.0-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for leo_cub-0.1.0-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 137cbf26e3deff33ca92b97373632f091c24e357c4357f77880d6253af910342
MD5 dc2bbf1991ffe6bd5604a01ae4020974
BLAKE2b-256 16ad42bf1eb5532b26ff73c935abfdd813a4de247905f554910238ff6f1283ee

See more details on using hashes here.

Provenance

The following attestation bundles were made for leo_cub-0.1.0-py3-none-macosx_10_12_x86_64.whl:

Publisher: release.yml on vivainio/leo-cub

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.3.0

5 files

0.2.2

5 files

0.2.1

4 files

0.1.1

4 files

This release

0.1.0 This release

4 files

0.0.2

4 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page