gitfred 0.1.0__py3-none-any.whl

gitfred-0.1.0.dist-info/METADATA

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: gitfred
+Version: 0.1.0
+Summary: GitFred CLI — deploy GitHub repositories as live web apps from your terminal.
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.15
+Description-Content-Type: text/markdown
+
+# gitfred
+
+The GitFred CLI: deploy GitHub repositories as live web apps at `https://<slug>.gitfred.com` from your terminal — or from an AI coding agent.
+
+```bash
+uv tool install gitfred        # or: pipx install gitfred
+gitfred login                  # browser-approval sign-in
+gitfred app create --repo you/your-repo --publish
+gitfred deploy 42 --follow
+```
+
+Every command supports `--json` for machine-readable output and uses meaningful exit codes (`0` ok, `2` usage, `3` auth, `4` not found, `5` quota, `6` deploy failed, `7` timeout), so agents can drive it non-interactively with `GITFRED_TOKEN`.
+
+Docs: https://app.gitfred.com/docs/cli

gitfred-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+gitfred_cli/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+gitfred_cli/client.py,sha256=fvTH6iljCqTiXIxGPKwznTTFHps2VGpgNcpEOZLsIQg,4380
+gitfred_cli/config.py,sha256=hI_cSHpkDZ5Af8rDPpYv_cV8vwLmzRX94dFgH5-9-jQ,1189
+gitfred_cli/helpers.py,sha256=s0yzzxUfth2Nc_7lxhjpNbL3YapBUTMsbvqPTMGOUBw,2019
+gitfred_cli/main.py,sha256=9ySm02WQxgT0Ib5z_80Ee501oiAbMGoL5MW2eT0rhVk,1891
+gitfred_cli/output.py,sha256=h1DAlVRGlOMJHXHx93gBNpyww2qSSPRMc5G2wt_YcOo,1356
+gitfred_cli/state.py,sha256=GjP1rBWSZ7MlNMVJ4AkghIEVH--m27Q7HMHHB6cwSGo,1258
+gitfred_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gitfred_cli/commands/addon.py,sha256=ZDgiz7gSLXZJbGOjz4myPzbMIqDz7mtHlutBjJKqJyg,1274
+gitfred_cli/commands/app.py,sha256=UqGE_BPsfGt0wcduQz62uk7NyGq3plWXLYj1tE0tz_k,5750
+gitfred_cli/commands/auth.py,sha256=ADNHvttJy-qRQMVwnbKOMDPJKS7Mp2FT8ot8vc7qTHE,3158
+gitfred_cli/commands/deploy.py,sha256=k_fzOBmtlG13W6GigQWDZWlduIGCdkVtVPAl9M22Cjg,5175
+gitfred_cli/commands/env.py,sha256=d6MWM_zSglBrtpXUl8nX4ULHsfQEegT45zYq2cpcoxA,2322
+gitfred_cli/commands/repo.py,sha256=o8Kv011wIXgRfRAmRfluxNmEhvYZ1C_wwLFijNVVRAs,2043
+gitfred-0.1.0.dist-info/METADATA,sha256=w5ixnmN2PHH5ulkNQqGh0Wo1oJpN7aJVQHXgIgyG2Ao,943
+gitfred-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+gitfred-0.1.0.dist-info/entry_points.txt,sha256=SXqT2IdmiWZ6zxW9CsOtCMZAM3Cpr39fC2pHAcnAUk4,49
+gitfred-0.1.0.dist-info/RECORD,,

gitfred-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

gitfred-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gitfred = gitfred_cli.main:app

gitfred_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

gitfred_cli/client.py

@@ -0,0 +1,130 @@
+"""HTTP client for the GitFred /api/v1 contract, plus the SSE log iterator."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from typing import Any
+
+import httpx
+
+from . import __version__
+from .output import EXIT_AUTH, EXIT_ERROR, EXIT_NOT_FOUND, EXIT_QUOTA
+
+
+class ApiError(Exception):
+    def __init__(self, status: int, message: str, detail: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.detail = detail
+
+    @property
+    def exit_code(self) -> int:
+        if self.status in (401, 403):
+            return EXIT_AUTH
+        if self.status == 404:
+            return EXIT_NOT_FOUND
+        if self.status == 429:
+            return EXIT_QUOTA
+        return EXIT_ERROR
+
+
+class Client:
+    """Thin wrapper around httpx bound to ``{api_url}/api/v1`` with bearer auth."""
+
+    def __init__(
+        self,
+        api_url: str,
+        token: str | None = None,
+        timeout: float = 30.0,
+        transport: httpx.BaseTransport | None = None,
+    ):
+        headers = {"User-Agent": f"gitfred-cli/{__version__}"}
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        self._http = httpx.Client(
+            base_url=api_url.rstrip("/") + "/api/v1",
+            headers=headers,
+            timeout=timeout,
+            transport=transport,
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any = None,
+        params: dict | None = None,
+        expect_json: bool = True,
+    ) -> Any:
+        try:
+            res = self._http.request(method, path, json=body, params=params)
+        except httpx.HTTPError as exc:
+            raise ApiError(0, f"cannot reach the GitFred API: {exc}") from exc
+        if res.status_code >= 400:
+            raise self._error(res)
+        if not expect_json or res.status_code == 204 or not res.content:
+            return None
+        return res.json()
+
+    def get(self, path: str, **kw: Any) -> Any:
+        return self.request("GET", path, **kw)
+
+    def post(self, path: str, **kw: Any) -> Any:
+        return self.request("POST", path, **kw)
+
+    def put(self, path: str, **kw: Any) -> Any:
+        return self.request("PUT", path, **kw)
+
+    def patch(self, path: str, **kw: Any) -> Any:
+        return self.request("PATCH", path, **kw)
+
+    def delete(self, path: str, **kw: Any) -> Any:
+        return self.request("DELETE", path, **kw)
+
+    def status_of(self, method: str, path: str, *, body: Any = None) -> int:
+        """Like request() but returns the status code, never raising on 4xx.
+        Used by the device-auth poll loop where 202 is a normal answer."""
+        res = self._http.request(method, path, json=body)
+        if res.status_code >= 400:
+            raise self._error(res)
+        return res.status_code
+
+    def sse(self, path: str, params: dict | None = None) -> Iterator[tuple[str, dict]]:
+        """Yield ``(event, data)`` pairs from an SSE endpoint until it closes."""
+        with self._http.stream(
+            "GET", path, params=params, timeout=httpx.Timeout(30.0, read=90.0)
+        ) as res:
+            if res.status_code >= 400:
+                res.read()
+                raise self._error(res)
+            event = "message"
+            data_lines: list[str] = []
+            for line in res.iter_lines():
+                if line.startswith("event:"):
+                    event = line[6:].strip()
+                elif line.startswith("data:"):
+                    data_lines.append(line[5:].strip())
+                elif line == "" and data_lines:
+                    try:
+                        yield event, json.loads("\n".join(data_lines))
+                    except ValueError:
+                        pass
+                    event = "message"
+                    data_lines = []
+
+    @staticmethod
+    def _error(res: httpx.Response) -> ApiError:
+        message = f"{res.status_code} {res.reason_phrase}"
+        detail: Any = None
+        try:
+            payload = res.json()
+            detail = payload.get("detail", payload)
+            if isinstance(detail, str):
+                message = detail
+            elif isinstance(detail, dict) and "message" in detail:
+                message = str(detail["message"])
+        except ValueError:
+            pass
+        return ApiError(res.status_code, message, detail)

gitfred_cli/commands/addon.py

@@ -0,0 +1,38 @@
+"""addon enable — turn on platform addons for an app."""
+
+from __future__ import annotations
+
+import typer
+
+from ..helpers import handle_errors, resolve_app
+from ..output import emit
+from ..state import get_state
+
+addon_app = typer.Typer(help="Manage application addons (postgres, valkey, volume, object-storage).")
+
+_KINDS = {
+    "postgres": "enable_postgres",
+    "valkey": "enable_valkey",
+    "volume": "enable_volume",
+    "object-storage": "enable_object_storage",
+    "object_storage": "enable_object_storage",
+}
+
+
+@addon_app.command("enable")
+@handle_errors
+def enable(
+    app_ref: str = typer.Argument(..., metavar="APP"),
+    kind: str = typer.Argument(..., help="postgres | valkey | volume | object-storage"),
+) -> None:
+    """Enable an addon (provisioned on the next deploy)."""
+    field = _KINDS.get(kind.lower())
+    if field is None:
+        raise typer.BadParameter(f"unknown addon {kind!r} (expected one of: {', '.join(sorted(set(_KINDS) - {'object_storage'}))})")
+    data = resolve_app(app_ref)
+    updated = get_state().client.patch(f"/applications/{data['id']}", body={field: True})
+    emit(
+        updated,
+        f"Enabled [bold]{kind}[/bold] on {updated['name']} — redeploy to provision: "
+        f"gitfred deploy {updated['id']}",
+    )

gitfred_cli/commands/app.py

@@ -0,0 +1,149 @@
+"""app create / list / show / delete."""
+
+from __future__ import annotations
+
+import sys
+
+import typer
+from rich.table import Table
+
+from ..helpers import handle_errors, resolve_app, resolve_repository
+from ..output import EXIT_ERROR, console, emit, fail, json_mode
+from ..state import get_state
+
+app_app = typer.Typer(help="Manage applications.")
+
+ADDON_FLAGS = ("postgres", "valkey", "volume", "object_storage")
+
+
+def _parse_env(pairs: list[str]) -> dict[str, str]:
+    env: dict[str, str] = {}
+    for pair in pairs:
+        if "=" not in pair:
+            raise fail(f"--env expects KEY=VALUE, got {pair!r}", 2)
+        key, value = pair.split("=", 1)
+        env[key] = value
+    return env
+
+
+@app_app.command("create")
+@handle_errors
+def create(
+    repo: str = typer.Option(..., "--repo", help="owner/name or a connected repository id."),
+    name: str | None = typer.Option(None, "--name", help="Application name (default: repo name)."),
+    branch: str | None = typer.Option(None, "--branch"),
+    port: int | None = typer.Option(None, "--port"),
+    health_path: str | None = typer.Option(None, "--health-path"),
+    postgres: bool = typer.Option(False, "--postgres", help="Enable the PostgreSQL addon."),
+    valkey: bool = typer.Option(False, "--valkey", help="Enable the Valkey (Redis) addon."),
+    volume: bool = typer.Option(False, "--volume", help="Enable the persistent-volume addon."),
+    object_storage: bool = typer.Option(
+        False, "--object-storage", help="Enable the S3 object-storage addon."
+    ),
+    env: list[str] = typer.Option([], "--env", help="KEY=VALUE (repeatable)."),
+    auto_deploy: bool = typer.Option(False, "--auto-deploy", help="Republish on every push."),
+    no_detect: bool = typer.Option(
+        False, "--no-detect", help="Skip repo-type detection and its suggested defaults."
+    ),
+    publish: bool = typer.Option(False, "--publish", help="Trigger the first deploy immediately."),
+) -> None:
+    """Create an application from a repository (detection fills in sensible defaults)."""
+    client = get_state().client
+    repository = resolve_repository(repo)
+
+    detection = None
+    if not no_detect:
+        detection = client.post(
+            "/applications/detect",
+            body={"repository_id": repository["id"], "branch": branch},
+        )
+        if not detection["deployable"]:
+            raise fail(
+                f"{repository['full_name']} is not deployable: "
+                f"{detection.get('reason') or detection['label']}",
+                EXIT_ERROR,
+                detail=detection,
+            )
+        if not json_mode():
+            console.print(
+                f"Detected [bold]{detection['label']}[/bold]"
+                + (f" · {detection['note']}" if detection.get("note") else "")
+            )
+
+    suggestions = (detection or {}).get("suggestions", {})
+    body = {
+        "repository_id": repository["id"],
+        "name": name or repository["name"],
+        "branch": branch,
+        "port": port if port is not None else suggestions.get("port", 8080),
+        "health_path": health_path
+        if health_path is not None
+        else suggestions.get("health_path", "/"),
+        "release_command": suggestions.get("release_command"),
+        "auto_deploy": auto_deploy,
+        "enable_postgres": postgres or suggestions.get("enable_postgres", False),
+        "enable_valkey": valkey or suggestions.get("enable_valkey", False),
+        "enable_volume": volume,
+        "enable_object_storage": object_storage
+        or suggestions.get("enable_object_storage", False),
+        "env": _parse_env(env),
+    }
+    created = client.post("/applications", body=body)
+
+    deployment = None
+    if publish:
+        deployment = client.post(f"/applications/{created['id']}/publish")
+
+    emit(
+        {"application": created, "deployment": deployment, "detection": detection},
+        f"Created application [bold]{created['name']}[/bold] (id {created['id']})"
+        + (f"\nDeployment {deployment['id']} queued — follow with: gitfred logs {deployment['id']} --follow"
+           if deployment else
+           f"\nDeploy it with: gitfred deploy {created['id']}"),
+    )
+
+
+@app_app.command("list")
+@handle_errors
+def list_apps() -> None:
+    """List your applications."""
+    apps = get_state().client.get("/applications")
+    emit(apps)
+    if not json_mode():
+        table = Table(header_style="bold")
+        for col in ("id", "name", "status", "url", "last deployed"):
+            table.add_column(col)
+        for a in apps:
+            table.add_row(
+                str(a["id"]), a["name"], a["status"], a.get("url") or "-",
+                a.get("last_deployed_at") or "never",
+            )
+        console.print(table)
+
+
+@app_app.command("show")
+@handle_errors
+def show(app_ref: str = typer.Argument(..., metavar="APP", help="Application id, slug, or name.")) -> None:
+    """Show one application in full."""
+    data = resolve_app(app_ref)
+    emit(data)
+    if not json_mode():
+        console.print_json(data=data)
+
+
+@app_app.command("delete")
+@handle_errors
+def delete(
+    app_ref: str = typer.Argument(..., metavar="APP"),
+    yes: bool = typer.Option(False, "--yes", help="Skip the confirmation prompt."),
+) -> None:
+    """Delete an application and tear down everything it provisioned."""
+    data = resolve_app(app_ref)
+    if not yes:
+        if not sys.stdin.isatty():
+            raise fail("refusing to delete without --yes in non-interactive mode", 2)
+        typer.confirm(
+            f"Delete '{data['name']}' (id {data['id']}) and all its resources?", abort=True
+        )
+    get_state().client.delete(f"/applications/{data['id']}")
+    emit({"status": "deleted", "id": data["id"]}, f"Deleted application {data['id']}.")

gitfred_cli/commands/auth.py

@@ -0,0 +1,91 @@
+"""login / logout / whoami."""
+
+from __future__ import annotations
+
+import socket
+import time
+import webbrowser
+
+import typer
+
+from ..client import ApiError, Client
+from ..config import load_config, save_config
+from ..helpers import handle_errors
+from ..output import EXIT_AUTH, EXIT_TIMEOUT, console, emit, fail, json_mode
+from ..state import get_state
+
+
+@handle_errors
+def login(
+    token: str | None = typer.Option(
+        None, "--token", help="Use an existing API token instead of the browser flow."
+    ),
+    no_browser: bool = typer.Option(
+        False, "--no-browser", help="Print the approval URL instead of opening a browser."
+    ),
+) -> None:
+    """Sign in to GitFred (opens your browser to approve this device)."""
+    state = get_state()
+    if token is None and not json_mode():
+        token = _device_flow(state.anon_client, open_browser=not no_browser)
+    elif token is None:
+        # --json implies non-interactive: a polling browser flow makes no sense there.
+        raise fail("in --json mode pass --token or set GITFRED_TOKEN", EXIT_AUTH)
+
+    me = Client(state.api_url, token).get("/auth/me")
+    config = load_config()
+    config["token"] = token
+    config["api_url"] = state.api_url
+    save_config(config)
+    emit(me, f"Signed in as [bold]@{me['login']}[/bold]")
+
+
+def _device_flow(client: Client, open_browser: bool) -> str:
+    started = client.post(
+        "/auth/device",
+        body={"client_name": "gitfred-cli", "client_host": socket.gethostname()},
+    )
+    url = started["verification_url"]
+    console.print(f"Approve this device in your browser:\n\n  [bold cyan]{url}[/bold cyan]\n")
+    if open_browser:
+        webbrowser.open(url)
+    deadline = time.monotonic() + started["expires_in"]
+    interval = started.get("interval", 2)
+    console.print("Waiting for approval…")
+    while time.monotonic() < deadline:
+        try:
+            result = client.post("/auth/device/poll", body={"device_code": started["device_code"]})
+        except ApiError as exc:
+            if exc.status == 403:
+                raise fail("authorization was denied in the browser", EXIT_AUTH) from exc
+            raise
+        if result is not None:
+            return result["token"]
+        time.sleep(interval)
+    raise fail("login timed out — run `gitfred login` again", EXIT_TIMEOUT)
+
+
+@handle_errors
+def logout() -> None:
+    """Sign out: revoke this device's token and remove it from the local config."""
+    config = load_config()
+    token = config.pop("token", None)
+    if token:
+        # Best-effort server-side revocation (the PAT can revoke itself).
+        try:
+            client = get_state().client
+            for t in client.get("/tokens"):
+                if token.startswith(t["token_prefix"]):
+                    client.delete(f"/tokens/{t['id']}")
+                    break
+        except ApiError:
+            pass
+    save_config(config)
+    emit({"status": "logged_out"}, "Signed out.")
+
+
+@handle_errors
+def whoami() -> None:
+    """Show the signed-in user."""
+    me = get_state().client.get("/auth/me")
+    emit(me, f"@{me['login']} ({me.get('name') or 'no name'}) · user id {me['id']}")

gitfred_cli/commands/deploy.py

@@ -0,0 +1,142 @@
+"""deploy / logs / open — the publish-and-watch path."""
+
+from __future__ import annotations
+
+import time
+import webbrowser
+
+import typer
+
+from ..client import ApiError
+from ..helpers import handle_errors, resolve_app
+from ..output import (
+    EXIT_DEPLOY_FAILED,
+    EXIT_OK,
+    EXIT_TIMEOUT,
+    console,
+    emit,
+    fail,
+    json_mode,
+)
+from ..state import get_state
+
+_TERMINAL = {"succeeded", "failed", "canceled"}
+
+
+@handle_errors
+def deploy(
+    app_ref: str = typer.Argument(..., metavar="APP", help="Application id, slug, or name."),
+    follow: bool = typer.Option(
+        True, "--follow/--no-follow", help="Stream build/deploy logs until the deploy finishes."
+    ),
+    timeout: int = typer.Option(1800, "--timeout", help="Max seconds to wait with --follow."),
+) -> None:
+    """Publish an application (build + deploy the latest commit)."""
+    client = get_state().client
+    data = resolve_app(app_ref)
+    deployment = client.post(f"/applications/{data['id']}/publish")
+    if not follow:
+        emit(
+            deployment,
+            f"Deployment {deployment['id']} queued — follow with: "
+            f"gitfred logs {deployment['id']} --follow",
+        )
+        return
+    if not json_mode():
+        console.print(f"Deployment [bold]{deployment['id']}[/bold] queued, streaming logs…")
+    status = _follow_logs(deployment["id"], timeout)
+    final = client.get(f"/deployments/{deployment['id']}")
+    emit(final, None)
+    _finish(final, status)
+
+
+@handle_errors
+def logs(
+    deployment_id: int = typer.Argument(..., help="Deployment id."),
+    follow: bool = typer.Option(False, "--follow", help="Stream until the deploy finishes."),
+    after: int = typer.Option(0, "--after", help="Only lines with seq > AFTER."),
+    timeout: int = typer.Option(1800, "--timeout", help="Max seconds to wait with --follow."),
+) -> None:
+    """Print (or stream) the logs of a deployment."""
+    client = get_state().client
+    if not follow:
+        lines = client.get(f"/deployments/{deployment_id}/logs", params={"after": after})
+        emit(lines)
+        if not json_mode():
+            for entry in lines:
+                _print_line(entry)
+        return
+    status = _follow_logs(deployment_id, timeout, after=after)
+    final = client.get(f"/deployments/{deployment_id}")
+    emit(final, None)
+    _finish(final, status)
+
+
+@handle_errors
+def open_app(app_ref: str = typer.Argument(..., metavar="APP")) -> None:
+    """Open the application's live URL in your browser."""
+    data = resolve_app(app_ref)
+    url = data.get("url")
+    if not url:
+        raise fail("application has no URL yet — deploy it first", 4)
+    emit({"url": url}, f"Opening [bold cyan]{url}[/bold cyan]")
+    if not json_mode():
+        webbrowser.open(url)
+
+
+def _print_line(entry: dict) -> None:
+    stage = entry.get("stage", "")
+    line = entry.get("line", "")
+    if entry.get("stream") == "stderr":
+        console.print(f"[dim]{stage:>10}[/dim] [red]{line}[/red]", highlight=False)
+    else:
+        console.print(f"[dim]{stage:>10}[/dim] {line}", highlight=False)
+
+
+def _follow_logs(deployment_id: int, timeout: int, after: int = 0) -> str | None:
+    """Stream logs via SSE (falling back to polling) until terminal or timeout.
+
+    Returns the final status when the stream reported it, else None.
+    """
+    client = get_state().client
+    deadline = time.monotonic() + timeout
+    last_seq = after
+    while time.monotonic() < deadline:
+        try:
+            for event, data in client.sse(
+                f"/deployments/{deployment_id}/logs/stream", params={"after": last_seq}
+            ):
+                if event == "log":
+                    last_seq = max(last_seq, data.get("seq", last_seq))
+                    if not json_mode():
+                        _print_line(data)
+                elif event == "done":
+                    return data.get("status")
+                if time.monotonic() > deadline:
+                    raise fail("timed out waiting for the deployment", EXIT_TIMEOUT)
+            # Stream closed without a `done` event (proxy idle cut) — check and resume.
+        except ApiError:
+            # SSE unavailable (old proxy, flaky link) — fall back to one polling round.
+            time.sleep(2)
+            entries = client.get(
+                f"/deployments/{deployment_id}/logs", params={"after": last_seq}
+            )
+            for entry in entries:
+                last_seq = max(last_seq, entry["seq"])
+                if not json_mode():
+                    _print_line(entry)
+        status = client.get(f"/deployments/{deployment_id}")["status"]
+        if status in _TERMINAL:
+            return status
+    raise fail("timed out waiting for the deployment", EXIT_TIMEOUT)
+
+
+def _finish(final: dict, status: str | None) -> None:
+    status = status or final.get("status")
+    if status == "succeeded":
+        if not json_mode():
+            console.print(f"\n[green]✓ deployed[/green] {final.get('url') or ''}")
+        raise SystemExit(EXIT_OK)
+    if not json_mode():
+        console.print(f"\n[red]✗ deployment {status}[/red] {final.get('error') or ''}")
+    raise SystemExit(EXIT_DEPLOY_FAILED)

gitfred_cli/commands/env.py

@@ -0,0 +1,68 @@
+"""env get / set / unset."""
+
+from __future__ import annotations
+
+import typer
+
+from ..helpers import handle_errors, resolve_app
+from ..output import console, emit, fail, json_mode
+from ..state import get_state
+
+env_app = typer.Typer(help="Manage application environment variables.")
+
+
+def _get_items(app_id: int) -> list[dict]:
+    return get_state().client.get(f"/applications/{app_id}/env")["items"]
+
+
+def _put_items(app_id: int, items: dict[str, str]) -> list[dict]:
+    body = {"items": [{"key": k, "value": v} for k, v in items.items()]}
+    return get_state().client.put(f"/applications/{app_id}/env", body=body)["items"]
+
+
+@env_app.command("get")
+@handle_errors
+def get(app_ref: str = typer.Argument(..., metavar="APP")) -> None:
+    """Print the application's environment variables."""
+    data = resolve_app(app_ref)
+    items = _get_items(data["id"])
+    emit(items)
+    if not json_mode():
+        for item in items:
+            console.print(f"{item['key']}={item['value']}", highlight=False)
+
+
+@env_app.command("set")
+@handle_errors
+def set_(
+    app_ref: str = typer.Argument(..., metavar="APP"),
+    pairs: list[str] = typer.Argument(..., metavar="KEY=VALUE..."),
+) -> None:
+    """Set one or more variables (redeploy to apply)."""
+    data = resolve_app(app_ref)
+    merged = {i["key"]: i["value"] for i in _get_items(data["id"])}
+    for pair in pairs:
+        if "=" not in pair:
+            raise fail(f"expected KEY=VALUE, got {pair!r}", 2)
+        key, value = pair.split("=", 1)
+        merged[key] = value
+    items = _put_items(data["id"], merged)
+    emit(items, f"Set {len(pairs)} variable(s). Redeploy to apply: gitfred deploy {data['id']}")
+
+
+@env_app.command("unset")
+@handle_errors
+def unset(
+    app_ref: str = typer.Argument(..., metavar="APP"),
+    keys: list[str] = typer.Argument(..., metavar="KEY..."),
+) -> None:
+    """Remove one or more variables (redeploy to apply)."""
+    data = resolve_app(app_ref)
+    merged = {i["key"]: i["value"] for i in _get_items(data["id"])}
+    missing = [k for k in keys if k not in merged]
+    if missing:
+        raise fail(f"not set: {', '.join(missing)}", 4)
+    for key in keys:
+        del merged[key]
+    items = _put_items(data["id"], merged)
+    emit(items, f"Removed {len(keys)} variable(s). Redeploy to apply: gitfred deploy {data['id']}")

gitfred_cli/commands/repo.py

@@ -0,0 +1,61 @@
+"""repo list / search / connect."""
+
+from __future__ import annotations
+
+import typer
+from rich.table import Table
+
+from ..helpers import handle_errors
+from ..output import console, emit, json_mode
+from ..state import get_state
+
+repo_app = typer.Typer(help="Browse and connect GitHub repositories.")
+
+
+def _repo_table(rows: list[dict], title: str) -> Table:
+    table = Table(title=title, header_style="bold")
+    table.add_column("id")
+    table.add_column("repository")
+    table.add_column("private")
+    table.add_column("default branch")
+    for r in rows:
+        table.add_row(
+            str(r.get("id") or r.get("github_repo_id")),
+            r["full_name"],
+            "yes" if r.get("private") else "no",
+            r.get("default_branch") or "-",
+        )
+    return table
+
+
+@repo_app.command("list")
+@handle_errors
+def list_repos(
+    github: bool = typer.Option(
+        False, "--github", help="List repositories visible on GitHub instead of connected ones."
+    ),
+) -> None:
+    """List connected repositories (or, with --github, your GitHub repositories)."""
+    client = get_state().client
+    rows = client.get("/repositories/github" if github else "/repositories")
+    emit(rows)
+    if not json_mode():
+        console.print(_repo_table(rows, "GitHub repositories" if github else "Connected repositories"))
+
+
+@repo_app.command("search")
+@handle_errors
+def search(q: str = typer.Argument(..., help="Search query (GitHub repo search syntax).")) -> None:
+    """Search public GitHub repositories."""
+    rows = get_state().client.get("/repositories/github/search", params={"q": q})
+    emit(rows)
+    if not json_mode():
+        console.print(_repo_table(rows, f"Search: {q}"))
+
+
+@repo_app.command("connect")
+@handle_errors
+def connect(full_name: str = typer.Argument(..., help="owner/name")) -> None:
+    """Connect a repository to GitFred."""
+    repo = get_state().client.post("/repositories", body={"full_name": full_name})
+    emit(repo, f"Connected [bold]{repo['full_name']}[/bold] (repository id {repo['id']})")

gitfred_cli/config.py

@@ -0,0 +1,46 @@
+"""Local CLI configuration: token + API URL.
+
+Precedence for the token: ``GITFRED_TOKEN`` env > ``--token`` flag > config file.
+The config file lives at ``~/.config/gitfred/config.json`` (0600).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+DEFAULT_API_URL = "https://api.gitfred.com"
+
+
+def config_path() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME") or os.path.join(Path.home(), ".config")
+    return Path(base) / "gitfred" / "config.json"
+
+
+def load_config() -> dict:
+    path = config_path()
+    try:
+        return json.loads(path.read_text())
+    except (OSError, ValueError):
+        return {}
+
+
+def save_config(data: dict) -> None:
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2) + "\n")
+    path.chmod(0o600)
+
+
+def resolve_token(flag_token: str | None) -> str | None:
+    return os.environ.get("GITFRED_TOKEN") or flag_token or load_config().get("token")
+
+
+def resolve_api_url(flag_url: str | None) -> str:
+    return (
+        os.environ.get("GITFRED_API_URL")
+        or flag_url
+        or load_config().get("api_url")
+        or DEFAULT_API_URL
+    )

gitfred_cli/helpers.py

@@ -0,0 +1,60 @@
+"""Shared command plumbing: error handling and repo/app resolution."""
+
+from __future__ import annotations
+
+import functools
+from typing import Any, Callable
+
+from .client import ApiError
+from .output import fail
+from .state import get_state
+
+
+def handle_errors(fn: Callable) -> Callable:
+    """Map ApiError to the exit-code contract; everything else propagates."""
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return fn(*args, **kwargs)
+        except ApiError as exc:
+            raise fail(str(exc), exc.exit_code, detail=exc.detail) from exc
+
+    return wrapper
+
+
+def resolve_repository(repo: str) -> dict:
+    """Resolve ``owner/name`` or a numeric connected-repo id to a Repository.
+
+    ``owner/name`` is connected automatically when not already connected.
+    """
+    client = get_state().client
+    connected = client.get("/repositories")
+    if repo.isdigit():
+        for r in connected:
+            if r["id"] == int(repo):
+                return r
+        raise fail(f"no connected repository with id {repo}", 4)
+    matches = [r for r in connected if r["full_name"].lower() == repo.lower()]
+    if matches:
+        return matches[0]
+    if "/" not in repo:
+        raise fail(f"expected owner/name or a repository id, got {repo!r}", 2)
+    return client.post("/repositories", body={"full_name": repo})
+
+
+def resolve_app(app_ref: str) -> dict:
+    """Resolve an application id, slug, or exact name to an ApplicationOut."""
+    client = get_state().client
+    if app_ref.isdigit():
+        return client.get(f"/applications/{app_ref}")
+    apps = client.get("/applications")
+    matches = [
+        a for a in apps if a.get("slug") == app_ref or a["name"].lower() == app_ref.lower()
+    ]
+    if len(matches) == 1:
+        return matches[0]
+    if not matches:
+        raise fail(f"no application matching {app_ref!r}", 4)
+    ids = ", ".join(str(a["id"]) for a in matches)
+    raise fail(f"{app_ref!r} is ambiguous (ids: {ids}) — use the id", 2)

gitfred_cli/main.py

@@ -0,0 +1,64 @@
+"""gitfred — deploy GitHub repositories as live web apps from your terminal.
+
+Agent-friendly by design: every command takes --json (machine-readable output,
+JSON errors on stderr), auth comes from GITFRED_TOKEN or `gitfred login`, and
+exit codes are a stable contract (see output.py).
+"""
+
+from __future__ import annotations
+
+import typer
+
+from . import __version__
+from .commands.addon import addon_app
+from .commands.app import app_app
+from .commands.auth import login, logout, whoami
+from .commands.deploy import deploy, logs, open_app
+from .commands.env import env_app
+from .commands.repo import repo_app
+from .output import set_json_mode
+from .state import set_state
+
+app = typer.Typer(
+    name="gitfred",
+    help=__doc__,
+    no_args_is_help=True,
+    add_completion=False,
+    pretty_exceptions_show_locals=False,
+)
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    json_output: bool = typer.Option(
+        False, "--json", help="Machine-readable JSON output (errors as JSON on stderr)."
+    ),
+    token: str | None = typer.Option(
+        None, "--token", envvar="GITFRED_TOKEN", help="API token (overrides the saved login)."
+    ),
+    api_url: str | None = typer.Option(
+        None, "--api-url", envvar="GITFRED_API_URL", help="GitFred API base URL."
+    ),
+    version: bool = typer.Option(False, "--version", help="Print the version and exit."),
+) -> None:
+    if version:
+        print(f"gitfred {__version__}")
+        raise typer.Exit()
+    set_json_mode(json_output)
+    set_state(api_url, token)
+
+
+app.command("login")(login)
+app.command("logout")(logout)
+app.command("whoami")(whoami)
+app.command("deploy")(deploy)
+app.command("logs")(logs)
+app.command("open")(open_app)
+app.add_typer(repo_app, name="repo")
+app.add_typer(app_app, name="app")
+app.add_typer(env_app, name="env")
+app.add_typer(addon_app, name="addon")
+
+
+if __name__ == "__main__":
+    app()

gitfred_cli/output.py

@@ -0,0 +1,54 @@
+"""Rendering + exit-code conventions.
+
+Exit codes (stable contract for scripts and agents):
+0 success · 2 usage error · 3 auth · 4 not found · 5 quota/rate-limit ·
+6 deploy failed · 7 timeout · 1 anything else.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+from rich.console import Console
+
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_USAGE = 2
+EXIT_AUTH = 3
+EXIT_NOT_FOUND = 4
+EXIT_QUOTA = 5
+EXIT_DEPLOY_FAILED = 6
+EXIT_TIMEOUT = 7
+
+console = Console()
+err_console = Console(stderr=True)
+
+_json_mode = False
+
+
+def set_json_mode(enabled: bool) -> None:
+    global _json_mode
+    _json_mode = enabled
+
+
+def json_mode() -> bool:
+    return _json_mode
+
+
+def emit(data: Any, human: str | None = None) -> None:
+    """Print ``data`` as JSON in --json mode, else the human rendering (or nothing)."""
+    if _json_mode:
+        print(json.dumps(data, indent=2, default=str))
+    elif human is not None:
+        console.print(human)
+
+
+def fail(message: str, exit_code: int = EXIT_ERROR, detail: Any = None) -> "SystemExit":
+    """Print an error (JSON on stderr in --json mode) and return SystemExit to raise."""
+    if _json_mode:
+        err_console.print_json(json.dumps({"error": message, "detail": detail}, default=str))
+    else:
+        err_console.print(f"[red]error:[/red] {message}")
+    return SystemExit(exit_code)

gitfred_cli/state.py

@@ -0,0 +1,47 @@
+"""Per-invocation CLI state, set by the root callback and read by commands."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .client import Client
+from .config import resolve_api_url, resolve_token
+from .output import EXIT_AUTH, fail
+
+
+@dataclass
+class State:
+    api_url: str
+    token: str | None
+
+    _client: Client | None = None
+
+    @property
+    def client(self) -> Client:
+        """Authenticated client; exits 3 when no token is configured."""
+        if self._client is None:
+            if not self.token:
+                raise fail(
+                    "not signed in — run `gitfred login` or set GITFRED_TOKEN", EXIT_AUTH
+                )
+            self._client = Client(self.api_url, self.token)
+        return self._client
+
+    @property
+    def anon_client(self) -> Client:
+        """Unauthenticated client (device-auth flow)."""
+        return Client(self.api_url)
+
+
+_state: State | None = None
+
+
+def set_state(api_url_flag: str | None, token_flag: str | None) -> State:
+    global _state
+    _state = State(api_url=resolve_api_url(api_url_flag), token=resolve_token(token_flag))
+    return _state
+
+
+def get_state() -> State:
+    assert _state is not None, "root callback did not run"
+    return _state