pyvolt-cli 0.0.1__tar.gz → 0.2.0__tar.gz

pyvolt_cli-0.2.0/.gitignore

@@ -0,0 +1,4 @@
+dist/
+*.egg-info/
+__pycache__/
+.venv/

pyvolt_cli-0.2.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: pyvolt-cli
+Version: 0.2.0
+Summary: The command-line companion to Pyvolt: managed Python deployments on infrastructure you actually own.
+Project-URL: Homepage, https://pyvolt.com
+Project-URL: Repository, https://github.com/pyvolt-hq/pyvolt-cli
+Project-URL: Issues, https://github.com/pyvolt-hq/pyvolt-cli/issues
+Author-email: Will Abbott <will@digitaloutback.co.uk>
+Maintainer-email: Pyvolt HQ <will@digitaloutback.co.uk>
+License: MIT
+License-File: LICENSE
+Keywords: deployment,digitalocean,django,fastapi,flask,hetzner,paas,python,vps
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Installation/Setup
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# pyvolt-cli
+
+The command-line companion to [Pyvolt](https://pyvolt.com) — managed Python
+deployments on infrastructure you actually own.
+
+```bash
+uv tool install pyvolt-cli   # or: pipx install pyvolt-cli
+pyvolt login                 # browser approval, no password in the terminal
+pyvolt deploy myapp --follow
+```
+
+| Command | What it does |
+|---|---|
+| `pyvolt login` / `logout` / `whoami` | Device-flow auth (token stored in `~/.config/pyvolt/`, mode 600) |
+| `pyvolt servers` / `pyvolt apps` | Inventory with live status |
+| `pyvolt deploy DOMAIN [--follow]` | Trigger a deployment, optionally streaming the log |
+| `pyvolt deployments DOMAIN` | Recent deployment history |
+| `pyvolt env DOMAIN list\|set K=V…\|rm K` | Environment variables — pushed and app restarted |
+| `pyvolt ps DOMAIN [restart NAME]` | Background processes with live systemd state |
+| `pyvolt logs DOMAIN [-p NAME] [-n N]` | Tail the app's journal |
+| `pyvolt bans SERVER` | IPs banned by fail2ban, your own flagged |
+| `pyvolt unban SERVER [IP] [--me]` | Lift a ban — `--me` unbans your own IP, even while it's banned |
+| `pyvolt open DOMAIN` | Jump to the dashboard |
+
+`DOMAIN` is the app's domain, or any unambiguous fragment of it — domains
+are unique across the platform, so no server qualifier is ever needed.
+
+Full guide: [pyvolt.com/docs/cli](https://pyvolt.com/docs/cli/) · HTTP API:
+[pyvolt.com/api/docs](https://pyvolt.com/api/docs)
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

pyvolt_cli-0.2.0/README.md

@@ -0,0 +1,40 @@
+# pyvolt-cli
+
+The command-line companion to [Pyvolt](https://pyvolt.com) — managed Python
+deployments on infrastructure you actually own.
+
+```bash
+uv tool install pyvolt-cli   # or: pipx install pyvolt-cli
+pyvolt login                 # browser approval, no password in the terminal
+pyvolt deploy myapp --follow
+```
+
+| Command | What it does |
+|---|---|
+| `pyvolt login` / `logout` / `whoami` | Device-flow auth (token stored in `~/.config/pyvolt/`, mode 600) |
+| `pyvolt servers` / `pyvolt apps` | Inventory with live status |
+| `pyvolt deploy DOMAIN [--follow]` | Trigger a deployment, optionally streaming the log |
+| `pyvolt deployments DOMAIN` | Recent deployment history |
+| `pyvolt env DOMAIN list\|set K=V…\|rm K` | Environment variables — pushed and app restarted |
+| `pyvolt ps DOMAIN [restart NAME]` | Background processes with live systemd state |
+| `pyvolt logs DOMAIN [-p NAME] [-n N]` | Tail the app's journal |
+| `pyvolt bans SERVER` | IPs banned by fail2ban, your own flagged |
+| `pyvolt unban SERVER [IP] [--me]` | Lift a ban — `--me` unbans your own IP, even while it's banned |
+| `pyvolt open DOMAIN` | Jump to the dashboard |
+
+`DOMAIN` is the app's domain, or any unambiguous fragment of it — domains
+are unique across the platform, so no server qualifier is ever needed.
+
+Full guide: [pyvolt.com/docs/cli](https://pyvolt.com/docs/cli/) · HTTP API:
+[pyvolt.com/api/docs](https://pyvolt.com/api/docs)
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

{pyvolt_cli-0.0.1 → pyvolt_cli-0.2.0}/pyproject.toml

@@ -4,16 +4,21 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pyvolt-cli"
-version = "0.0.1"
-description = "The command-line companion to pyvolt: managed Python deployments on infrastructure you actually own."
+version = "0.2.0"
+description = "The command-line companion to Pyvolt: managed Python deployments on infrastructure you actually own."
 readme = "README.md"
 license = { text = "MIT" }
-requires-python = ">=3.10"
+requires-python = ">=3.11"
+dependencies = [
+    "typer>=0.12",
+    "httpx>=0.27",
+    "rich>=13.7",
+]
 authors = [
     { name = "Will Abbott", email = "will@digitaloutback.co.uk" },
 ]
 maintainers = [
-    { name = "PyVolt HQ", email = "will@digitaloutback.co.uk" },
+    { name = "Pyvolt HQ", email = "will@digitaloutback.co.uk" },
 ]
 keywords = [
     "deployment",
@@ -27,13 +32,12 @@ keywords = [
     "digitalocean",
 ]
 classifiers = [
-    "Development Status :: 1 - Planning",
+    "Development Status :: 4 - Beta",
     "Environment :: Console",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
@@ -60,3 +64,9 @@ include = [
     "LICENSE",
     "pyproject.toml",
 ]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "respx>=0.22",
+]

pyvolt_cli-0.2.0/pyvolt_cli/__init__.py

@@ -0,0 +1,4 @@
+"""pyvolt-cli: the terminal companion to Pyvolt — managed Python deployments
+on infrastructure you actually own. Docs: https://pyvolt.com/docs/cli/"""
+
+__version__ = "0.1.0"

pyvolt_cli-0.2.0/pyvolt_cli/__main__.py

@@ -0,0 +1,12 @@
+"""Entry point for the ``pyvolt`` command (``[project.scripts]``)."""
+from __future__ import annotations
+
+from .app import app
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

pyvolt_cli-0.2.0/pyvolt_cli/app.py

@@ -0,0 +1,355 @@
+"""The Pyvolt CLI — deploy, logs, env and processes from your terminal."""
+from __future__ import annotations
+
+import platform
+import time
+import webbrowser
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from . import __version__, config
+from .client import Api, fail
+
+app = typer.Typer(
+    name="pyvolt",
+    help="The Pyvolt CLI — manage servers, apps and deployments on your own infrastructure.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+console = Console()
+
+STATUS_STYLE = {
+    "ready": "green", "live": "green", "succeeded": "green", "running": "cyan",
+    "active": "green", "queued": "yellow", "deploying": "cyan",
+    "failed": "red", "error": "red", "inactive": "red",
+}
+
+
+def _status(s: str) -> str:
+    return f"[{STATUS_STYLE.get(s, 'white')}]{s}[/]"
+
+
+def _table(*columns: str) -> Table:
+    t = Table(box=None, header_style="bold dim", pad_edge=False)
+    for c in columns:
+        t.add_column(c)
+    return t
+
+
+@app.callback(invoke_without_command=True)
+def _main(
+    ctx: typer.Context,
+    version: bool = typer.Option(False, "--version", "-V", help="Print version and exit."),
+):
+    if version:
+        console.print(f"pyvolt-cli {__version__}")
+        raise typer.Exit()
+    if ctx.invoked_subcommand is None:
+        console.print(ctx.get_help())
+        raise typer.Exit()
+
+
+# ---- auth -------------------------------------------------------------------
+
+@app.command()
+def login():
+    """Authorize this machine via your browser (no password in the terminal)."""
+    import httpx
+
+    base = config.api_url()
+    try:
+        start = httpx.post(
+            f"{base}/api/cli/auth/start",
+            json={"device_name": platform.node()},
+            timeout=30,
+        ).json()
+    except httpx.HTTPError as e:
+        raise fail(f"Could not reach {base}: {e}") from e
+
+    console.print(f"\nConfirmation code: [bold cyan]{start['user_code']}[/]")
+    console.print(f"Opening [link]{start['verification_uri']}[/link] — approve there if the code matches.\n")
+    webbrowser.open(start["verification_uri"])
+
+    deadline = time.monotonic() + start.get("expires_in", 600)
+    with console.status("Waiting for browser approval…"):
+        while time.monotonic() < deadline:
+            time.sleep(start.get("interval", 2))
+            poll = httpx.post(
+                f"{base}/api/cli/auth/poll",
+                json={"device_code": start["device_code"]},
+                timeout=30,
+            ).json()
+            if poll["status"] == "approved":
+                path = config.save(poll["token"], base)
+                console.print(f"[green]✓[/green] Logged in — token stored in {path}")
+                return
+            if poll["status"] == "denied":
+                raise fail("Request denied in the browser.")
+            if poll["status"] == "expired":
+                raise fail("Login request expired — run [bold]pyvolt login[/bold] again.")
+    raise fail("Timed out waiting for approval.")
+
+
+@app.command()
+def logout():
+    """Remove this machine's stored token (revoke it fully under Account → API)."""
+    config.clear()
+    console.print("[green]✓[/green] Logged out. Revoke the token under Account → API on the dashboard.")
+
+
+@app.command()
+def whoami():
+    """Show the authenticated account."""
+    me = Api().get("/v1/me")
+    console.print(f"{me['username']} <{me['email']}> @ {config.api_url()}")
+
+
+# ---- read-only inventory ------------------------------------------------------
+
+@app.command()
+def servers():
+    """List your servers."""
+    t = _table("NAME", "IP", "PROVIDER", "STATUS", "CONNECTED")
+    for s in Api().get("/v1/servers"):
+        t.add_row(
+            s["name"], s["ip_address"], s["provider"], _status(s["status"]),
+            "[green]yes[/]" if s["connected"] else "[red]no[/]",
+        )
+    console.print(t)
+
+
+@app.command()
+def ssh(
+    server: str = typer.Argument(..., metavar="SERVER"),
+    app_name: str = typer.Option("", "--app", "-a", help="cd into this app's directory on connect."),
+):
+    """Open an SSH shell on a server (as the pyvolt app-user).
+
+    A thin convenience wrapper: it resolves the host/port from the API and
+    execs your local `ssh`, so your own key must be on the box — add it under
+    Account → SSH Keys (or `pyvolt` on the web dashboard)."""
+    import os
+    import shutil
+
+    if not shutil.which("ssh"):
+        raise fail("No `ssh` client found on PATH.")
+    api = Api()
+    srv = api.resolve_server(server)
+    if srv["status"] != "ready":
+        raise fail(f"{srv['name']} is {srv['status']}, not ready.")
+    target = f"{srv.get('ssh_user', 'pyvolt')}@{srv['ip_address']}"
+    args = ["ssh", "-p", str(srv.get("ssh_port", 22)), target]
+    if app_name:
+        site = api.resolve_app(app_name)
+        # Drop into the app's checkout, then hand over an interactive shell.
+        args += ["-t", f"cd sites/{site['domain']}/repo 2>/dev/null; exec \"$SHELL\" -l"]
+    console.print(f"[dim]Connecting to {target}…[/dim]")
+    os.execvp("ssh", args)
+
+
+@app.command()
+def apps(server: str = typer.Option("", "--server", help="Filter by server name.")):
+    """List your apps."""
+    t = _table("DOMAIN", "SERVER", "STATUS", "REPO", "BRANCH")
+    for a in Api().get("/v1/apps", params={"server": server} if server else None):
+        t.add_row(a["domain"], a["server"], _status(a["status"]), a["repo"], a["branch"])
+    console.print(t)
+
+
+# ---- deployments --------------------------------------------------------------
+
+TERMINAL = ("succeeded", "failed")
+
+
+def _follow(api: Api, deployment_id: int) -> str:
+    offset, status = 0, "queued"
+    while status not in TERMINAL:
+        time.sleep(2)
+        chunk = api.get(f"/v1/deployments/{deployment_id}/log", params={"offset": offset})
+        status, offset = chunk["status"], chunk["offset"]
+        if chunk["chunk"]:
+            console.out(chunk["chunk"], end="", highlight=False)
+    return status
+
+
+@app.command()
+def deploy(
+    app_name: str = typer.Argument(..., metavar="DOMAIN"),
+    follow: bool = typer.Option(False, "--follow", "-f", help="Stream the deploy log."),
+):
+    """Trigger a deployment."""
+    api = Api()
+    site = api.resolve_app(app_name)
+    r = api.post(f"/v1/apps/{site['id']}/deployments", ok=(201, 409))
+    if r.status_code == 409:
+        raise fail(r.json()["detail"])
+    d = r.json()
+    console.print(f"[green]✓[/green] Deployment queued for [bold]{site['domain']}[/bold]")
+    if not follow:
+        console.print(f"  pyvolt deploy {site['domain']} --follow   (or watch {site['dashboard_url']})")
+        return
+    status = _follow(api, d["id"])
+    if status == "failed":
+        raise fail("Deployment failed.")
+    console.print(f"\n[green]✓[/green] Deployed {site['domain']}")
+
+
+@app.command()
+def deployments(app_name: str = typer.Argument(..., metavar="DOMAIN")):
+    """Recent deployments for an app."""
+    api = Api()
+    site = api.resolve_app(app_name)
+    t = _table("WHEN", "STATUS", "COMMIT", "MESSAGE", "BY", "TOOK")
+    for d in api.get(f"/v1/apps/{site['id']}/deployments"):
+        took = f"{d['duration_seconds']}s" if d["duration_seconds"] is not None else ""
+        t.add_row(
+            d["created_at"][:16].replace("T", " "), _status(d["status"]),
+            d["commit_sha"][:7], d["commit_message"].splitlines()[0][:60] if d["commit_message"] else "",
+            d["triggered_by"], took,
+        )
+    console.print(t)
+
+
+# ---- env ----------------------------------------------------------------------
+
+env_app = typer.Typer(no_args_is_help=True, help="Manage an app's environment variables.")
+app.add_typer(env_app, name="env")
+
+
+@env_app.callback()
+def _env_main(ctx: typer.Context, app_name: str = typer.Argument(..., metavar="DOMAIN")):
+    ctx.obj = app_name
+
+
+@env_app.command("list")
+def env_list(ctx: typer.Context):
+    """Show the app's variables (secret values masked)."""
+    api = Api()
+    site = api.resolve_app(ctx.obj)
+    t = _table("KEY", "VALUE")
+    for row in api.get(f"/v1/apps/{site['id']}/env"):
+        t.add_row(row["key"], "••••••••" if row["is_secret"] else row["value"])
+    console.print(t)
+
+
+@env_app.command("set")
+def env_set(ctx: typer.Context, pairs: list[str] = typer.Argument(..., metavar="KEY=VALUE...")):
+    """Set one or more variables — pushes the .env and restarts the app."""
+    api = Api()
+    site = api.resolve_app(ctx.obj)
+    for pair in pairs:
+        if "=" not in pair:
+            raise fail(f"Expected KEY=VALUE, got [bold]{pair}[/bold]")
+        key, _, value = pair.partition("=")
+        api.post(f"/v1/apps/{site['id']}/env", json={"key": key, "value": value})
+        console.print(f"[green]✓[/green] {key}")
+
+
+@env_app.command("rm")
+def env_rm(ctx: typer.Context, key: str):
+    """Remove a variable — pushes the .env and restarts the app."""
+    api = Api()
+    site = api.resolve_app(ctx.obj)
+    r = api.delete(f"/v1/apps/{site['id']}/env/{key}")
+    if not r["deleted"]:
+        raise fail(f"[bold]{key}[/bold] is not set.")
+    console.print(f"[green]✓[/green] {key} removed")
+
+
+# ---- processes & logs -----------------------------------------------------------
+
+@app.command()
+def ps(
+    app_name: str = typer.Argument(..., metavar="DOMAIN"),
+    action: str = typer.Argument("", metavar="[restart]"),
+    process: str = typer.Argument("", metavar="[NAME]"),
+):
+    """List background processes; `pyvolt ps APP restart NAME` restarts one."""
+    api = Api()
+    site = api.resolve_app(app_name)
+    procs = api.get(f"/v1/apps/{site['id']}/processes")
+    if action:
+        if action != "restart" or not process:
+            raise fail("Usage: pyvolt ps DOMAIN restart NAME")
+        match = [p for p in procs if p["name"] == process]
+        if not match:
+            known = ", ".join(p["name"] for p in procs) or "none"
+            raise fail(f"No process [bold]{process}[/bold]. Processes: {known}")
+        api.post(f"/v1/apps/{site['id']}/processes/{match[0]['id']}/restart")
+        console.print(f"[green]✓[/green] Restarted {process}")
+        return
+    t = _table("NAME", "KIND", "STATE", "COMMAND")
+    for p in procs:
+        state = _status(p["state"]) + (f" ({p['exit']})" if p["exit"] else "")
+        t.add_row(p["name"], p["kind"], state, p["command"])
+    console.print(t)
+
+
+@app.command()
+def logs(
+    app_name: str = typer.Argument(..., metavar="DOMAIN"),
+    process: str = typer.Option("", "--process", "-p", help="A named background process instead of the web app."),
+    lines: int = typer.Option(100, "--lines", "-n", help="How many lines (max 500)."),
+):
+    """Tail the app's journal."""
+    api = Api()
+    site = api.resolve_app(app_name)
+    params = {"lines": lines}
+    if process:
+        params["process"] = process
+    r = api.get(f"/v1/apps/{site['id']}/logs", params=params)
+    if r.get("error"):
+        raise fail(f"journalctl failed on the server: {r['error']}")
+    for line in r["lines"]:
+        console.out(line, highlight=False)
+
+
+# ---- fail2ban -------------------------------------------------------------------
+
+@app.command()
+def bans(server: str = typer.Argument(..., metavar="SERVER")):
+    """List IPs banned by fail2ban on a server (flags your own IP)."""
+    api = Api()
+    srv = api.resolve_server(server)
+    r = api.get(f"/v1/servers/{srv['id']}/bans")
+    if not r["running"]:
+        raise fail("fail2ban is not active on this server.")
+    if not r["banned"]:
+        console.print("[green]✓[/green] No IPs are currently banned.")
+    else:
+        t = _table("BANNED IP", "")
+        for ip in r["banned"]:
+            t.add_row(ip, "[yellow]← this is you[/]" if ip == r["your_ip"] else "")
+        console.print(t)
+    console.print(f"[dim]Your public IP: {r['your_ip']}[/dim]")
+    if r["your_ip"] in r["banned"]:
+        console.print(f"Unban yourself:  [bold]pyvolt unban {srv['name']} --me[/bold]")
+
+
+@app.command()
+def unban(
+    server: str = typer.Argument(..., metavar="SERVER"),
+    ip: str = typer.Argument("", metavar="[IP]"),
+    me: bool = typer.Option(False, "--me", help="Unban your own public IP (as the API sees it)."),
+):
+    """Lift a fail2ban ban — banned yourself? `pyvolt unban SERVER --me`."""
+    api = Api()
+    srv = api.resolve_server(server)
+    if me:
+        ip = api.get(f"/v1/servers/{srv['id']}/bans")["your_ip"]
+    if not ip:
+        raise fail("Give an IP, or use [bold]--me[/bold] to unban your own.")
+    r = api.post(f"/v1/servers/{srv['id']}/bans/unban", ok=(200, 400), json={"ip": ip})
+    if r.status_code == 400:
+        raise fail(r.json()["detail"])
+    console.print(f"[green]✓[/green] Unbanned {ip}")
+
+
+@app.command("open")
+def open_(app_name: str = typer.Argument(..., metavar="DOMAIN")):
+    """Open the app's dashboard page in your browser."""
+    site = Api().resolve_app(app_name)
+    console.print(f"Opening {site['dashboard_url']}")
+    webbrowser.open(site["dashboard_url"])

pyvolt_cli-0.2.0/pyvolt_cli/client.py

@@ -0,0 +1,84 @@
+"""Thin httpx wrapper over the Pyvolt API (interactive docs at /api/docs)."""
+from __future__ import annotations
+
+import httpx
+import typer
+from rich.console import Console
+
+from . import config
+
+err = Console(stderr=True)
+
+
+def fail(message: str) -> typer.Exit:
+    err.print(f"[red]✗[/red] {message}")
+    return typer.Exit(1)
+
+
+class Api:
+    """Authenticated client. Instantiating without a stored token exits."""
+
+    def __init__(self) -> None:
+        tok = config.token()
+        if not tok:
+            raise fail("Not logged in — run [bold]pyvolt login[/bold] first.")
+        self.base = config.api_url()
+        self.http = httpx.Client(
+            base_url=self.base + "/api",
+            headers={"Authorization": f"Bearer {tok}"},
+            timeout=30,
+        )
+
+    def request(self, method: str, path: str, *, ok=(200, 201), **kw) -> httpx.Response:
+        try:
+            r = self.http.request(method, path, **kw)
+        except httpx.HTTPError as e:
+            raise fail(f"Could not reach {self.base}: {e}") from e
+        if r.status_code == 401:
+            raise fail("Token rejected (revoked or expired) — run [bold]pyvolt login[/bold] again.")
+        if r.status_code == 404:
+            raise fail("Not found.")
+        if r.status_code not in ok:
+            raise fail(f"API error {r.status_code}: {r.text[:200]}")
+        return r
+
+    def get(self, path: str, **kw):
+        return self.request("GET", path, **kw).json()
+
+    def post(self, path: str, *, ok=(200, 201), **kw) -> httpx.Response:
+        return self.request("POST", path, ok=ok, **kw)
+
+    def delete(self, path: str, **kw):
+        return self.request("DELETE", path, **kw).json()
+
+    # -- resolution ---------------------------------------------------------
+
+    def resolve_server(self, name: str) -> dict:
+        """Match a server by exact name, else unambiguous substring."""
+        servers = self.get("/v1/servers")
+        exact = [s for s in servers if s["name"] == name]
+        if exact:
+            return exact[0]
+        matches = [s for s in servers if name.lower() in s["name"].lower()]
+        if len(matches) == 1:
+            return matches[0]
+        if not matches:
+            known = ", ".join(s["name"] for s in servers) or "none yet"
+            raise fail(f"No server matches [bold]{name}[/bold]. Your servers: {known}")
+        ambiguous = ", ".join(s["name"] for s in matches)
+        raise fail(f"[bold]{name}[/bold] is ambiguous: {ambiguous}")
+
+    def resolve_app(self, name: str) -> dict:
+        """Match an app by exact domain, else unambiguous substring."""
+        apps = self.get("/v1/apps")
+        exact = [a for a in apps if a["domain"] == name]
+        if exact:
+            return exact[0]
+        matches = [a for a in apps if name.lower() in a["domain"].lower()]
+        if len(matches) == 1:
+            return matches[0]
+        if not matches:
+            known = ", ".join(a["domain"] for a in apps) or "none yet"
+            raise fail(f"No app matches [bold]{name}[/bold]. Your apps: {known}")
+        ambiguous = ", ".join(a["domain"] for a in matches)
+        raise fail(f"[bold]{name}[/bold] is ambiguous: {ambiguous}")

pyvolt_cli-0.2.0/pyvolt_cli/config.py

@@ -0,0 +1,56 @@
+"""Credentials + endpoint resolution.
+
+Token lives in ~/.config/pyvolt/credentials.toml (mode 600). Environment
+overrides — PYVOLT_TOKEN, PYVOLT_API_URL — win over the file, so CI and
+local-dev instances need no config file at all.
+"""
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+
+DEFAULT_API_URL = "https://pyvolt.com"
+
+
+def config_dir() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(base) / "pyvolt"
+
+
+def credentials_path() -> Path:
+    return config_dir() / "credentials.toml"
+
+
+def _load() -> dict:
+    p = credentials_path()
+    if not p.exists():
+        return {}
+    try:
+        return tomllib.loads(p.read_text())
+    except tomllib.TOMLDecodeError:
+        return {}
+
+
+def api_url() -> str:
+    return (os.environ.get("PYVOLT_API_URL") or _load().get("api_url") or DEFAULT_API_URL).rstrip("/")
+
+
+def token() -> str | None:
+    return os.environ.get("PYVOLT_TOKEN") or _load().get("token")
+
+
+def save(tok: str, api: str | None = None) -> Path:
+    d = config_dir()
+    d.mkdir(parents=True, exist_ok=True)
+    lines = [f'token = "{tok}"']
+    if api and api.rstrip("/") != DEFAULT_API_URL:
+        lines.append(f'api_url = "{api.rstrip("/")}"')
+    p = credentials_path()
+    p.write_text("\n".join(lines) + "\n")
+    p.chmod(0o600)
+    return p
+
+
+def clear() -> None:
+    credentials_path().unlink(missing_ok=True)

pyvolt_cli-0.0.1/PKG-INFO

@@ -1,65 +0,0 @@
-Metadata-Version: 2.4
-Name: pyvolt-cli
-Version: 0.0.1
-Summary: The command-line companion to pyvolt: managed Python deployments on infrastructure you actually own.
-Project-URL: Homepage, https://pyvolt.com
-Project-URL: Repository, https://github.com/pyvolt-hq/pyvolt-cli
-Project-URL: Issues, https://github.com/pyvolt-hq/pyvolt-cli/issues
-Author-email: Will Abbott <will@digitaloutback.co.uk>
-Maintainer-email: PyVolt HQ <will@digitaloutback.co.uk>
-License: MIT
-License-File: LICENSE
-Keywords: deployment,digitalocean,django,fastapi,flask,hetzner,paas,python,vps
-Classifier: Development Status :: 1 - Planning
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Software Development :: Build Tools
-Classifier: Topic :: System :: Installation/Setup
-Classifier: Topic :: System :: Systems Administration
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-
-# pyvolt-cli
-
-The terminal companion to [pyvolt](https://pyvolt.com): managed Python deployments on infrastructure you actually own.
-
-## Status
-
-This is a **placeholder release (0.0.1)**. It installs the `pyvolt` command onto `$PATH` and prints a "coming soon" banner. Real subcommands (`pyvolt deploy`, `pyvolt logs`, `pyvolt scale`, and friends) land in a future release.
-
-Follow along at:
-
-- Website: <https://pyvolt.com>
-- Repository: <https://github.com/pyvolt-hq/pyvolt-cli>
-- Issues: <https://github.com/pyvolt-hq/pyvolt-cli/issues>
-
-## Install
-
-```bash
-pip install pyvolt-cli
-```
-
-The distribution name on PyPI is `pyvolt-cli`; the installed command on your `$PATH` is `pyvolt`.
-
-## Verify
-
-```bash
-pyvolt
-```
-
-Prints the version banner. If you see it, the entry point is wired correctly.
-
-## Requires
-
-Python 3.10 or newer.
-
-## License
-
-MIT. See [LICENSE](LICENSE).

pyvolt_cli-0.0.1/README.md

@@ -1,37 +0,0 @@
-# pyvolt-cli
-
-The terminal companion to [pyvolt](https://pyvolt.com): managed Python deployments on infrastructure you actually own.
-
-## Status
-
-This is a **placeholder release (0.0.1)**. It installs the `pyvolt` command onto `$PATH` and prints a "coming soon" banner. Real subcommands (`pyvolt deploy`, `pyvolt logs`, `pyvolt scale`, and friends) land in a future release.
-
-Follow along at:
-
-- Website: <https://pyvolt.com>
-- Repository: <https://github.com/pyvolt-hq/pyvolt-cli>
-- Issues: <https://github.com/pyvolt-hq/pyvolt-cli/issues>
-
-## Install
-
-```bash
-pip install pyvolt-cli
-```
-
-The distribution name on PyPI is `pyvolt-cli`; the installed command on your `$PATH` is `pyvolt`.
-
-## Verify
-
-```bash
-pyvolt
-```
-
-Prints the version banner. If you see it, the entry point is wired correctly.
-
-## Requires
-
-Python 3.10 or newer.
-
-## License
-
-MIT. See [LICENSE](LICENSE).

pyvolt_cli-0.0.1/pyvolt_cli/__init__.py

@@ -1,8 +0,0 @@
-"""pyvolt-cli: the terminal companion to pyvolt.
-
-This is a placeholder release that reserves the ``pyvolt`` command on the
-user's ``$PATH``. Real subcommands land in a future release. See
-https://pyvolt.com for status.
-"""
-
-__version__ = "0.0.1"

pyvolt_cli-0.0.1/pyvolt_cli/__main__.py

@@ -1,32 +0,0 @@
-"""Entry point for the ``pyvolt`` command.
-
-The pyproject.toml maps ``[project.scripts] pyvolt`` to :func:`main` in this
-module. Running ``pyvolt`` after ``pip install pyvolt-cli`` lands here.
-"""
-
-from __future__ import annotations
-
-import sys
-
-from . import __version__
-
-
-BANNER = f"""
-pyvolt {__version__}
-
-Managed Python deployments on infrastructure you actually own.
-
-This CLI is a placeholder release. Real subcommands land in a future
-version. Track progress at https://pyvolt.com and
-https://github.com/pyvolt-hq/pyvolt-cli.
-""".strip()
-
-
-def main() -> int:
-    """Print a coming-soon banner and exit cleanly."""
-    print(BANNER)
-    return 0
-
-
-if __name__ == "__main__":  # pragma: no cover
-    sys.exit(main())