@runtypelabs/cli 2.37.0 → 2.39.0

package/README.md

@@ -673,6 +673,39 @@ runtype dispatch --flow <id> --variable key=value --variable key2=value2
 runtype dispatch --flow <id> --no-stream --json
 ```
 
+#### Execution inputs and machine-readable results
+
+`dispatch`, `flows run`, and `agents execute` accept `--inputs <json>` or
+`--inputs-file <file|->` for typed input variables. Use `-` to read a JSON object
+from stdin. `--variable key=value` remains a repeatable **string** input; use JSON
+for numbers, booleans, arrays, objects, and null. Conflicting input sources and
+duplicate keys are rejected rather than silently overwritten.
+
+```bash
+runtype flows run flow_example --inputs '{"limit":5,"enabled":true}' --json
+printf '%s' '{"customer":{"name":"Alyss"}}' | runtype dispatch --flow flow_example --inputs-file - --json
+runtype agents execute agent_example --message "Summarize these items" --inputs '{"items":[1,2,3]}' --json
+runtype dispatch --flow flow_example --messages-file conversation.json --jsonl
+```
+
+`--messages-file <file|->` supplies a JSON array of messages instead of `--message`.
+Only one source may consume stdin. Input-bearing `agents execute` requests use
+the dispatch API so variables reach the runtime; requests without input variables
+retain the agent execution endpoint.
+
+For these execution commands, `--json` writes one final JSON value to stdout,
+without progress prose or text deltas. `--jsonl` writes structured events one per
+line followed by an `execution_summary` event (also used for buffered results or
+errors). The two formats are mutually exclusive. Diagnostics go to stderr.
+Exit codes are **0** for completion, **1** for failed execution, invalid input,
+authentication errors, or incomplete streams, and **2** when awaiting input or
+approval. Awaiting results do not claim `success: true`. A paused execution is
+not automatically approved or restarted.
+
+CRUD commands that accept a JSON-object `--from-file` through the shared file
+reader also accept `--from-file -`. This does not change commands whose input
+files have a different format, such as batch record-ID arrays.
+
 ### `runtype prompts`
 
 Manage prompts.
@@ -706,6 +739,17 @@ Manage batch operations.
 | `batch status <id>`                          | Check batch job status (`--watch`) |
 | `batch cancel <id>`                          | Cancel a batch job                 |
 
+`batch status --watch` polls in both terminal and nonterminal environments. Use
+`--timeout <ms>` (default `300000`) and `--interval <ms>` (default `2000`) to bound
+the local wait; these options require `--watch`. With `--json`, stdout contains
+one final result, while progress is sent to stderr. Failed or cancelled batches,
+completed batches with failed records, and local timeouts exit nonzero. Timing out
+stops watching only: it does not cancel or resubmit the server batch.
+
+```bash
+runtype batch status batch_example --watch --timeout 600000 --interval 2000 --json
+```
+
 ### `runtype eval`
 
 Manage evaluations.
@@ -855,16 +899,59 @@ runtype config path
 
 Valid config keys: `apiUrl`, `defaultModel`, `defaultTemperature`, `outputFormat`, `streamResponses`
 
-### Global Options
+### Effective target and headless safeguards
+
+```bash
+# Inspect the resolved endpoint and credential source without exposing the key
+runtype config context --json
+
+# Fail closed if the target or authenticated organization differs
+runtype --no-input --expect-api-url https://api.runtype.com --expect-org org_example \
+  flows run flow_example --inputs '{"limit":5}' --json
+
+# Headless mode is not consent: destructive commands also require --yes
+runtype --no-input records delete record_example --yes
+```
 
-All commands support these flags:
+API URL precedence is **`--api-url` > `RUNTYPE_API_URL` > saved `apiUrl` config >
+stored credential endpoint > production**. Saved URL configuration now affects
+ordinary API commands, not just configuration display. If an old saved value is
+stale, reset it or explicitly select your intended endpoint before upgrading
+automation. Conflicting explicit API URL flags are rejected.
+
+`config context` is an offline, redacted inspection; its stored organization hint
+is not proof of current server identity (`orgVerified: false`). `--expect-org`
+checks the authenticated identity against the server before API actions. With
+either expected-target guard, an invalid environment credential does not silently
+fall back to a different stored credential.
+
+Claim/verify tokens remain bound to their issuing server; the expected-URL guard
+also checks that actual endpoint. Anonymous registration and claim/verify reject
+`--expect-org`, since that ceremony cannot prove the resulting organization.
+
+Implicit login never prompts when stdin is not a terminal. `--no-input` also
+disables interactive startup and prompts in terminal sessions; delete, bulk-delete,
+revoke, and reset commands require explicit `--yes` in this mode. Marathon and
+`agents task` reject `--no-input`; use their documented headless JSON mode instead.
+
+### Global Options
 
-| Flag                 | Description              |
-| -------------------- | ------------------------ |
-| `--json`             | Output in JSON format    |
-| `--tty` / `--no-tty` | Force TTY / non-TTY mode |
-| `-v, --verbose`      | Enable verbose output    |
-| `--api-url <url>`    | Override API URL         |
+Root flags are forwarded to subcommands; output support depends on the command:
+
+| Flag                     | Description                             |
+| ------------------------ | --------------------------------------- |
+| `--json`                 | Output in JSON format                   |
+| `--tty` / `--no-tty`     | Force TTY / non-TTY mode                |
+| `-v, --verbose`          | Enable verbose output                   |
+| `--api-url <url>`        | Override API URL                        |
+| `--expect-api-url <url>` | Assert effective API endpoint           |
+| `--expect-org <id>`      | Assert authenticated organization       |
+| `--no-input`             | Disable prompts; does not imply consent |
+| `-y, --yes`              | Explicit destructive-action consent     |
+
+`--tty` / `--no-tty` are available on commands with terminal rendering. The strict
+single-result JSON contract above applies to the three execution commands and
+`batch status --watch`, not every legacy command.
 
 ## Development