A terminal UI application for exploring and visualizing Backstage software catalog entities.
- Tree View: Hierarchical visualization of entities organized by Domain → System → Component
- Entity Details: View metadata, ownership, lifecycle, tags, links, annotations, and source file information
- Group Hierarchy: Display group parent/child relationships and member lists for organizational structure
- Schema Validation: Automatically validates entities against the official Backstage JSON Schema
- Relationship Graph: Visualize how entities relate to each other (dependencies, APIs, ownership), and jump straight to a related entity
- Documentation Browser: View TechDocs and ADR markdown files directly in the terminal
- Reference Validation: Highlights missing or invalid entity references
- Search: Incremental
/search across name, title, description, kind, owner, and tags, with field-scoped queries (owner:team-a,tag:backend,kind:component,system:…,domain:…) - Live Reload: Automatically re-reads the catalog when files change on disk (or press
rto reload manually), preserving your expansion and selection
Prebuilt binaries are published for macOS (Intel + Apple Silicon), Linux (x86_64), and Windows (x86_64) with every release. Pick whichever method fits your platform.
This repository doubles as a Homebrew tap, so no separate tap repo is needed:
brew install https://raw.githubusercontent.com/grahambrooks/bsv/main/Formula/bsv.rbOr tap it for brew upgrade support:
brew tap grahambrooks/bsv https://github.com/grahambrooks/bsv
brew install bsv# curl
curl -fsSL https://raw.githubusercontent.com/grahambrooks/bsv/main/install.sh | sh
# wget
wget -qO- https://raw.githubusercontent.com/grahambrooks/bsv/main/install.sh | shThe script auto-detects your OS/architecture, verifies the download checksum, and
installs to ~/.local/bin (or /usr/local/bin when writable). Override with
BSV_VERSION or BSV_BIN_DIR.
scoop bucket add bsv https://github.com/grahambrooks/bsv
scoop install bsvirm https://raw.githubusercontent.com/grahambrooks/bsv/main/install.ps1 | iexInstalls to %LOCALAPPDATA%\Programs\bsv and adds it to your user PATH.
Grab the archive for your platform from the
releases page, extract it, and put
the bsv binary on your PATH. Each archive ships with a .sha256 checksum file.
git clone https://github.com/grahambrooks/bsv.git
cd bsv
cargo install --path .Requires Rust 1.70 or later.
# Scan current directory for catalog-info.yaml files
bsv
# Scan a specific directory
bsv /path/to/backstage/catalog
# Load a specific catalog file
bsv /path/to/catalog-info.yamlbsv can validate a catalog without launching the UI, which is useful in CI
pipelines:
# Validate: prints schema errors and broken references, exits non-zero on failure
bsv --validate /path/to/catalog
# Dump the parsed catalog as JSON (for piping into jq, etc.)
bsv --json /path/to/catalog--validate reports both JSON Schema violations and references that don't
resolve to a known entity (owner, system, domain, dependsOn, providesApis,
consumesApis, memberOf, group parent/children, …), and exits with a
non-zero status when any problem is found.
The Tab key moves focus between the entity tree (left) and the detail/graph
panel (right). When the panel is focused, the navigation keys scroll its
contents instead of moving the tree selection — useful for long entities or the
raw YAML view. The mouse scroll wheel scrolls whichever pane the cursor is over.
In the relationship graph (g), focus the panel with Tab, use ↑/↓ to
highlight a related entity, and press Enter to jump to it in the tree — letting
you walk the dependency graph hop by hop.
| Key | Action |
|---|---|
Tab |
Switch focus between tree and detail panel |
↑ / k |
Move up (tree) / scroll up (panel) |
↓ / j |
Move down (tree) / scroll down (panel) |
PgUp / PgDn |
Scroll up / down a page |
Home / End |
Jump to first / last item (or top/bottom of panel) |
← / h |
Collapse node, or jump to parent if already collapsed |
→ / l / Enter |
Expand node |
e |
Expand all nodes |
c |
Collapse all nodes |
/ |
Start search |
Esc |
Clear search / return focus to tree |
g |
Toggle graph view |
y |
Toggle raw YAML view of the selected entity |
d |
Open documentation browser (when available) |
r |
Reload catalog |
x / X |
Jump to next / previous entity with validation errors |
? |
Show keyboard shortcut help |
q |
Quit |
| Key | Action |
|---|---|
↑ / k |
Navigate up / Scroll up |
↓ / j |
Navigate down / Scroll down |
Enter |
Open selected file |
PgUp / PgDn |
Page scroll |
Esc |
Back to file list / Close browser |
q |
Quit |
bsv supports all standard Backstage entity types:
- Component - Individual software components (services, websites, libraries)
- API - API definitions (REST, GraphQL, gRPC)
- Resource - Infrastructure resources (databases, storage, queues)
- System - Collection of related components and APIs
- Domain - Business domain grouping systems
- Group - Teams and organizational units
- User - Individual team members
- Location - Catalog file locations
Backstage uses a specific format for entity references:
[<kind>:][<namespace>/]<name>
Examples:
component:default/my-service- Fully qualifiedmy-service- Name only (kind and namespace inferred from context)group:platform-team- Kind specified, namespace inferred
bsv displays inferred parts in [brackets] with dim styling to distinguish them from explicitly specified values.
bsv validates entity references and provides visual feedback:
- Green: Reference exists in catalog
- Yellow: Reference not found (might be external or missing)
- Red: Unknown entity kind
bsv automatically validates all entities against the official Backstage catalog JSON Schema. Validation errors are displayed:
- In the tree view: Entities with validation errors are shown in red with a ⚠ indicator and error count
- In the details panel: Full validation error details including field path and error message
Common validation errors include:
- Missing required fields (e.g.,
owner,lifecycle,typefor Components) - Invalid field types or values
- Missing
apiVersionorkind - Empty or invalid entity names
This helps ensure your catalog files comply with Backstage standards before deployment.
bsv reads standard Backstage catalog-info.yaml files:
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: my-service
title: My Service
description: A microservice that does things
tags:
- python
- backend
spec:
type: service
lifecycle: production
owner: group:platform-team
system: my-system
dependsOn:
- component:other-service
providesApis:
- my-apiMultiple entities can be defined in a single file using YAML document separators (---).
# Run in development mode
cargo run
# Run with a test catalog
cargo run -- testdata/large-catalog.yaml
# Run tests
cargo test
# Check for linting issues
cargo clippy
# Format code
cargo fmtbsv can browse TechDocs and ADR documentation directly in the terminal. When an entity has documentation annotations, press d to open the documentation browser.
backstage.io/techdocs-ref: TechDocs reference (e.g.,dir:.ordir:./docs)backstage.io/adr-location: ADR location (e.g.,docs/adr)
The browser provides:
- File list navigation for markdown files
- Basic markdown syntax highlighting (headers, lists, code blocks, links)
- Scrollable document viewing
src/
├── main.rs # Entry point and event loop
├── app.rs # Application state management
├── docs.rs # Documentation browser and TechDocs/ADR support
├── entity.rs # Entity types and reference parsing
├── parser.rs # YAML file discovery and parsing
├── tree.rs # Tree data structure
├── graph.rs # Relationship graph extraction
├── validator.rs # JSON Schema validation
└── ui.rs # Terminal UI rendering
MIT License - see LICENSE for details.
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.