Repositories

Repositories tell peppy where to look for nodes. When you run peppy repo refresh, peppy walks every configured repository, finds peppy.json5 files, and builds an index of available nodes.

Out of the box, one repository is configured:

• The community hub (https://github.com/Peppy-bot/nodes_hub, tracked on main) — a curated collection of ready-to-use nodes.

Add your own local directory with peppy repo add /path/to/my/nodes so peppy can discover nodes you create locally.

Configuration files

Repository configuration lives in ~/.peppy/conf/:

File	Purpose
repositories.json5	Repositories to scan
excluded_repositories.json5	Repositories (or subdirectories) to skip

Both files are JSON5 arrays. Each entry has an id (auto-assigned if missing), a type, and source-specific fields:

repositories.json5

[
  { id: 1, type: "fs",  path: "/home/user" },
  { id: 2, type: "git", url: "https://github.com/Peppy-bot/nodes_hub", ref: "main" },
  { id: 3, type: "url", url: "https://example.com/packages" },
]

Source types

Type	Fields	Description
fs	path	A local directory. Peppy recursively walks it looking for peppy.json5 files.
git	url, ref (optional)	A git repository. Peppy shallow-clones it and scans for nodes. Use ref to pin a branch, tag, or commit.
url	url	An HTTP endpoint (not yet implemented).

Commands

List repositories

peppy repo list

Shows all discovered nodes grouped by the repository that provides them. Each group is headed by the repository’s display label (path for fs, url (ref: r) for git) followed by the node count and source kind, then lists each node’s name, tag, path, and available variants. Duplicate nodes (same name:tag provided by multiple repositories) are flagged so you can see which repository currently wins resolution.

Refresh the index

peppy repo refresh

Re-scans all configured repositories and rebuilds the node index. peppy repo update is accepted as an alias. During refresh, peppy:

• Reads repositories.json5 (creates it with defaults on first run).
• Skips any repository or path listed in excluded_repositories.json5.
• Walks local directories and shallow-clones git repositories.
• Reports each discovered node and excluded repository in real time.
• Caches results in ~/.peppy/cache/packages.json5.

When multiple repositories provide the same name:tag pair, the repository with the lower id takes priority. The duplicate is still recorded and shown in repo list but does not override the primary source.

Add a repository

peppy repo add <source> [--ref <tag-or-branch>] [--top]

Adds a new repository to repositories.json5. The source format is auto-detected:

# Local directory
peppy repo add /path/to/my/nodes

# Git repository
peppy repo add https://github.com/org/repo.git

# Git repository pinned to a branch or tag
peppy repo add https://github.com/org/repo.git --ref v2.0

# Plain URL
peppy repo add https://example.com/packages

# Give the new repo top priority (lower `id` than every existing entry)
peppy repo add /path/to/my/nodes --top

The --ref flag is only valid for git sources. By default the new repository is appended with id = max(existing ids) + 1, so it has the lowest priority among configured repositories; pass --top to assign it an id just below the current minimum, giving it the highest priority. The priority id decides which repository wins when several of them provide the same name:tag (see Refresh the index).

Remove a repository

peppy repo remove <id>

Removes a repository by its numeric ID (shown by peppy repo list). The repository index is automatically refreshed after removal.

Exclude a repository

peppy repo exclude <source> [--ref <tag-or-branch>]

Adds a source to excluded_repositories.json5. Excluded repositories are skipped during peppy repo refresh. You can exclude an entire repository or a specific subdirectory within a local repository:

# Exclude a whole git repository
peppy repo exclude https://github.com/org/repo.git

# Exclude a subdirectory of a local repository
peppy repo exclude /home/user/projects/private-nodes

Using a repository-indexed node

Once a node appears in peppy repo list, you can add it by its name:tag without supplying a path or URL — peppy resolves the source through the cached index at ~/.peppy/cache/packages.json5:

peppy node add uvc_camera:0.1.0

This is the shortest form of peppy node add. It works for any node provided by any repository listed in repositories.json5, including the default nodes_hub community repository. When several repositories provide the same name:tag, the resolution rule from repo refresh applies — the repository with the lower id wins.

Two constraints apply to this source shape:

• --ref is rejected. The git ref (if any) is pinned once in repositories.json5 when you register the repo, not per-add.
• Dependency-level variant overrides with --variant <dep_name>:<dep_tag>@<variant_name> are only valid when the source is a name:tag reference. With a local path or a direct git/http URL, use the per-node --variant at the source level instead.

If the node you want to add lives in a repository that is not in repositories.json5, keep using the full git URL or HTTP archive form shown in Sharing nodes.

Directory pruning

When scanning local and git repositories, peppy automatically skips the following directories:

• .git
• .peppy
• target
• node_modules
• .venv
• __pycache__