Metadata-Version: 2.5
Name: mforge
Version: 0.1.4
Summary: Sync issues and pull requests from your git forges into a local store, then browse and manage them offline from the CLI or an interactive TUI.
Project-URL: Homepage, https://codeberg.org/fleax/mforge
Project-URL: Issues, https://codeberg.org/fleax/mforge/issues
Author-email: fleax <ybonatakis@proton.me>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Requires-Python: >=3.13
Requires-Dist: fastapi>=0.141.1
Requires-Dist: httpx>=0.28.1
Requires-Dist: keyring>=25.7.0
Requires-Dist: pydantic-settings>=2.14.2
Requires-Dist: textual>=8.2.8
Requires-Dist: typer>=0.27.1
Description-Content-Type: text/markdown

# mforge

![Status: ](https://img.shields.io/badge/status-blue)
![License: GPL--3.0--or--later](https://img.shields.io/badge/license-GPL--3.0--or--later-blue)

> **Work in progress.** Early development — several commands listed below are not
> implemented yet, and the CLI surface may change without notice between releases.

Sync issues and pull requests from your git forges into a local store, then browse
and manage them offline from the CLI or an interactive TUI.

mforge keeps a local SQLite mirror of the repositories you care about. Once synced,
listing and reading issues and pull requests needs no network round-trip — useful on
a slow connection, on a plane, or when you simply do not want to wait on a web UI.

## Install

```bash
uv tool install mforge
```

or with pip:

```bash
pip install mforge
```

Requires Python 3.13 or newer.

The package is called `mforge` and installs two identical commands: `mf` (short,
used throughout these docs) and `mforge`.

## Authentication

mforge reads your forge token with the following order:
- from the OS [keyring](https://pypi.org/project/keyring/ "Make sure that there is installed in your system: ex: zypper se python314-keyring"),
- falling back to environment variables when no keyring entry is present (headless machines, CI).

Store it in the keyring under service `mforge`:

```bash
keyring set mforge github
keyring set mforge forgejo:codeberg.org      # Codeberg
keyring set mforge forgejo:git.example.org   # a self-hosted Forgejo
```

Or export it instead:

```bash
export GH_TOKEN="your-token"              # or MFORGE_GITHUB_TOKEN
export CODEBERG_TOKEN="your-token"        # or MFORGE_CODEBERG_TOKEN
export MFORGE_FORGEJO_TOKEN="your-token"  # any other Forgejo instance
```

### Supported forges

| Forge | Provider key | Notes |
| --- | --- | --- |
| GitHub | `github` | |
| Codeberg | `codeberg` | An alias for `forgejo` with host `codeberg.org` |
| Forgejo | `forgejo` | Any instance; pass `--host` for a self-hosted one |

Forgejo credentials are keyed per **instance**, not per forge — `forgejo:codeberg.org` is a
different credential from `forgejo:git.example.org`. A token for one instance is not a token for
another, so they are never interchanged.

## Quick start

```bash
mf repo add owner/name       # track a repository (GitHub by default)
mf sync                      # pull issues and PRs into the local store
mf pr list                   # list what you fetched
mf ui                        # browse everything in the TUI
```

The TUI is the complete read surface; the CLI currently exposes a subset (see
[Commands](#commands)).

Tracking a repository on another forge:

```bash
mf repo add fleax/mforge --provider-key codeberg
mf repo add team/thing --provider-key forgejo --host git.example.org
```

## Commands

### Top level

| Command | Description |
| --- | --- |
| `mf sync [SLUG]` | Sync all tracked repositories, or just `SLUG` |
| `mf ui` | Open the interactive TUI |
| `mf version` | Print the installed version |

### Repositories

| Command | Description |
| --- | --- |
| `mf repo add SLUG [--provider-key KEY] [--host HOST]` | Track a repository |
| `mf repo list [--provider-key KEY]` | List tracked repositories |
| `mf repo remove REPO` | Stop tracking a repository |

### Issues

Placeholders only — these print a message and read nothing from the store. Use `mf ui` to
browse issues, or `mf pr list` for change requests.

| Command | Status |
| --- | --- |
| `mf issues show-issues-all` | Stub |
| `mf issues show-issue ID` | Stub |
| `mf issues comment ID` | Stub |
| `mf issues refresh` | Stub |

### Pull requests

| Command | Description |
| --- | --- |
| `mf pr list [--provider-key KEY] [--me]` | List stored pull requests |
| `mf pr view` | Stub |

## Global options

| Option | Description |
| --- | --- |
| `--db PATH` | Path to the SQLite store (default `mforge.db`) |

The database location resolves as `--db` > `DB_PATH` in `.env` > `mforge.db` in the
working directory.

A new release upgrades the store automatically on first use and first saves a copy as
`<store>.v<N>.bak` (only the latest is kept). See `docs/store.md`.

## License

GPL-3.0-or-later. See [LICENSE](LICENSE).
