README.md

@@ -1,3 +1,15 @@
 # forge-tools
 
 Like `gh` and `tea`, but aspiring to be compatible with multiple forge types to avoid using different tools for each.
+
+## Usage
+
+`frg --help` will give you an overview of what's available!
+
+## Development
+
+This uses `uv` to manage dependencies; [make sure it's installed before proceeding](https://github.com/astral-sh/uv).
+
+### Direction
+
+The primary intention of this is to make a more hackable version of `gh`-like tooling for my own purposes. This is not aiming feature parity or production-level quality.

frg/cli.py

@@ -15,14 +15,35 @@ class CliContext(pydantic.BaseModel):
 @click.group()
 @click.pass_context
 def cli(ctx):
+    """
+    A command-line tool to interact with different kinds of code forges.
+    """
+
     config = get_configuration()
     git_context = get_git_context(domain_aliases=config.domain_aliases)
     ctx.obj = CliContext(git=git_context, config=config)
 
 
-@cli.command()
+@cli.group()
 @click.pass_obj
 def pr(ctx):
+    """Interacts with pull requests."""
+    pass
+
+
+@pr.command(name="create")
+@click.option(
+    "-w",
+    "--web",
+    type=bool,
+    is_flag=True,
+    help="Opens the pull-request page in the default browser.",
+)
+@click.pass_obj
+def create_pr(ctx, web: bool):
+    """Interacts with pull requests."""
+
+    if web:
         forgejo_browser.create_pull_request_via_web(
             head=ctx.git.current_branch,
             host=ctx.git.host,
@@ -34,15 +55,27 @@ def pr(ctx):
 @cli.group()
 @click.pass_obj
 def repo(ctx):
+    """Interacts with repositories"""
     pass
 
 
-@repo.command()
+@repo.command(name="view")
+@click.option(
+    "-w",
+    "--web",
+    type=bool,
+    is_flag=True,
+    help="Opens the repository page in the default browser.",
+)
 @click.pass_obj
-def view(ctx):
+def view_repo(ctx, web: bool):
+    """View the current repository."""
+    if web:
         forgejo_browser.view_repository_via_web(
             host=ctx.git.host, repo=ctx.git.repo_name, owner=ctx.git.repo_author
         )
+    else:
+        raise NotImplementedError("--web is the only mode supported.")
 
 
 def main():

pyproject.toml

@@ -1,8 +1,12 @@
 [project]
-name = "frg"
-version = "0.1.0"
-description = "Add your description here"
+name = "forge-tools"
+version = "0.0.0"
+description = "Homegrown CLI tooling for code forges."
+authors = [
+    {name="Marc Cataford", email="hello@karnov.club"}
+]
 readme = "README.md"
+license={ file = "LICENSE" }
 requires-python = ">=3.12"
 dependencies = [
     "click>=8.1.7",
@@ -11,6 +15,10 @@ dependencies = [
     "pyyaml>=6.0.2",
 ]
 
+[project.urls]
+homepage = "https://forge.karnov.club/marc/forge-tools"
+issues = "https://forge.karnov.club/marc/forge-tools/issues"
+
 [project.scripts]
 frg = "frg.cli:main"