urun-cli 0.4.0__tar.gz → 0.5.0__tar.gz

urun_cli-0.5.0/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+## Unreleased
+
+- Make `urun deploy` resilient to transient network blips. The manifest/blob
+  push and the "Waiting for build to complete" build-status poll now retry on
+  transient failures (read/connect timeouts, connection resets, 5xx, 429) with
+  exponential backoff + jitter (base 1s, factor 2, cap 30s) instead of fatally
+  exiting on the first `network error: The read operation timed out`. A single
+  failed status read backs off and re-polls — the build continues server-side —
+  while a real build failure or a 4xx auth/validation error still fails fast and
+  loud. Every retry is logged (`transient ...; retrying in Ns`) so backoff is
+  visible, never silent. New `urun.retry` module centralizes the
+  transient-vs-terminal classification and backoff policy.
+
+- Add experimental `urun list apps` subcommand. Reads from a new control-plane
+  endpoint `GET /apps` (server-side edge function not yet shipped). The STATUS
+  column projects the app's current lifecycle phase to one of `provisioning`,
+  `ready`, `pending`, `paused`, or `failed`; see the README or
+  `urun list apps --help` for the full mapping. Supports `--json` for the raw
+  payload.
+- Add experimental `urun list sessions` subcommand. Lists live and historical
+  sessions for the org, with per-row STARTED / DURATION / STATE / DETAIL.
+  Newest sessions print at the bottom of the table (tail-friendly). Supports
+  `--limit` (default 100), `--state` (filter to a single backend
+  status), and `--json`. Reads from a new control-plane endpoint
+  `GET /sessions` (server-side edge function not yet shipped).
+- Add experimental `urun list compute` subcommand. Lists the compute slices
+  the org currently has provisioned, broken down per (app, function,
+  compute_shape) with INSTANCES (allocated/ready), GPU UNITS
+  (allocated/ready), live SESSIONS count, and snapshot AGE. Slices with no
+  provisioned GPU units are omitted server-side so the listing reflects
+  what is running right now (`urun list apps` for the full deployment
+  catalogue; `urun list sessions` for history). Supports `--limit`
+  (default 100) and `--json`. Reads from a new control-plane
+  endpoint `GET /compute` (server-side edge function not yet shipped).
+- Add experimental `urun app status|scale|delete|activate` lifecycle commands
+  for managing a single deployed app (addressed by slug, org-scoped via the API
+  key). `app status` shows the build/deployment/capacity/live-session rollup;
+  `app scale --replicas N` sets the deployment's desired replica count (use 0 to
+  drain; GPU/shape stay fixed at deploy time, so only `--replicas` is exposed);
+  `app delete` (alias `app rm`) retires an app — driving it to `paused`/
+  `disabled` so the control-plane materializer stops recreating its runtime —
+  with an interactive confirmation (`--yes` to skip); `app activate` reverses a
+  retire. All accept `--environment` (default `prod`) and `--json`. Backed by a
+  new server-side `app` edge function (`GET /app/<slug>`,
+  `POST /app/<slug>/scale`, `DELETE /app/<slug>`, `POST /app/<slug>/activate`).
+
+## 0.3.0
+
+- Implement the `urun org` / `urun org id` command: print the caller's org id
+  (resolved via the control-plane org-config endpoint).
+- Implement `urun auth jwks set`: register the org's trusted JWKS for federated
+  identity, via `--jwks-url` or `--jwks-json` (file or stdin), with optional
+  `--issuer`/`--audience`. This registers a trust relationship only; JWTs are
+  issued out of band and the CLI never mints, fetches, or stores one.
+- Add `ApiClient.register_trusted_jwks`, calling `POST /org-config/trusted-jwks`.
+
+## 0.2.0
+
+- Bumped past 0.1.1/0.1.2 because both filenames were occupied by previously-deleted PyPI artifacts.
+- Drop the org-id requirement from `urun deploy`; authentication now relies solely on the API key.
+- Add `urun login`, `urun run`, and `urun org`/`urun auth` subcommands.
+
+## 0.1.0
+
+- Initial public `urun deploy` CLI.
+- Deploy from a Python app file with local Python imports included automatically.
+- Source manifest generation, dependency declaration upload, and API deploy flow.
+- Public docs for the config-free v1 CLI surface.

urun_cli-0.5.0/PKG-INFO

@@ -0,0 +1,321 @@
+Metadata-Version: 2.4
+Name: urun-cli
+Version: 0.5.0
+Summary: End-user CLI for deploying apps to urun
+Project-URL: Homepage, https://urun.sh
+Project-URL: Repository, https://github.com/urun-sh/urun-cli
+Project-URL: Issues, https://github.com/urun-sh/urun-cli/issues
+Author: urun
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,deploy,urun
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# urun CLI
+
+Deploy Python apps to urun from your terminal.
+
+[![PyPI](https://img.shields.io/pypi/v/urun-cli.svg)](https://pypi.org/project/urun-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/urun-cli.svg)](https://pypi.org/project/urun-cli/)
+
+## Install
+
+```bash
+uv tool install urun-cli
+# or
+pip install urun-cli
+```
+
+The package installs the `urun` command:
+
+```bash
+urun --version
+```
+
+For one-off `uvx` usage:
+
+```bash
+uvx --from urun-cli urun --version
+# or the package-matching command alias
+uvx urun-cli --version
+```
+
+## Quick start
+
+Today, an operator manually vends an org-scoped deploy API key. Save it locally
+with `urun login`:
+
+```bash
+urun login --api-key urun_<32hex>
+```
+
+`urun login` verifies the key with the urun API and stores credentials for later
+commands. The future browser-based login flow is not available in this CLI
+release.
+
+For CI or one-off commands, you can still use the environment variable:
+
+```bash
+export URUN_API_KEY=urun_<32hex>
+```
+
+Create `app.py`:
+
+```python
+import urun
+from urun import App
+
+app = App("hello-h100")
+
+
+@app.function(gpus="h100:1")
+def hello(ctx: urun.Context):
+    print(f"running on {ctx.device}")
+    return {"device": str(ctx.device)}
+```
+
+Run it:
+
+```bash
+urun run app.py
+```
+
+In this release, `urun run` uses the same deploy pipeline as `urun deploy`.
+`deploy` remains available as the lower-level command while the full
+deploy/run/monitor workflow is being built.
+
+## Inspect apps
+
+List every app deployed in your org and its current status:
+
+```bash
+urun list apps
+```
+
+Sample output:
+
+```text
+APP                    FUNCTION        COMPUTE  STATUS         RELEASE       DETAIL
+causal-forcing-stream  generate_video  h100:1   ready          fa61f31b0961  0/1 GPU units in use
+queued-app             warmup          a10:1    provisioning   000000000000  building
+```
+
+The STATUS column is one of `provisioning`, `ready`, `pending`, `paused`, or
+`failed`. It is derived from three backend signals reporting on sequential
+lifecycle phases:
+
+| Build (S3 status)      | Promotion (`app_deployments`) | Capacity (`function_ready`) | STATUS         |
+| ---------------------- | ----------------------------- | --------------------------- | -------------- |
+| `queued` \| `building` | (no row yet)                  | -                           | `provisioning` |
+| `failed`               | (no row yet)                  | -                           | `failed`       |
+| `ready`                | `active`                      | `false`                     | `pending`      |
+| `ready`                | `active`                      | `true`                      | `ready`        |
+| `ready`                | `paused`                      | (irrelevant)                | `paused`       |
+| `ready`                | `failed`                      | (irrelevant)                | `failed`       |
+
+The DETAIL column carries the disambiguating signal (raw build state, error
+message, `ready_reason`, or in-use GPU counts). Pass `--json` for the raw
+payload.
+
+This command is **experimental** and requires the server-side `GET /apps`
+endpoint, which is in development.
+
+## Inspect sessions
+
+List live and historical sessions in your org. Newest sessions appear at the
+**bottom** of the table so the command works well with `tail`:
+
+```bash
+urun list sessions
+urun list sessions | tail -20
+urun list sessions --state failed
+urun list sessions --limit 500
+```
+
+Sample output:
+
+```text
+ID            APP                FUNCTION        SHAPE    STARTED               DURATION  STATE       DETAIL
+2cc8a91f4b3d  helios             world_gen       h100:4   2026-06-02 10:55 UTC       44s  failed      no_capacity
+3f0017daee01  helios             world_gen       h100:1   2026-06-02 11:08 UTC    18m43s  completed   client_disconnect
+4a1c886e2d0a  causal-forcing-…   generate_video  h100:1   2026-06-02 14:21 UTC     3m12s  live        -
+```
+
+The STATE column maps the raw backend status to a user-friendly label:
+
+| Backend status | STATE       |
+| -------------- | ----------- |
+| `allocated`    | `starting`  |
+| `connected`    | `live`      |
+| `closed`       | `completed` |
+| `failed`       | `failed`    |
+| `cancelled`    | `cancelled` |
+
+DURATION is computed from `allocated_at` to `closed_at` for terminal sessions,
+or `allocated_at` to now for live ones. DETAIL carries `close_reason` when
+present. Pass `--json` for the raw payload (full IDs, ISO timestamps, all
+fields).
+
+Pass `--limit` to control how many rows are fetched (default 100).
+
+This command is **experimental** and requires the server-side `GET /sessions`
+endpoint, which is in development.
+
+## Inspect active compute
+
+List the compute slices your org currently has provisioned:
+
+```bash
+urun list compute
+```
+
+Sample output:
+
+```text
+APP                    FUNCTION        SHAPE   INSTANCES  GPU UNITS  SESSIONS  AGE
+causal-forcing-stream  generate_video  h100:1  1/2        1/2        1         12s
+helios                 world_gen       h100:4  0/1        0/4        0         3m
+```
+
+Each row is one actively provisioned `(app, function, compute_shape)`
+slice. `INSTANCES` and `GPU UNITS` show `<allocated>/<provisioned>` — a
+row with `0/1` is an idle warm runtime with no active sessions on it.
+`SESSIONS` is the live session count. `AGE` is how stale the capacity
+snapshot is; very old ages may indicate the runtime is no longer
+reporting.
+
+Slices with no provisioned capacity are omitted, so this command answers
+"what is running right now". For the full deployment catalogue
+(including paused / failed / unprovisioned apps) use `urun list apps`;
+for historical or in-flight sessions use `urun list sessions`.
+
+Pass `--limit` to control how many rows are fetched (default 100).
+
+This command is **experimental** and requires the server-side `GET /compute`
+endpoint, which is in development.
+
+## Manage apps
+
+Manage the lifecycle of a single deployed app. The app is addressed by its
+slug (the name shown under `APP` in `urun list apps`); every operation is
+org-scoped via your API key.
+
+Show detailed status for one app (the single-app complement to `list apps`):
+
+```bash
+urun app status lingbot
+```
+
+```text
+            App: lingbot
+           Name: LingBot
+    Environment: prod
+     App status: active
+     Deployment: active
+Desired replicas: 2
+       Function: handle_lingbot_runtime
+        Compute: b200:4
+            GPU: 4 x b200
+        Release: 1c6d6287abcd
+  Live sessions: 1
+```
+
+Scale an app's runtime replica count (the backend's scaling knob; the
+control plane turns it into the runtime StatefulSet replica count):
+
+```bash
+urun app scale lingbot --replicas 3
+urun app scale lingbot --replicas 0   # drain to zero without retiring
+```
+
+GPU count and compute shape are fixed at deploy time per release (set via
+`@app.function`), so `scale` intentionally exposes only `--replicas`.
+
+Retire an app so the control plane stops running it (drives the deployment
+to `paused` and the app to `disabled`, so the materializer stops recreating
+its runtime). This is the clean, reversible, API-driven alternative to a
+manual database edit:
+
+```bash
+urun app delete lingbot-handle      # prompts for confirmation
+urun app delete lingbot-handle --yes  # or urun app rm lingbot-handle --yes
+```
+
+Reverse a retire and bring the app back online:
+
+```bash
+urun app activate lingbot-handle
+```
+
+All `app` subcommands accept `--environment` (default `prod`) and `--json`.
+These commands are **experimental** and require the server-side `app`
+lifecycle endpoint, which is in development.
+
+## What gets deployed
+
+`urun deploy` creates a source manifest from your Python entrypoint:
+
+| Entrypoint | Included source |
+| --- | --- |
+| `urun deploy app.py` | `app.py` and local Python files it imports |
+
+Dependencies are declared in your urun app code. Project-level files such as
+`pyproject.toml` and `requirements.txt` are not uploaded as dependency
+declarations by the CLI.
+
+Generated/cache content such as `.git`, dotfiles, `__pycache__`, and `.pyc`
+files is excluded. Add `.urunignore` to exclude additional paths.
+
+Non-Python assets such as templates, static files, and data files are not
+auto-included yet.
+
+## Common options
+
+Shared by `run` and `deploy`:
+
+| Option | Description |
+| --- | --- |
+| `--name` | Override the derived app name. |
+| `--api-url` | Override the API URL; defaults to `URUN_API_URL`, saved login credentials, or `https://api.urun.sh/v1`. |
+| `--api-key` | Deploy API key; defaults to `URUN_API_KEY` or saved login credentials. |
+| `--no-wait` | Finalize but do not poll for readiness. |
+| `--poll-interval`, `--timeout` | Control readiness polling. |
+
+## Troubleshooting
+
+| Error | Fix |
+| --- | --- |
+| `missing API key` | Run `urun login`, set `URUN_API_KEY`, or pass `--api-key`. |
+| `invalid API key format` | Use `urun_<32 lowercase hex chars>`. |
+| `entrypoint not found` | Run from the project root or pass the entrypoint path. |
+| `path is outside the project root` | Move the file under the project before deploying. |
+| Expected files are missing | Import local Python files from `app.py`; non-Python assets are not auto-included yet. |
+
+## Development
+
+Contributing and test instructions are in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT.
+
+## Development environment
+
+This repo has a Nix/direnv/devcontainer baseline:
+
+```bash
+direnv allow
+just sync
+just check
+```
+
+Use VS Code Dev Containers to open the repository with the same toolchain in a container. Copy `devcontainer.env.example` to `.devcontainer.env` if you need to pass local git identity or other non-secret development settings into the container.

urun_cli-0.5.0/README.md

@@ -0,0 +1,299 @@
+# urun CLI
+
+Deploy Python apps to urun from your terminal.
+
+[![PyPI](https://img.shields.io/pypi/v/urun-cli.svg)](https://pypi.org/project/urun-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/urun-cli.svg)](https://pypi.org/project/urun-cli/)
+
+## Install
+
+```bash
+uv tool install urun-cli
+# or
+pip install urun-cli
+```
+
+The package installs the `urun` command:
+
+```bash
+urun --version
+```
+
+For one-off `uvx` usage:
+
+```bash
+uvx --from urun-cli urun --version
+# or the package-matching command alias
+uvx urun-cli --version
+```
+
+## Quick start
+
+Today, an operator manually vends an org-scoped deploy API key. Save it locally
+with `urun login`:
+
+```bash
+urun login --api-key urun_<32hex>
+```
+
+`urun login` verifies the key with the urun API and stores credentials for later
+commands. The future browser-based login flow is not available in this CLI
+release.
+
+For CI or one-off commands, you can still use the environment variable:
+
+```bash
+export URUN_API_KEY=urun_<32hex>
+```
+
+Create `app.py`:
+
+```python
+import urun
+from urun import App
+
+app = App("hello-h100")
+
+
+@app.function(gpus="h100:1")
+def hello(ctx: urun.Context):
+    print(f"running on {ctx.device}")
+    return {"device": str(ctx.device)}
+```
+
+Run it:
+
+```bash
+urun run app.py
+```
+
+In this release, `urun run` uses the same deploy pipeline as `urun deploy`.
+`deploy` remains available as the lower-level command while the full
+deploy/run/monitor workflow is being built.
+
+## Inspect apps
+
+List every app deployed in your org and its current status:
+
+```bash
+urun list apps
+```
+
+Sample output:
+
+```text
+APP                    FUNCTION        COMPUTE  STATUS         RELEASE       DETAIL
+causal-forcing-stream  generate_video  h100:1   ready          fa61f31b0961  0/1 GPU units in use
+queued-app             warmup          a10:1    provisioning   000000000000  building
+```
+
+The STATUS column is one of `provisioning`, `ready`, `pending`, `paused`, or
+`failed`. It is derived from three backend signals reporting on sequential
+lifecycle phases:
+
+| Build (S3 status)      | Promotion (`app_deployments`) | Capacity (`function_ready`) | STATUS         |
+| ---------------------- | ----------------------------- | --------------------------- | -------------- |
+| `queued` \| `building` | (no row yet)                  | -                           | `provisioning` |
+| `failed`               | (no row yet)                  | -                           | `failed`       |
+| `ready`                | `active`                      | `false`                     | `pending`      |
+| `ready`                | `active`                      | `true`                      | `ready`        |
+| `ready`                | `paused`                      | (irrelevant)                | `paused`       |
+| `ready`                | `failed`                      | (irrelevant)                | `failed`       |
+
+The DETAIL column carries the disambiguating signal (raw build state, error
+message, `ready_reason`, or in-use GPU counts). Pass `--json` for the raw
+payload.
+
+This command is **experimental** and requires the server-side `GET /apps`
+endpoint, which is in development.
+
+## Inspect sessions
+
+List live and historical sessions in your org. Newest sessions appear at the
+**bottom** of the table so the command works well with `tail`:
+
+```bash
+urun list sessions
+urun list sessions | tail -20
+urun list sessions --state failed
+urun list sessions --limit 500
+```
+
+Sample output:
+
+```text
+ID            APP                FUNCTION        SHAPE    STARTED               DURATION  STATE       DETAIL
+2cc8a91f4b3d  helios             world_gen       h100:4   2026-06-02 10:55 UTC       44s  failed      no_capacity
+3f0017daee01  helios             world_gen       h100:1   2026-06-02 11:08 UTC    18m43s  completed   client_disconnect
+4a1c886e2d0a  causal-forcing-…   generate_video  h100:1   2026-06-02 14:21 UTC     3m12s  live        -
+```
+
+The STATE column maps the raw backend status to a user-friendly label:
+
+| Backend status | STATE       |
+| -------------- | ----------- |
+| `allocated`    | `starting`  |
+| `connected`    | `live`      |
+| `closed`       | `completed` |
+| `failed`       | `failed`    |
+| `cancelled`    | `cancelled` |
+
+DURATION is computed from `allocated_at` to `closed_at` for terminal sessions,
+or `allocated_at` to now for live ones. DETAIL carries `close_reason` when
+present. Pass `--json` for the raw payload (full IDs, ISO timestamps, all
+fields).
+
+Pass `--limit` to control how many rows are fetched (default 100).
+
+This command is **experimental** and requires the server-side `GET /sessions`
+endpoint, which is in development.
+
+## Inspect active compute
+
+List the compute slices your org currently has provisioned:
+
+```bash
+urun list compute
+```
+
+Sample output:
+
+```text
+APP                    FUNCTION        SHAPE   INSTANCES  GPU UNITS  SESSIONS  AGE
+causal-forcing-stream  generate_video  h100:1  1/2        1/2        1         12s
+helios                 world_gen       h100:4  0/1        0/4        0         3m
+```
+
+Each row is one actively provisioned `(app, function, compute_shape)`
+slice. `INSTANCES` and `GPU UNITS` show `<allocated>/<provisioned>` — a
+row with `0/1` is an idle warm runtime with no active sessions on it.
+`SESSIONS` is the live session count. `AGE` is how stale the capacity
+snapshot is; very old ages may indicate the runtime is no longer
+reporting.
+
+Slices with no provisioned capacity are omitted, so this command answers
+"what is running right now". For the full deployment catalogue
+(including paused / failed / unprovisioned apps) use `urun list apps`;
+for historical or in-flight sessions use `urun list sessions`.
+
+Pass `--limit` to control how many rows are fetched (default 100).
+
+This command is **experimental** and requires the server-side `GET /compute`
+endpoint, which is in development.
+
+## Manage apps
+
+Manage the lifecycle of a single deployed app. The app is addressed by its
+slug (the name shown under `APP` in `urun list apps`); every operation is
+org-scoped via your API key.
+
+Show detailed status for one app (the single-app complement to `list apps`):
+
+```bash
+urun app status lingbot
+```
+
+```text
+            App: lingbot
+           Name: LingBot
+    Environment: prod
+     App status: active
+     Deployment: active
+Desired replicas: 2
+       Function: handle_lingbot_runtime
+        Compute: b200:4
+            GPU: 4 x b200
+        Release: 1c6d6287abcd
+  Live sessions: 1
+```
+
+Scale an app's runtime replica count (the backend's scaling knob; the
+control plane turns it into the runtime StatefulSet replica count):
+
+```bash
+urun app scale lingbot --replicas 3
+urun app scale lingbot --replicas 0   # drain to zero without retiring
+```
+
+GPU count and compute shape are fixed at deploy time per release (set via
+`@app.function`), so `scale` intentionally exposes only `--replicas`.
+
+Retire an app so the control plane stops running it (drives the deployment
+to `paused` and the app to `disabled`, so the materializer stops recreating
+its runtime). This is the clean, reversible, API-driven alternative to a
+manual database edit:
+
+```bash
+urun app delete lingbot-handle      # prompts for confirmation
+urun app delete lingbot-handle --yes  # or urun app rm lingbot-handle --yes
+```
+
+Reverse a retire and bring the app back online:
+
+```bash
+urun app activate lingbot-handle
+```
+
+All `app` subcommands accept `--environment` (default `prod`) and `--json`.
+These commands are **experimental** and require the server-side `app`
+lifecycle endpoint, which is in development.
+
+## What gets deployed
+
+`urun deploy` creates a source manifest from your Python entrypoint:
+
+| Entrypoint | Included source |
+| --- | --- |
+| `urun deploy app.py` | `app.py` and local Python files it imports |
+
+Dependencies are declared in your urun app code. Project-level files such as
+`pyproject.toml` and `requirements.txt` are not uploaded as dependency
+declarations by the CLI.
+
+Generated/cache content such as `.git`, dotfiles, `__pycache__`, and `.pyc`
+files is excluded. Add `.urunignore` to exclude additional paths.
+
+Non-Python assets such as templates, static files, and data files are not
+auto-included yet.
+
+## Common options
+
+Shared by `run` and `deploy`:
+
+| Option | Description |
+| --- | --- |
+| `--name` | Override the derived app name. |
+| `--api-url` | Override the API URL; defaults to `URUN_API_URL`, saved login credentials, or `https://api.urun.sh/v1`. |
+| `--api-key` | Deploy API key; defaults to `URUN_API_KEY` or saved login credentials. |
+| `--no-wait` | Finalize but do not poll for readiness. |
+| `--poll-interval`, `--timeout` | Control readiness polling. |
+
+## Troubleshooting
+
+| Error | Fix |
+| --- | --- |
+| `missing API key` | Run `urun login`, set `URUN_API_KEY`, or pass `--api-key`. |
+| `invalid API key format` | Use `urun_<32 lowercase hex chars>`. |
+| `entrypoint not found` | Run from the project root or pass the entrypoint path. |
+| `path is outside the project root` | Move the file under the project before deploying. |
+| Expected files are missing | Import local Python files from `app.py`; non-Python assets are not auto-included yet. |
+
+## Development
+
+Contributing and test instructions are in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT.
+
+## Development environment
+
+This repo has a Nix/direnv/devcontainer baseline:
+
+```bash
+direnv allow
+just sync
+just check
+```
+
+Use VS Code Dev Containers to open the repository with the same toolchain in a container. Copy `devcontainer.env.example` to `.devcontainer.env` if you need to pass local git identity or other non-secret development settings into the container.

{urun_cli-0.4.0 → urun_cli-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "urun-cli"
-version = "0.4.0"
+version = "0.5.0"
 description = "End-user CLI for deploying apps to urun"
 readme = "README.md"
 requires-python = ">=3.11"