Metadata-Version: 2.3
Name: porthub
Version: 0.0.4
Summary: 
Author: narumi
Author-email: narumi <toucans-cutouts0f@icloud.com>
Requires-Dist: mcp[cli]>=1.26.0
Requires-Dist: typer>=0.24.1
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# 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:

```bash
uv tool install -U porthub
```

Or run directly without installation:

```bash
uvx porthub --help
```

For local development in this repository:

```bash
uv sync
```

You can run commands either through `uv`:

```bash
uv run porthub --help
```

Or through the installed script:

```bash
porthub --help
```

## Usage

Set Markdown content from an inline string:

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

Set Markdown content from a file:

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

Set Markdown content from stdin:

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

Get content by exact key:

```bash
porthub get python/typer
```

Search by key or content (case-insensitive):

```bash
porthub search typer
```

Search by key only:

```bash
porthub search typer --key-only
```

Search by content only:

```bash
porthub search typer --content-only
```

Limit search results:

```bash
porthub search typer --limit 10
```

List all keys:

```bash
porthub list
```

Use a custom storage root for any command:

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

Or set a default storage root via environment variable:

```bash
export PORTHUB_HOME=./tmp-porthub
porthub list
```

## Skills

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

- Install (method 1):

```bash
npx skills add narumiruna/porthub
```

- Install (method 2):

```bash
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`
