porthub 0.0.4

No project description provided

PortHub

PortHub is a local-first CLI tool for storing and retrieving Markdown context by hierarchical keys.

MVP Scope

• Local filesystem storage only (default: ~/.porthub; configurable via PORTHUB_HOME or --root).
• CLI-only workflows.
• Four commands: set, get, search, list.
• Exact match for get.
• Case-insensitive substring match for search (with optional key-only/content-only modes).

Install

Install the CLI tool:

uv tool install -U porthub

Or run directly without installation:

uvx porthub --help

For local development in this repository:

uv sync

You can run commands either through uv:

uv run porthub --help

Or through the installed script:

porthub --help

Usage

Set Markdown content from an inline string:

porthub set python/typer "# Typer\nCLI framework for Python"

Set Markdown content from a file:

porthub set python/typer --file ./notes/typer.md

Set Markdown content from stdin:

cat ./notes/typer.md | porthub set python/typer --stdin

Get content by exact key:

porthub get python/typer

Search by key or content (case-insensitive):

porthub search typer

Search by key only:

porthub search typer --key-only

Search by content only:

porthub search typer --content-only

Limit search results:

porthub search typer --limit 10

List all keys:

porthub list

Use a custom storage root for any command:

porthub --help
porthub list --root ./tmp-porthub
porthub get python/typer --root ./tmp-porthub

Or set a default storage root via environment variable:

export PORTHUB_HOME=./tmp-porthub
porthub list

Skills

This repository includes a local skill for package-documentation retrieval workflows:

• Install (method 1):

npx skills add narumiruna/porthub

• Install (method 2):

npx ctx7 skills install narumiruna/porthub

• Skill source: skills/porthub/SKILL.md

Key Rules

A key is valid only when all rules pass:

1. It is not empty after trimming spaces.
2. It does not start or end with /.
3. It does not contain //.
4. It does not contain ...
5. It does not end with .md.

Error Behavior

• Validation failures return non-zero exit code.
• get returns non-zero when a key is not found.
• search returns empty output with exit code 0 when no match exists.
• search returns non-zero when --key-only and --content-only are both provided.
• search returns non-zero when --limit is not greater than 0.
• set returns non-zero unless exactly one content source is provided:
  • positional value
  • --file
  • --stdin