leo-cub¶

leo-cub is an automation-safe Rust tool for reading, validating, browsing, and modifying Leo Editor outlines.

It treats a Leo outline as both a tree and a graph: a node's GNX identifies shared content, while a position identifies one occurrence in the outline. That distinction makes clones visible and makes scripted changes predictable.

Install it
Get the cub command from PyPI or build it with Cargo.

Open the quickstart outline
A working .leo file you read and act on node by node, right in the TUI.

Build your first outline
Create an outline, add a small tree, and inspect the result.

Understand the model
Learn how GNXs, positions, clones, and external files fit together.

Automate safely
Use compact inspection and transactional JSON operations from scripts or agents.

Script it with Rhai
Drive a Doc with cub run or @action bodies — cub's main path for custom behavior.

What it is good at¶

Inspecting .leo files without opening a graphical editor.
Validating outline structure in CI or pre-commit checks.
Importing source trees as @auto, @edit, or @clean nodes.
Applying a complete batch of edits atomically, with optional preconditions.
Browsing outlines in a small terminal UI.
Synchronizing supported external and thin files.

Status¶

This is an early project. The format support is deliberately conservative, so keep backups of important outlines and use --dry-run when a command offers it. The repository is the source of truth for implementation details and current limitations.