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

Install the cub command from PyPI with pipx (recommended for command-line applications):

pipx install leo-cub

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

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
Ctrl-P Find a headline incrementally; use ↑/↓ to cycle matches
o Open the full external source file at the node sentinel
y Toggle syntax highlighting

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, Helix, and Kakoune. Other editors receive the file path without a line argument.

Headless commands

cub inspect outline.leo
cub validate outline.leo
cub diff before.leo after.leo
cub inspect-derived path/to/derived.py --summary
cub refresh-derived outline.leo 0 path/to/derived.py --dry-run
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.0.2-py3-none-win_amd64.whl (1.9 MB view details)

Uploaded Python 3Windows x86-64

leo_cub-0.0.2-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.0.2-py3-none-macosx_11_0_arm64.whl (2.1 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

leo_cub-0.0.2-py3-none-macosx_10_12_x86_64.whl (2.1 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: leo_cub-0.0.2-py3-none-win_amd64.whl
  • Upload date:
  • Size: 1.9 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.0.2-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 aa64847ec09349b11043f924b53d02c2e4ab0d3815fe53beb23e964cc13197bd
MD5 11a5afaa3a56726d804b6712a9e1027d
BLAKE2b-256 b7bb49c87f80571345570aa7e4aa2b88491dc354c0bd862b99efc0f420581365

See more details on using hashes here.

Provenance

The following attestation bundles were made for leo_cub-0.0.2-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.0.2-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for leo_cub-0.0.2-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 309111df3f5c3f01a0dbaadfe80602955b247060686d49c16b38efd19e5b5b99
MD5 6b728e99427054b13c9f5dd1cba699ff
BLAKE2b-256 c9e65a64834ba27f3c01361a5ed37eba2739456be27b495138f19137d38f08ae

See more details on using hashes here.

Provenance

The following attestation bundles were made for leo_cub-0.0.2-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.0.2-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for leo_cub-0.0.2-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 18ba67e33b95f10362098a54e6391acb13a9091b415f7c503b9b406f8c9032da
MD5 5b069975f6dca3309b36e44f9a0e008d
BLAKE2b-256 5f083ca5da3143fee1dbbae5f84440eb361e109be6f9494a12989b0f583ee541

See more details on using hashes here.

Provenance

The following attestation bundles were made for leo_cub-0.0.2-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.0.2-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for leo_cub-0.0.2-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 33d192bf5b7030d0e284bb5bbd10f463d2fafe3b2b6042e32bb49b1a427ecfb4
MD5 c19c5a9ecda41c07eefec2a2ba633ef1
BLAKE2b-256 e0a09ed3607563879a7f8ba242b08ccfb447a23e73cfb0babad00fb62dcd3b3c

See more details on using hashes here.

Provenance

The following attestation bundles were made for leo_cub-0.0.2-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

0.1.0

4 files

This release

0.0.2 This release

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