tapper

tapper

tapper is a CLI for working with KEGs (Knowledge Exchange Graphs). It provides two entrypoints:

• tap for repo, config, and node workflows
• kegv2 for project-keg focused workflows

Installation

Prerequisite: Go 1.26.0 or newer.

Recommendation: install using the newest release tag (currently v0.2.0).

Install binaries from the newest tag:

go install github.com/jlrickert/tapper/cmd/tap@v0.2.0
go install github.com/jlrickert/tapper/cmd/kegv2@v0.2.0

Precompiled binaries are also published on GitHub Releases: https://github.com/jlrickert/tapper/releases (use the newest tag).

If needed, add your Go bin directory to PATH:

export PATH="$(go env GOPATH)/bin:$PATH"

Verify installation:

tap --help
kegv2 --help

Set up shell completions:

# zsh (current session)
source <(tap completion zsh)
source <(kegv2 completion zsh)

# zsh (persist)
tap completion zsh > "${fpath[1]}/_tap"
kegv2 completion zsh > "${fpath[1]}/_kegv2"

Quick Start

Run the CLI:

tap --help

Initialize a project-local keg:

tap repo init tapper --project

Show merged repo configuration:

tap repo config

Configuration Quick Map

• User config: ~/.config/tapper/config.yaml
• Project config: .tapper/config.yaml
• Keg config: <keg-root>/keg

Documentation

Project docs live under docs/:

• Documentation Home
• Configuration Overview
• Architecture Overview
• CLI And Command Flow
• Service Layer
• Repository Layer
• Testing Architecture
• User Config
• Project Config
• Keg Config
• Resolution Order
• Configuration Examples
• Troubleshooting
• KEG Structure Patterns
• Minimum Keg Node
• Entity And Tag Patterns
• Domain Separation And Migration
• Example Keg Structures
• Markdown Style Guide

Config Precedence At A Glance

When no explicit keg target is provided, tapper resolves in this order:

1. defaultKeg
2. kegMap path match (pathRegex first, then longest pathPrefix)
3. fallbackKeg

Alias lookup then prefers explicit kegs entries, then discovered aliases from kegSearchPaths, then project-local alias fallback at ./kegs/<alias>.

Troubleshooting

For common errors such as no keg configured, keg alias not found, and discovery path issues, see docs/configuration/troubleshooting.md.

Repository Layout

• cmd/tap - tap entrypoint
• cmd/kegv2 - kegv2 entrypoint
• pkg/tapper - config, resolution, and init services
• pkg/keg - KEG primitives and repository implementation
• kegs/tapper - repository KEG content
• docs/ - end-user documentation