ro-crate-tui

A terminal user interface (TUI) for exploring RO-Crate archives interactively.

ro-crate-tui lets you open RO-Crate packages (local or remote) and navigate their entities, subcrates, and metadata with simple commands from a compact TUI — useful for inspecting RO-Crates without leaving the terminal.

Features

• Load RO-Crates from:
  • local folders containing ro-crate-metadata.json
  • .zip archives containing ro-crate-metadata.json
  • direct URLs to RO-Crate archives
  • DOIs resolving to Zenodo or similar repositories
• Browse and pretty-print crate metadata
• List subcrates, properties, and ids used in a crate
• Enter subcrates or folders and inspect nested crates
• Search across indexed crates (uses a crate index)
• Simple command palette with completion for ids and subcrates
• Lightweight, fast, and keyboard-driven

Built with

• Rust
• ratatui (terminal UI)
• rocraters / ro-crate libraries for RO-Crate parsing
• rocrate_indexer for indexing & search

Quickstart

Prerequisites:

• Rust toolchain (stable)
• cargo

Clone and build:

git clone https://github.com/arunaengine/ro-crate-tui.git
cd ro-crate-tui
cargo build --release

Or install locally with cargo:

cargo install --path .

Run the TUI:

cargo run --release

(or run the installed binary ro-crate-tui if you used cargo install)

Commands

While in the TUI, enter commands at the prompt. The primary commands are:

• load <url|path>
  Load an RO-Crate from a local path, a .zip archive, a direct URL, or a DOI that resolves to a crate archive.

• ls
  Show the full RO-Crate (pretty-printed JSON).

• ls sub
  List all subcrates in the current crate.

• ls ids
  List all ids used in the current RO-Crate.

• ls props
  List all properties used in the current RO-Crate.

• get <@id>
  Pretty-print JSON for the entity identified by @id.

• cd
  Enter a subcrate or folder.

• cd ..
  Return to the parent crate.

• cd /
  Return to the root crate in the session.

• pwd
  Print the current path (crate stack location).

• search
  Search the indexed crates for matching entities (uses the local crate index).

• help
  Show the help message with available commands.

If you enter an unknown command the help message is shown with usage hints.

Examples

Load a local crate (folder with ro-crate-metadata.json):

load /path/to/my-ro-crate/

Load a crate archive or remote crate:

load https://example.org/archives/my-ro-crate.zip
load https://zenodo.org/record/XXXXX (DOI URL resolving to an RO-Crate)

List subcrates:

ls sub

Inspect a specific entity by id:

get @dataset1

Change context into a subcrate:

cd my-subcrate-id
pwd

Search the index for an entity or term:

search genome

Indexing & Search

ro-crate-tui ships with an embedded crate index (via rocrate_indexer) that is used for fast lookups and search. When you import a crate with load, the crate is added to the local index to enable subsequent search queries and faster lookups across previously loaded crates.

The index is stored using the library's default location/mechanism (see crate index docs for details).

Development

• Format and check:

cargo fmt
cargo clippy

• Run the app during development:

cargo run

• Run tests (if any):

cargo test

Contributions are welcome — please open issues and pull requests on the repository.

Troubleshooting

• If the terminal gets into a corrupted state due to a crash, running reset or closing and reopening the terminal usually restores it. The app attempts to restore terminal state on normal exit.
• If load fails for a remote URL, ensure the URL is reachable and points to a valid RO-Crate archive or ro-crate-metadata.json.
• For encoding or JSON errors, verify the crate's ro-crate-metadata.json is valid JSON and conforms to the RO-Crate specification.

License

See the repository's LICENSE file for license information.

Acknowledgements

• This project builds on the rocraters and rocrate_indexer crates for RO-Crate handling and indexing.
• Terminal UI based on ratatui.