pinstar

A terminal-based diagram editor for Obsidian Canvas, Mermaid, Graphviz DOT, and PlantUML files. Built with Rust and the Ratatui framework.

Disclaimer

pinstar is a sub-project of clin-rs. Separated for standalone use/testing. The project evolves as a module inside the clin-rs project for now in the future once it's matured enough both versions will be merged and unified together so any future updates inside one or other will be available on each other. Until then the project is in semi-maintanence mode. Reported bugs or features will be looked into for implementation.

If you want to have newest features/changes about this project check out clin-rs. Note that flowchart support does not exists in clin-rs though, for now.

Usage

pinstar <FILE>.canvas|.md|.dot|.puml

If the file doesn't exist, pinstar creates an empty diagram in the detected format.

Supported Formats

Features

• Multi-Format Support: Read, write, and edit Canvas, Mermaid, DOT, and PlantUML diagrams
• Spec Compliance: Full Obsidian .canvas JSON support (text, file, link, and group nodes)
• Interactive TUI: Pan, zoom, and navigate node relations inside the terminal using ratatui
• Inline Editing: Built-in node content editing via ratatui-textarea
• Node Shapes: Rectangle, Diamond, Circle, Cylinder, Stadium (flowchart formats)
• Edge Styles: Solid, Dashed, Dotted
• Color Presets: 10 colors (Default, Red, Orange, Yellow, Green, Cyan, Blue, Purple, Magenta, White)
• Hierarchical Layout: Automatic layout for Mermaid, DOT, and PlantUML with 4 orientations
• Undo/Redo: Full undo/redo stack
• Raw Editor: Split-pane JSON/text editor with live sync
• External Editor: Edit node content or entire diagrams in your $EDITOR
• Image Rendering: Terminal-native image previews for Canvas file nodes (requires Kitty/Sixel/iTerm2 support)

Keybindings

Navigation

Editing

Connections

Global

Mouse Controls

Node & Edge Types

Nodes

• Text — Standard text node with configurable shape and color
• File — Embedded file reference (Canvas only)
• Link — Embedded URL reference (Canvas only)
• Group — Container for grouping child nodes (Canvas only)

Shapes (flowchart formats)

Rectangle · Diamond · Circle · Cylinder · Stadium

Edge Styles

Solid · Dashed · Dotted

Orientations (flowchart)

Top-Down · Left-Right · Right-Left · Bottom-Up

Colors (10 presets)

Default · Red · Orange · Yellow · Green · Cyan · Blue · Purple · Magenta · White

Known Issues / Compatibility

• Node titles may not be preserved when editing Obsidian Canvas files (Obsidian uses a different title format)
• Diamond and Stadium shapes not available in PlantUML
• Color editing not available in Mermaid or PlantUML syntaxes
• Groups only supported in Canvas format

Technical Stack

• Framework: Ratatui v0.30 for terminal rendering
• Terminal: Crossterm v0.29 for cross-platform input
• Serialization: Serde JSON for Canvas spec parsing
• Text Editing: ratatui-textarea for inline editing
• Parsing: regex for multi-format parsers
• Identifiers: uuid crate for RFC 4122 compliant node tracking

Installation

Pre-built Packages

Pre-compiled binaries and system packages (.deb, .rpm, PKGBUILD) for Debian/Ubuntu, Fedora/RHEL, and Arch Linux are available on the GitHub Releases page.

Via Cargo

cargo install pinstar

Building from Source

Requires Rust toolchain (MSRV 1.85).

cargo build --release

Library Usage

pinstar can be embedded as a library in other Rust projects (e.g. clin-rs). See API.md for the full integration guide covering state management, input handling, rendering, data model, and format support.