feat(serverless): align the CLI with the 0.6.0 control plane

README.md

@@ -2,7 +2,7 @@
 
 A command-line tool for interacting with the [Runware](https://runware.ai) API. Built in Go, distributed as a single static binary.
 
-Run image generation, video generation, audio generation, 3D, upscaling, background removal, captioning, search models, and more.
+Run image generation, video generation, audio generation, 3D, upscaling, background removal, captioning, search models, deploy serverless applications, and more.
 
 ## Install
 
@@ -47,6 +47,9 @@ runware run runware:400@1 positivePrompt="a chess match in the park" width=1024
 
 # Check your account details
 runware account details
+
+# Deploy a serverless application
+runware serverless deploy ./app.py --id my-app --gpu-type h100
 ```
 
 ## Commands
@@ -212,6 +215,20 @@ runware result <taskUUID>       # Resume waiting for an async task by UUID
 
 Use when `runware run` was interrupted before a task completed. The taskUUID is printed when the task is first submitted.
 
+### `runware serverless` — applications
+
+Deploy and manage Runware serverless applications.
+
+```shell
+runware serverless deploy ./app.py --id my-app --gpu-type h100
+runware serverless apps list
+runware serverless apps show my-app
+runware serverless apps invoke my-app infer -f payload.json --wait
+runware serverless apps logs my-app --follow
+```
+
+Full command reference is under [docs/runware_serverless.md](./docs/runware_serverless.md).
+
 ### Other
 
 ```shell

api/serverless/openapi.yaml

@@ -434,6 +434,8 @@ paths:
                 $ref: '#/components/schemas/App'
         '401':
           $ref: '#/components/responses/Unauthorized'
+        '402':
+          $ref: '#/components/responses/PaymentRequired'
         '503':
           $ref: '#/components/responses/ServiceUnavailable'
         '403':
@@ -545,6 +547,8 @@ paths:
                 $ref: '#/components/schemas/App'
         '401':
           $ref: '#/components/responses/Unauthorized'
+        '402':
+          $ref: '#/components/responses/PaymentRequired'
         '503':
           $ref: '#/components/responses/ServiceUnavailable'
         '403':
@@ -829,6 +833,8 @@ paths:
           $ref: '#/components/responses/BadRequest'
         '401':
           $ref: '#/components/responses/Unauthorized'
+        '402':
+          $ref: '#/components/responses/PaymentRequired'
         '503':
           $ref: '#/components/responses/ServiceUnavailable'
         '403':
@@ -898,6 +904,8 @@ paths:
                 $ref: '#/components/schemas/App'
         '401':
           $ref: '#/components/responses/Unauthorized'
+        '402':
+          $ref: '#/components/responses/PaymentRequired'
         '503':
           $ref: '#/components/responses/ServiceUnavailable'
         '403':
@@ -906,6 +914,8 @@ paths:
           $ref: '#/components/responses/NotFound'
         '409':
           $ref: '#/components/responses/Conflict'
+        '422':
+          $ref: '#/components/responses/ValidationError'
 
   /v1/apps/{appId}/favourite:
     put:
@@ -1317,7 +1327,7 @@ paths:
         terminal `stopped` rows until purged). Omitted `versionId` scopes the page
         to the app's `activeVersionId`. An app with no active version therefore
         answers an empty default page — not that it has no workers, only that
-        none are pinned. Optional `state` and `status` narrow the page further;
+        none are pinned.         Optional `state`, `status` and `q` narrow the page further;
         a cursor must be replayed under the same filters it was issued with.
       operationId: listWorkers
       parameters:
@@ -1353,6 +1363,18 @@ paths:
           required: false
           schema:
             $ref: '#/components/schemas/WorkerStatus'
+        - name: q
+          in: query
+          required: false
+          description: >
+            Case-insensitive literal substring match against `id`, `podName`,
+            `nodeName` and `versionId`. A worker matching any field is returned
+            within the selected version, state and status filters. Omit `q` to
+            disable search. Cursors must retain the same search term, ignoring case.
+          schema:
+            type: string
+            minLength: 1
+            maxLength: 100
       responses:
         '200':
           description: A page of workers
@@ -2327,15 +2349,20 @@ paths:
         - Observability
       summary: Read one page of a named log query
       description: >
-        Returns one page of log entries, newest first, with an opaque cursor for the next
-        page when one exists. Query ids and their supported selectors are listed by the
-        insights catalogue.
+        Returns one page of log entries in the requested `sort` order, newest first by
+        default, with opaque cursors for the neighbouring pages when they exist.
+        `nextCursor` continues in the `sort` order and `prevCursor` goes back against it,
+        so a client can walk a window in either direction from either end. A cursor is only
+        valid for the `sort` it was issued under; reusing one under the other ordering
+        returns `400`. Query ids and their supported selectors are listed by the insights
+        catalogue.
       operationId: getLogEntries
       parameters:
         - $ref: '#/components/parameters/QueryId'
         - $ref: '#/components/parameters/MetricWindow'
         - $ref: '#/components/parameters/Limit'
         - $ref: '#/components/parameters/Cursor'
+        - $ref: '#/components/parameters/LogSort'
         - $ref: '#/components/parameters/SelectorDeployment'
         - $ref: '#/components/parameters/SelectorEndpoint'
       responses:
@@ -2497,9 +2524,20 @@ components:
       name: cursor
       in: query
       required: false
-      description: Opaque pagination cursor returned as `nextCursor` by a previous call.
+      description: >
+        Opaque pagination cursor returned by a previous call, as `nextCursor` or, on the
+        operations that offer one, `prevCursor`.
       schema:
         type: string
+    LogSort:
+      name: sort
+      in: query
+      required: false
+      description: >
+        Ordering of a log page and the direction `nextCursor` moves in. Only
+        `getLogEntries` accepts it.
+      schema:
+        $ref: '#/components/schemas/LogSort'
 
     QueryId:
       name: queryId
@@ -2686,6 +2724,18 @@ components:
         application/problem+json:
           schema:
             $ref: '#/components/schemas/ProblemDetails'
+    PaymentRequired:
+      description: >
+        The organization's credit cannot cover the capacity the request asks for.
+        The problem `type` is `insufficient-credit` when the available balance
+        is short, and `credit-suspended` when a refund took back credit already
+        spent and every allocation is refused until the balance is funded back.
+        Either way `shortfall` is the amount to add before retrying: the request
+        is unchanged by the refusal and succeeds as sent once the credit is there.
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/ProblemDetails'
     ServiceUnavailable:
       description: A required service is temporarily unavailable
       content:
@@ -3038,6 +3088,15 @@ components:
         - name
         - activity
         - errorRate
+    LogSort:
+      type: string
+      description: >
+        Ordering of a log page. `newest` is the default: the first row is the
+        newest entry and `nextCursor` walks older. `oldest` reverses that.
+      default: newest
+      enum:
+        - newest
+        - oldest
     BuildStatus:
       type: string
       description: Build/validation lifecycle status.
@@ -3463,6 +3522,30 @@ components:
           allOf:
             - $ref: '#/components/schemas/WorkerConfig'
           description: Live worker configuration. Updated via `PATCH /apps/{appId}`.
+        effectiveMaxWorkers:
+          type: integer
+          format: int32
+          minimum: 0
+          nullable: true
+          readOnly: true
+          description: >
+            The worker ceiling the last deploy actually applied, reduced where the
+            organization's credit balance did not back the whole range. The autoscaler
+            cannot grow past it.
+
+
+            It describes what was applied, not what is configured now, and the two can
+            differ. It is taken from the `maxWorkers` of the version that was deployed,
+            so deploying an older version applies that version's ceiling; and a later
+            `PATCH` of `configuration.maxWorkers` does not change it until the next
+            deploy. Read it beside `configuration.maxWorkers` rather than as a bound on
+            it.
+
+
+            `null` means nothing has been applied yet. It is recalculated on every
+            deploy. A committed credit top-up also recalculates a reduced ceiling and
+            restores the funded range automatically; KEDA then grows the workload from
+            queue demand without a customer redeploy.
         runtime:
           $ref: '#/components/schemas/AppRuntime'
         secrets:
@@ -3722,7 +3805,10 @@ components:
           type: integer
           format: int32
           default: 1
-          description: One GPU per worker is currently supported. Historical apps may contain another value.
+          description: >
+            GPUs granted to one worker pod. Create and update accept only the group
+            sizes the cluster grants indivisibly, since a worker holds its GPUs as one
+            such group. Historical apps may contain another value.
         minWorkers:
           type: integer
           format: int32
@@ -3818,9 +3904,19 @@ components:
         gpusPerWorker:
           type: integer
           format: int32
-          minimum: 0
+          enum: [1, 2, 4, 8]
+          x-go-type: int32
           default: 1
-          description: Only 1 is currently supported. Any other value returns 422.
+          description: >
+            GPUs granted to one worker pod. A worker holds its GPUs as one group the
+            cluster grants indivisibly, so the count is one of the advertised group
+            sizes rather than any number in a range. The value must also be a group
+            size admitted by the cluster backing the chosen `gpuType`: a count above 1
+            that cluster does not grant is rejected with a 422 naming
+            `/configuration/gpusPerWorker`, since the pod could never be scheduled.
+            A value above 1 requires an image built after the multi-GPU worker
+            entrypoint; older images serve a single rank while holding every granted
+            GPU.
         minWorkers:
           type: integer
           format: int32
@@ -3899,8 +3995,18 @@ components:
         gpusPerWorker:
           type: integer
           format: int32
-          minimum: 0
-          description: Only 1 is currently supported. Any other value returns 422.
+          enum: [1, 2, 4, 8]
+          x-go-type: int32
+          description: >
+            GPUs granted to one worker pod. A worker holds its GPUs as one group the
+            cluster grants indivisibly, so the count is one of the advertised group
+            sizes rather than any number in a range. The value must also be a group
+            size admitted by the cluster backing the chosen `gpuType`: a count above 1
+            that cluster does not grant is rejected with a 422 naming
+            `/configuration/gpusPerWorker`, since the pod could never be scheduled.
+            A value above 1 requires an image built after the multi-GPU worker
+            entrypoint; older images serve a single rank while holding every granted
+            GPU.
         minWorkers:
           type: integer
           format: int32
@@ -5164,6 +5270,13 @@ components:
             per offending request field.
           items:
             $ref: '#/components/schemas/ProblemError'
+        shortfall:
+          type: string
+          description: >
+            Extension member. Present on `402` credit refusals. The amount of
+            credit to add before retrying the same request. Units match the
+            platform credit display.
+          example: "12.50"
 
     ProblemError:
       type: object
@@ -5316,6 +5429,11 @@ components:
         nextCursor:
           type: string
           description: Opaque; absent on the last page.
+        prevCursor:
+          type: string
+          description: >
+            Opaque; absent on the first page. Walks the opposite direction of
+            `nextCursor` under the same `sort`.
     LogEntry:
       type: object
       required: [time, body]

docs/runware.md

@@ -5,7 +5,7 @@ CLI tool for the Runware API
 ### Synopsis
 
 A command-line tool for interacting with the Runware API.
-Run image generation, video generation, audio generation, 3D, upscaling, background removal, captioning, search models, and more.
+Run image generation, video generation, audio generation, 3D, upscaling, background removal, captioning, search models, deploy serverless applications, and more.
 
 Use of Runware services is subject to our Terms of Service (https://runware.ai/terms) and Privacy Policy (https://runware.ai/privacy).
 

docs/runware_serverless_apps.md

@@ -32,10 +32,12 @@ runware serverless apps [flags]
 * [runware serverless apps delete](runware_serverless_apps_delete.md)	 - Delete a serverless application
 * [runware serverless apps endpoints](runware_serverless_apps_endpoints.md)	 - List and inspect endpoints for a serverless application
 * [runware serverless apps env](runware_serverless_apps_env.md)	 - Manage plain-text environment variables for an application
+* [runware serverless apps errors](runware_serverless_apps_errors.md)	 - List failed inference requests for a serverless application
 * [runware serverless apps events](runware_serverless_apps_events.md)	 - List events for a serverless application
 * [runware serverless apps invoke](runware_serverless_apps_invoke.md)	 - Invoke an application endpoint
 * [runware serverless apps list](runware_serverless_apps_list.md)	 - List serverless applications
 * [runware serverless apps logs](runware_serverless_apps_logs.md)	 - Show or follow logs for a serverless application
+* [runware serverless apps rename](runware_serverless_apps_rename.md)	 - Rename a serverless application
 * [runware serverless apps resume](runware_serverless_apps_resume.md)	 - Resume a stopped serverless application
 * [runware serverless apps scale](runware_serverless_apps_scale.md)	 - Scale a serverless application
 * [runware serverless apps show](runware_serverless_apps_show.md)	 - Show details for a serverless application

docs/runware_serverless_apps_env_set.md

@@ -9,6 +9,10 @@ Create or update one plain-text environment variable.
 Prefer --value-file so the value is not visible in process lists; use
 --value-file - to read from stdin.
 
+A write that changes the stored value records a new version and rolls live
+workers when the application can take one. A write that leaves the value
+unchanged records no version and does not roll.
+
 The server rejects (HTTP 422) reserved platform names, names that collide
 with an attached secret's injected env var, and adding a binding past the
 100-variable-plus-secret ceiling. Overwriting an existing key is always

docs/runware_serverless_apps_errors.md

@@ -0,0 +1,51 @@
+## runware serverless apps errors
+
+List failed inference requests for a serverless application
+
+### Synopsis
+
+List failed inference requests for an application, newest first.
+
+Omit --status-class to include both 4xx and 5xx. The cursor is only valid with
+the same --window and --status-class it was issued under.
+
+```
+runware serverless apps errors <appId> [flags]
+```
+
+### Examples
+
+```
+  # list recent request errors
+  runware serverless apps errors my-app
+
+  # last 24 hours of 5xx only
+  runware serverless apps errors my-app --window 24h --status-class 5xx
+
+  # page through results
+  runware serverless apps errors my-app --limit 50 --cursor <nextCursor>
+```
+
+### Options
+
+```
+      --cursor string         Pagination cursor from a previous nextCursor (reuse the same --window/--status-class)
+  -h, --help                  help for errors
+      --limit int             Maximum number of errors to return (1-100)
+      --status-class string   Filter by status class (4xx or 5xx)
+      --window string         Time window (1h, 6h, 24h, 7d, or 30d)
+```
+
+### Options inherited from parent commands
+
+```
+      --debug              Show full debug output
+  -F, --format string      CLI output format: table, json, yaml (default "table")
+      --transport string   Transport protocol: ws (WebSocket) or http (REST) (default "ws")
+  -v, --verbose            Show request/response details
+```
+
+### SEE ALSO
+
+* [runware serverless apps](runware_serverless_apps.md)	 - Manage deployed serverless applications
+

docs/runware_serverless_apps_invoke.md

@@ -49,6 +49,7 @@ runware serverless apps invoke <appId> <endpointPath> [flags]
       --poll-interval duration   Polling interval when waiting for a task (default 2s)
       --sync                     Use sync invocation and wait for a terminal task
       --task-id string           Client task id (UUID); generated if omitted
+      --timeout duration         Maximum time to wait (0 = no limit)
       --wait                     Poll until the task is completed or failed
 ```