Metadata-Version: 2.4
Name: Hearth-CLI
Version: 1.0.1
Summary: Local project and sprint awareness from the terminal
Author: Toshon Jennings
License-Expression: LicenseRef-Hearth-CLI-Proprietary-1.0
License-File: LICENSE
Keywords: cli,project-management,sprint,textual,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.3.3
Requires-Dist: textual>=0.85.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Hearth CLI — Project & Sprint Awareness System

Hearth CLI is a local project and sprint awareness tool for the terminal. It
keeps a YAML registry of active work, calculates a lightweight cognitive-load
signal, records context switches, and presents the same data through a Rich CLI
and a Textual dashboard.

Created by Toshon Jennings.

The PyPI distribution is named `hearth-cli`; the installed command is `hearth`.

## Install

Hearth CLI requires Python 3.11 or newer. Installing it as an isolated
command-line tool is recommended:

```bash
pipx install hearth-cli
```

or:

```bash
uv tool install hearth-cli
```

You can also install it into an existing Python environment:

```bash
python -m pip install hearth-cli
```

## First use

```bash
hearth add
```

```bash
hearth status
```

```bash
hearth dashboard
```

Hearth CLI starts with an empty registry. Its local data lives in
`~/.config/hearth/` by default. Set `HEARTH_DATA_DIR` to use another directory.

## Commands

- `hearth status` shows project health, sprint capacity, and priority actions.
- `hearth sprint` shows committed projects and cognitive-load guidance.
- `hearth switch <id>` records a context switch and updates the project date.
- `hearth add` registers a project interactively.
- `hearth add --from-json <json>` registers a project non-interactively.
- `hearth edit <id>` opens a project's YAML in `$EDITOR`.
- `hearth md` writes `PROJECTS.md` in the Hearth CLI data directory.
- `hearth md --output <path>` writes the report to a specific path.
- `hearth md --json` prints the registry as structured JSON.
- `hearth agent-link <id> <type> <path>` associates an agent log with a project.
- `hearth scan` discovers candidate repositories directly under your home and
  `~/projects` directories and asks before importing them.

Run `hearth --help` or `hearth <command> --help` for the complete interface.

## Data and privacy

Hearth CLI is local-first. Registry data is stored as plain YAML and
context-switch history is appended to a plain JSON Lines file. It does not
encrypt those files or send them to a remote service. Protect the data directory
with normal filesystem permissions and full-disk encryption if it contains
sensitive project information.

## Development

```bash
uv sync --extra dev
```

```bash
uv run pytest
```

```bash
uv build
```

## License

Hearth CLI is source-available proprietary software. Personal, educational, and
internal operational use is permitted with named credit. Reselling it, charging
for access to it, including it in a paid product or service, or otherwise
monetizing Hearth CLI requires a separate written commercial agreement with
Toshon Jennings. See [LICENSE](LICENSE) for the complete terms.
