@xano/cli 1.2.0 → 1.3.1-beta.0

package/README.md

@@ -46,16 +46,16 @@ The Metadata API pages unevenly, so `list` commands differ in what they expose.
 | Commands | Flags | Footer |
 |---|---|---|
 | `function list`, `unit_test list`, `workflow_test list` (plus `sandbox` / `tenant` variants) | `--page`, `--per_page` | `Page 2 · 50 shown · next: --page 3` |
-| `static_host list`, `static_host build list` | `--page` only | `Page 2 · 100 shown · 340 total` |
+| `static_host list`, `static_host build list` (plus `ephemeral` variants) | `--page` only | `Page 2 · 100 shown · 340 total` |
 | `branch list`, `workspace list`, `tenant snapshot list`, `sandbox env list`, `tenant env list` | none | `12 branches` |
-| `tenant list`, `release list`, `platform list`, `tenant cluster list` | none | none |
+| `tenant list`, `release list`, `platform list`, `tenant cluster list`, `ephemeral list` | none | none |
 | `tenant backup list` | `--page` only (pre-existing) | none |
 
 Notes:
 
 - **`--per_page` is only offered where the endpoint accepts it.** Static-host endpoints hardcode 100 items per page server-side, so those commands take `--page` alone. `xano static_host list --per_page 10` previously parsed but did nothing; it is now rejected rather than silently ignored.
 - **All paged commands default `--per_page` to 50.** The test-list commands previously requested 10000 internally so nothing was ever cut off; now that the footer and the JSON envelope both report position, a page that stops at 50 is visible rather than silent. Raise it (up to 10000) when you want everything in one call.
-- **The last group has no CLI paging.** Those endpoints page server-side but return a plain array with no page or total metadata, so the CLI cannot tell you where you are. Rather than show a page number with no context — or infer "more available" from a full page, which is wrong exactly when the result count is a multiple of the page size — these commands are left as-is. **They return at most 25–50 items** (50 for tenants, 25 for releases, platforms, and tenant backups). If you have more than that, query the Metadata API directly until those endpoints return paging metadata.
+- **The last group has no CLI paging.** Those endpoints page server-side but return a plain array with no page or total metadata, so the CLI cannot tell you where you are. Rather than show a page number with no context — or infer "more available" from a full page, which is wrong exactly when the result count is a multiple of the page size — these commands are left as-is. **They return at most 25–50 items** (50 for tenants and ephemerals, 25 for releases, platforms, and tenant backups). If you have more than that, query the Metadata API directly until those endpoints return paging metadata.
 - **`--output json` returns an envelope, not a bare array.** Every list command emits `{items, ...}` using the Metadata API's own field names — `curPage`, `nextPage`, `prevPage`, `itemsTotal` — each included only when the endpoint actually reports it. `perPage` is the one field the CLI adds, since the API never echoes it back and it is otherwise invisible at its default. This is a **breaking change** for scripts that parsed the previous bare array — read `.items` instead.
 
   ```jsonc
@@ -170,6 +170,104 @@ xano profile delete myprofile
 xano profile delete myprofile --force
 ```
 
+### Policies
+
+Policies combine a description with deterministic check rules; the platform parses, validates and evaluates
+them. `xano policy <command> --help` gives each command's flags and output, and the Xano developer MCP documents
+the rest: the `policies` topic of `xano_xanoscript_docs` (the language) and the `policy` topic of `xano_cli_docs`.
+
+```bash
+xano policy catalogue --check object.auth_required    # The checks a rule can use (all of them without --check)
+xano policy create --goal endpoints_need_login -b dev # Create an independent policy from a platform goal
+xano policy create --goal no_pii_in_responses --key DATA-020 --param 'fields=["email","ssn"]'
+xano policy list                                     # Policies on the branch
+xano policy parse policies/AUTH-001.xs               # Validate and print canonical XanoScript (or --file, --stdin)
+xano policy publish policies/AUTH-001.xs -m "Why"    # Create or update by key; -m labels the Version History entry
+xano policy evaluate                                 # Evaluate the branch now
+xano policy evaluate --summary                       # The same, answering the run summary and its first 50 findings
+xano policy status --fail-on-findings                # The latest run, without evaluating (CI)
+xano policy runs 1674 --run-detail                   # One run and its first 100 findings; without an id, the retained runs
+xano policy runs 1674 --offset 100 --limit 100       # The next page of that run's findings (at most 500 a page)
+xano policy runs 1674 --all -o json                  # Every finding, read page by page
+xano policy runs 1674 --blocking --policy AUTH-001   # Only some findings: --blocking/--advisory, --policy, --rule,
+                                                     #   --severity, --kind, --object type:id, --tag (repeatable), --search
+xano policy runs --release v1.2                      # A release's check (stored when it was cut), paged and filtered the same way
+xano policy runs --release v1.2 --recheck            # Check the release again from its archive, store the run, then read it
+xano policy runs --release-id 12                    # Read an imported release by ID without a name lookup
+xano policy delete TMP-001                           # Remove a policy; its Version History is kept
+```
+
+`policy create --goal <id>` reads the instance's goals from `policy catalogue -o json`, copies a goal's
+sparse settings, validates them natively and creates an Active, Advisory policy. Required goal settings must
+be filled before it saves. Repeat `--param 'N.path=JSON'` for overrides: rule numbers start at 1; the `N.`
+prefix is optional for a single-rule goal. Nested paths work, for example `--param '1.when.statement="db.edit"'`.
+Values are JSON, including quoted strings, arrays, booleans and numbers. The goal key gets a free numeric
+suffix if already taken (case-insensitive); an explicitly taken `--key` is refused. It never updates an
+existing policy. `-m/--message` labels its Version History entry; `-o json` returns the saved policy and
+native rule warnings go to stderr. No continuing link to the goal is stored.
+
+A push to the live branch is refused before commit when mandatory policies block it. The gate judges the branch by the policies it will have after the push, so the pushed policy files count, and a push that weakens a mandatory policy of the live branch (demotes, deactivates or deletes it, or loosens one of its rules) needs `workspace:policy` update and is otherwise refused before anything is imported. A 403 `policy_gate` exits **2**, says nothing was imported, and lists the blocking findings and introduced/changed counts. With `-o json` it prints `{imported: false, refused: <payload>}`. `--policy-override "reason"` sends an audited override, requiring `workspace:policy` update permission. This gate requires transactions: remove `--no-transaction` if the server refuses it (exit 1).
+
+Every policy command takes `-w/--workspace`, `-b/--branch` (the profile's branch by default; `-b ''` is live)
+and `-o/--output summary|json`. `workspace pull` and `workspace push` carry policies as `policies/<KEY>.xs`.
+Policies use `active = true|false` before `enforcement`; authored `lifecycle` is refused. The list shows
+`Active, Mandatory`, `Active, Advisory` or `Inactive`. Inactive policies are saved directly and skipped by
+branch checks; `policy status` reports `inactive`. An inactive policy may have no rules.
+`release push` carries them too, for a credential holding `workspace:policy` create and update: a release ships its
+policies like its code, and a tenant deploy lands them (see Releases). Tier1 tenant, sandbox and ephemeral pushes
+carry them as well; a remote tenant push, or a tenant created before policies, leaves them out and prints the
+platform's notice.
+While the instance's Policies feature is off, `workspace pull` exports no policy (and keeps local policy files)
+and `workspace push` leaves its policy files out, printing the platform's notice instead of a policy count.
+
+A run can hold tens of thousands of findings, so the CLI reads them a page at a time. `policy runs <id>` reads
+the run's summary and one page of its findings; a page that is not every finding says `(one page)` and how to read
+the next. `-o json` is the summary with `findings`, the page's findings as an array, and
+`findings_page: {total, offset, limit, next_offset}`. `--all` reads every page (500 a request, saying so on stderr
+when there are more) and returns every matching finding in `findings`. `policy status` reads the latest run's
+summary, so its `-o json` `run` carries each policy's finding count rather than the findings. The `policy_check` a
+`workspace push` prints lists the first 100 findings; when there are more it prints their counts and
+`Listed: the first 100 of N; \`xano policy runs <run_id>\` has them all.` `policy evaluate --summary` does the same
+with the first 50, and `policy evaluate` without it still answers the whole run.
+
+`policy evaluate --policy AUTH-001` tries that one policy alone, even if inactive. It never stores or audits
+the trial, replaces the latest run or gates anything. The output names each rule's clear objects (up to five
+names, with the rest counted). Combine it with `--summary`, `--run-detail` or `-o json`; an inactive trial
+does not exit 2. A blank key is refused before any request, and an unknown key gets the platform's 404.
+
+`policy runs --release <name>` reads a release's check: the run stored when the release was cut, evaluated on what
+the release ships against the policies it ships. It takes every finding flag a run read takes, `-o json` has the same
+shape (plus the release's `shipped` policies), and a release with no check says so (`{"run": null}` under `-o json`).
+`--recheck` checks the release again from its archive and stores the new run, so a read-only credential is refused.
+`--release-id <id>` reads the same report directly by ID and also supports `--recheck`; it is exclusive with
+`--release` and `--branch`.
+
+**Exit codes** of `policy evaluate`, `workspace push` and `policy status --fail-on-findings`: `2` when a finding
+blocks (an active, mandatory policy failed), whatever else happened; `1` when a request or the import failed, or
+when `status --fail-on-findings` finds stale, missing or errored evidence; otherwise `0`. `tenant deploy_release`,
+`tenant_deploy_request set_status` and `tenant_deploy_request bypass` exit `2` when the tenant deploy policy gate
+refuses the deploy (and `tenant deploy_release --check` when it would), `1` for any other failure, otherwise `0`.
+`release deploy --set_live` and `branch set_live` exit `2` when the set-live policy gate refuses to set the branch live, and `1` for any other failure; `branch set_live --policy-override "<reason>"` sets it live past the gate with an audited reason, as `release deploy` does. `function create` and `function edit` exit `2` when the live-branch publish gate refuses the save (see Functions), and `1` for any other failure. A blank `--policy-override` is refused before any request. A `workspace push`, `branch set_live`, `release deploy --set_live` or `policy delete` refused with `policy_weakening_permission_required` exits `1`, like the other permission refusals: it is a missing permission, not a blocking finding.
+
+Each route needs the `workspace:policy` permission at the request's level. A refusal's `payload.code` names the
+gate and the CLI prints its remedy: `policy_feature_disabled` (Policies are off on the instance),
+`policy_permission_required` (an instance admin grants your role the level) or `policy_scope_required` (create a
+Metadata API token that has the scope). A push to the live branch, a set live or a merge is judged by the policies it
+leaves, so one that weakens a policy active and mandatory on the branch (demotes, deactivates or deletes it, or
+loosens one of its rules; for a set live, a live mandatory policy the branch lacks counts as deleted) needs
+`workspace:policy` update, and without it is refused before anything is written with
+`policy_weakening_permission_required`, naming the policies. `--policy-override` does not lift it: the CLI prints the
+platform's sentence and how to go on (a push can leave the policy files out with `-e "policies/*"`), and a push's
+`--dry-run` is refused the same way. `policy delete` of an active, mandatory policy needs update too, not only delete,
+and is refused with the same code otherwise. A set live whose check could not read the policies fails closed: only
+update proceeds, and the refusal says so (`unavailable`). A rule naming a check the instance does not have (`policy_unknown_check`)
+points at `xano policy catalogue`. `policy delete` sends the `updated_at` it listed, so a policy changed since is
+refused (`policy_stale`) rather than deleted; it asks first, and without `--force` in a non-interactive shell it
+exits 1. A create past the plan's per-branch policy cap (lower plans cap the policies on each branch; Pro and above are unlimited) is refused with
+`policy_plan_limit`, naming the plan, and a `workspace push` whose new policies would not fit imports nothing.
+`policy parse` and `policy publish` print rule warnings (a part of a rule that would do nothing or allow too much on
+that branch) on stderr; `-o json` keeps stdout the JSON.
+
 ### Workspaces
 
 ```bash
@@ -197,6 +295,7 @@ xano workspace delete -w <workspace_id> --force
 xano workspace pull
 xano workspace pull -d ./my-workspace                    # Specify output directory
 xano workspace pull -b dev                               # Specific branch
+xano workspace pull -b ''                                # The live branch, whatever the profile's branch
 xano workspace pull --env --records                      # Include env vars and table records
 xano workspace pull --draft                              # Include draft changes
 
@@ -204,6 +303,7 @@ xano workspace pull --draft                              # Include draft changes
 xano workspace push
 xano workspace push -d ./my-workspace                    # Push from a specific directory
 xano workspace push -b dev
+xano workspace push -b ''                                # The live branch, whatever the profile's branch
 xano workspace push --sync                               # Full push — send all files, not just changed ones
 xano workspace push --sync --delete                      # Full push + delete remote objects not included
 xano workspace push --dry-run                            # Preview changes without pushing
@@ -216,6 +316,9 @@ xano workspace push --force                              # Skip preview and conf
 xano workspace push -i "function/*"                      # Push only matching files
 xano workspace push -e "table/*"                         # Push all files except tables
 xano workspace push -i "function/*" -e "**/test*"        # Include functions, exclude tests
+xano workspace push -o json                              # One JSON document: the preview (with --dry-run) or the import result with policy_check
+xano workspace push -m "Tightened the auth policies"     # Label the Version History entry of each policy this push changes; other objects get no message
+xano workspace push --policy-override "Approved exception" # Proceed past a blocking live-branch gate with an audited reason
 
 # Pull from a git repository to local files (defaults to current directory)
 xano workspace git pull -r https://github.com/owner/repo
@@ -229,6 +332,51 @@ xano workspace git pull -r https://github.com/owner/private-repo -t ghp_xxx
 xano workspace git pull -r https://github.com/owner/repo --path subdir
 ```
 
+**One workspace document per tree.** A push directory must contain at most one
+`workspace/*.xs` document. The server applies the first workspace document it
+receives to the workspace being pushed into and silently discards the rest,
+without checking that it describes that workspace — so a second one renames the
+destination to a foreign name while leaving its content untouched. `workspace push`
+and `sandbox push` refuse a tree carrying more than one, naming the offending
+files; there is no `--force` override, because only you know which workspace the
+tree is meant to be.
+
+Trees pick up a second one easily: `pull` names the file after the workspace
+itself (`workspace/{name}.xs`), so pulling a different workspace into the same
+directory *adds* a file rather than overwriting, and renaming a workspace leaves
+the old-name file behind. Delete the stale ones, keeping the single document that
+matches your target workspace.
+
+### Flatten
+
+A hand-authored `.xs` file can hold several documents joined by `---`. That is
+convenient to edit but unsupported by `push`: the partial-diff filter and GUID
+writeback both parse only the first document in a file, so such a bundle
+silently pushes nothing (partial mode) or corrupts GUIDs (full mode). `push`
+refuses these files and offers to flatten them.
+
+`xano flatten` performs that split on demand, producing the same
+one-document-per-file tree `pull` would have written. It is purely local — no
+profile, token, or network — and deletes the original bundle once the split
+succeeds, unless you pass `--keep-source`.
+
+```bash
+# Split a bundle in place into per-document files (removes the original)
+xano flatten secret/pdf-micro/multidoc.xs
+
+# Write the split files somewhere else instead of alongside the bundle
+xano flatten ./bundle.xs -o ./workspace
+
+# Preview the resulting layout without writing anything
+xano flatten secret/pdf-micro/multidoc.xs --dry-run
+
+# Flatten every multi-doc .xs under a directory, keeping the originals
+xano flatten ./dir-of-bundles --keep-source
+
+# Overwrite existing destination files instead of erroring
+xano flatten ./bundle.xs --force
+```
+
 ### Knowledge
 
 Knowledge items are user-authored docs and skills (e.g. `CLAUDE.md`, `AGENTS.md`, runbooks)
@@ -285,6 +433,7 @@ xano branch edit <branch_label> --color "#ff0000"
 # Set live branch
 xano branch set_live <branch_label>
 xano branch set_live <branch_label> --force
+xano branch set_live <branch_label> --policy-override "Rollback approved"  # Past a blocking set-live policy gate (audited)
 
 # Delete a branch
 xano branch delete <branch_label>
@@ -309,6 +458,7 @@ xano function get <function_id> --include_draft         # Include draft version
 xano function create -f function.xs
 xano function create -f function.xs --edit              # Open in $EDITOR before creating
 cat function.xs | xano function create --stdin
+xano function create -f function.xs --policy-override "Exception approved"  # Past a blocking publish policy gate (audited)
 
 # Edit a function
 xano function edit <function_id>                        # Opens in $EDITOR
@@ -316,6 +466,7 @@ xano function edit <function_id> -f new.xs              # Update from file
 xano function edit <function_id> -f new.xs --edit       # Open in $EDITOR before updating
 cat function.xs | xano function edit <function_id> --stdin  # Update from stdin
 xano function edit <function_id> --no-publish           # Edit without publishing
+xano function edit <function_id> -f new.xs --policy-override "Exception approved"  # Past a blocking publish policy gate (audited)
 
 # Run (execute) a function by name
 xano function run <name>                                # Prompts for declared inputs (on a TTY)
@@ -323,8 +474,14 @@ xano function run <name> --data email=jo@x.com --data age:=30 --data active:=tru
 xano function run <name> --json @payload.json --data env=staging   # base payload + override
 echo '{"email":"jo@x.com"}' | xano function run <name> --stdin -o json | jq .result
 xano function run <name> --branch dev --logs            # run on a branch, show execution logs
+xano function run <name> --datasource test              # run against the 'test' data source
 ```
 
+`function create` and `function edit` save a function on the live branch through the publish policy gate. When
+blocking findings refuse the save, nothing is saved: the command prints the verdict and the platform's message and
+exits `2` (any other failure exits `1`), and `-o json` prints `{created|updated: false, message, policy_gate}`.
+`--policy-override "<reason>"` saves past the gate with an audited reason (requires `workspace:policy` update).
+
 Input flexibility for `function run` (assembled into one JSON `input` object):
 
 | Form | Meaning |
@@ -335,6 +492,11 @@ Input flexibility for `function run` (assembled into one JSON `input` object):
 | `--json '<inline>'` / `--json @file.json` / `--json -` | a base JSON object (stdin with `-`) |
 | `--stdin` | read the JSON object from stdin (same as `--json -`) |
 
+`--datasource <label>` runs the function against a non-live data source by sending the
+`X-Data-Source` header, so table reads and writes hit that data source's tables. Omit it
+to run against `live`; an unknown label is rejected by the server with
+`Invalid data source.`
+
 Merge order is JSON base first, then `--data` overrides. Missing required inputs are
 prompted for on an interactive terminal; in a non-TTY (CI) context the command fails
 listing them. Output defaults to the raw `result` (`-o json`); the exit code is non-zero
@@ -370,12 +532,27 @@ xano knowledge get "deploy-runbook" -w 40 --output json
 xano knowledge get "deploy-runbook" -w 40 --file checklist.md
 ```
 
+### Agent skills
+
+```bash
+xano skills pull                                         # Writes ./.claude/skills/xano-policies/SKILL.md
+xano skills pull -d ./my-project                         # Install into another project directory
+xano skills pull -b dev -o json                          # Another branch; print the result as JSON
+```
+
+`xano skills pull` writes the `xano-policies` skill the instance generates from its check catalogue to
+`<directory>/.claude/skills/xano-policies/SKILL.md`, replacing that file without a backup; pull it again after an
+instance upgrade. A copy installed anywhere else is not touched, so remove it. The route needs the
+`workspace:policy` read permission. The CLI writes the file's frontmatter (`name` and `description`) itself and drops
+any frontmatter the served content opens with, so a workspace knowledge record that replaces the platform skill cannot
+set agent settings such as `allowed-tools` or `hooks`. It refuses to write through a symbolic link at that path.
+
 ### Releases
 
 All release commands use **release names** (e.g., `v1.0`), not IDs.
 
 ```bash
-# List releases
+# List releases, each tagged with its stored policy check when Policies is enabled and readable (see Policies)
 xano release list
 
 # Get release details
@@ -416,8 +593,54 @@ xano release deploy "v1.0"
 xano release deploy "v1.0" --force
 xano release deploy "v1.0" --branch "restore-v1" --no-set_live
 xano release deploy "v1.0" -w 40 -o json --force
+
+# Set it live past a blocking set-live policy gate with an audited reason (needs workspace:policy update)
+xano release deploy "v1.0" --branch "rollback-v1" --set_live --policy-override "Rollback approved; tracked in JIRA-12"
+
+# Read a release's policy check, or check it again (see Policies)
+xano policy runs --release v1.0
+xano policy runs --release v1.0 --recheck
 ```
 
+A release carries its branch's policies like its code (`release push` sends `policies/*.xs` with the rest), and a
+tenant deploy lands them on the tenant. A release built by `release push` carries those files only for a credential
+holding `workspace:policy` create and update; for anyone else it carries the workspace's live-branch policies instead,
+and when the files differ from them the push prints the platform's notice naming them (exit `0`). `release import` of
+an archive that carries policies needs the same levels: without them nothing is stored, and the command fails with
+the platform's message and the remedy for your role or token.
+
+Cutting a release (`release create`, `release push`, `release import`) stores its policy check, and the summary
+prints it: `Policy check: fail (run 1712), 2 blocking, 1 advisory findings`, or
+`Policy check disabled|skipped|error: <why>` when none was recorded. `-o json` keeps it as `policy_run`
+(`{status, run_id, run_status, blocking, advisory, message?}`, or `null` for a credential without `workspace:policy`
+read). A cut is never refused for its findings: its blocking findings are what gates each tenant deploy (see Tenant
+deployments).
+
+`release list` tags each release with its stored check, worded as Studio's Policies column: `[policies: 2 blocking,
+1 advisory]`, `[policies: 11 advisory]`, `[policies: passed]`, `[policies: none shipped]` (the release carries no
+policies), `[policies: could not check]` (a rule could not run) or `[policies: not checked]` (no stored check:
+deploying the release checks it, and so does `policy runs --release <name> --recheck`), and ends with
+`Policy check details: xano policy runs --release <name>`. The tag is the release's own check, its code against the
+policies it ships, and it is also what the tenant deploy gate judges: a release with blocking findings is held on
+every standard or run tenant (`tenant deploy_release --check`). The list reads `release/policy_check` once, stores nothing, and
+prints as it did before when that read is refused (Policies off, no `workspace:policy` read) or fails. `-o json`
+adds `policy_check` to each item (`{run_id, status, finished_at, counts {findings, blocking, advisory, errors},
+policies}`, or `null` for a release with no stored check) and leaves it out when the checks could not be read.
+Tier1 tenant, ephemeral and sandbox pushes carry policy files too when Policies is enabled and the tenant has
+a policy table. Remote tenant pushes still leave them out; remote release deploys carry them.
+
+`release deploy --set_live` lands the release as a new branch, then sets it live through the same policy gate as
+`branch set_live`: the branch is checked against its own policies, which live will have once it is set live, and
+blocking findings it introduces compared with the live branch, or leaves on objects it changes, refuse it. A branch
+that weakens a mandatory policy of the live branch needs `workspace:policy` update (a release that lands no policy is
+judged by the live branch's policies instead, and nothing is checked for weakening): without it set live is refused
+with `policy_weakening_permission_required`, the branch stays, and the command exits `1`, naming the branch to set
+live or delete. A gate refusal keeps the branch, prints the verdict, says `The branch was
+created; set live was refused` and exits `2`; `-o json` prints `{"branch_created": true, "set_live": false, "branch",
+"message", "policy_gate"}`. Set it live from Studio's Branches panel with a reason, or delete the branch and deploy
+again with `--policy-override "<reason>"`, which sets it live past the gate and is audited. A policy of the release
+that the new branch could not take (its key is held by another policy) is named in a warning.
+
 ### Platforms
 
 ```bash
@@ -555,9 +778,14 @@ xano tenant get <tenant_name>
 xano tenant create "My Tenant"
 xano tenant create "My Tenant" -d "Description" --type tier2 --cluster_id 1 --platform_id 5
 xano tenant create "My Tenant" --type tier2 --cluster_id 1 --license ./license.yaml
+xano tenant create "Production" --required_reviewers 1 --allow_deploy_bypass
+xano tenant create "Staging" --required_reviewers 0 --allow_quick_deploy
 
 # Edit a tenant
 xano tenant edit <tenant_name> --display "New Name" -d "New description"
+xano tenant edit <tenant_name> --required_reviewers 1
+xano tenant edit <tenant_name> --required_reviewers 0
+xano tenant edit <tenant_name> --allow_quick_deploy
 
 # Delete a tenant (confirmation required)
 xano tenant delete <tenant_name>
@@ -604,10 +832,101 @@ xano tenant deploy_platform <tenant_name> --platform_id 5
 # Deploy a release by name
 xano tenant deploy_release <tenant_name> --release v1.0
 
+# Preview the release's policy gate on the tenant without deploying (exit 2 when it would refuse)
+xano tenant deploy_release <tenant_name> --release v1.0 --check
+xano tenant deploy_release <tenant_name> --release v1.0 --check -o json
+
+# Deploy past a blocking policy gate with an audited reason (needs workspace:policy update)
+xano tenant deploy_release <tenant_name> --release v1.0 --override-reason "Accepted; fix tracked in JIRA-12"
+
 # Deploy with a license override file (deploy_platform only)
 xano tenant deploy_platform <tenant_name> --platform_id 5 --license ./license.yaml
 ```
 
+If a tenant has `required_reviewers` set above 0, `tenant deploy_release` fails with an
+error naming the `tenant_deploy_request` command to run instead — see below. A tenant
+with `allow_quick_deploy` enabled skips the gate entirely, regardless of
+`required_reviewers`.
+
+A release deploy is also gated on policy. The gate judges the release alone, by its own policy check (the one
+stored when it was cut, or checked from its archive on demand): the blocking findings of its active mandatory policies
+refuse the deploy, including findings the tenant's current release already has. It does not compare the release with
+what the tenant runs, so the same release gets the same verdict on every tenant. Ephemeral and sandbox tenants get the
+verdict but are never refused. A release cut before releases carried policies reads `not_carried` and is not gated.
+`--check` prints the verdict (status, the release and its policy run, the number of blocking findings, and the first
+of them) without deploying; `-o json` is the gate's answer as served. A refused deploy prints the same verdict and exits `2`, naming the
+`--override-reason` rerun when your credential may override; under `-o json` it prints
+`{"deployed": false, "message", "policy_gate"}`. `--override-reason` sends `override_policy: true` with the reason,
+and the platform audits it. A successful deploy's summary prints the gate's status when the platform returns one,
+and a warning names any policy of the release the tenant could not take (its key is held by another policy).
+
+#### Tenant Deploy Requests
+
+When a tenant has `required_reviewers` set above 0 and `allow_quick_deploy` is off (see
+`tenant create`/`tenant edit` above), a release may only be deployed to it through an
+**approved deploy request**, requiring that many distinct reviewer approvals. An author
+with no deploy permission opens a request; a named reviewer who does hold deploy
+permission on the tenant votes to approve it, and once enough reviewers have approved,
+it deploys as part of that action. `allow_deploy_bypass` (set at `tenant create` time
+only) additionally allows an authorized user to skip a specific request's gate via
+`tenant_deploy_request bypass`, audited with a required reason.
+
+```bash
+# List deploy requests in a workspace (results show the target tenant and release)
+xano tenant_deploy_request list
+xano tenant_deploy_request list --tenant prod --status pending
+xano tenant_deploy_request list --tenant prod --release v1.2
+xano tenant_deploy_request list --to-review
+
+# Get details of a specific deploy request, with its release's policy check on its tenant
+xano tenant_deploy_request get <id>
+
+# Open a deploy request (submits for review immediately unless --draft is passed)
+xano tenant_deploy_request create "Deploy v1.2 to prod" --tenant prod --release v1.2 --reviewers 12,45
+xano tenant_deploy_request create "Deploy v1.2 to prod" --tenant prod --release v1.2 --draft
+
+# Edit a deploy request's title, description or reviewers
+xano tenant_deploy_request edit <id> --title "Deploy v1.2.1 to prod"
+xano tenant_deploy_request edit <id> --reviewers 12,45,67
+
+# Change status: draft, submit, approve, request_changes, close, or reopen
+# (approve records one reviewer's vote; once enough votes are in it deploys the
+# release as part of that same call)
+xano tenant_deploy_request set_status <id> --status submit
+xano tenant_deploy_request set_status <id> --status approve
+xano tenant_deploy_request set_status <id> --status approve --override-policy --reason "Accepted; fix tracked in JIRA-12"
+xano tenant_deploy_request set_status <id> --status request_changes --reason "Needs a migration note"
+xano tenant_deploy_request set_status <id> --status close --reason "Superseded by a newer request"
+xano tenant_deploy_request set_status <id> --status reopen
+
+# Link a newer release to a request after changes were requested (author only)
+xano tenant_deploy_request revision <id> --release v1.2.1 --note "Added the missing migration"
+
+# Deploy past the approval gate under the deploy-bypass permission (requires the
+# tenant's allow_deploy_bypass to be enabled, and a separately-grantable RBAC
+# permission). Every use is audited.
+xano tenant_deploy_request bypass <id> --reason "Prod incident, reviewer unavailable"
+xano tenant_deploy_request bypass <id> --reason "Prod incident, reviewer unavailable" --override-policy
+```
+
+`tenant_deploy_request get` always names the tenant and release. For requests that are neither approved nor closed,
+it also prints what the policy gate would decide now for the request's release on its
+tenant (under `-o json`, as `policy_gate`). It needs `workspace:policy` read; without it, or with the Policies
+feature off, it prints `Policy checks: not available (<why>)` (`policy_gate: null` and `policy_gate_unavailable`
+under `-o json`) and the command still succeeds. The deploy an approval triggers, and a bypass deploy, are gated like
+`tenant deploy_release`: a refusal prints the verdict and exits `2`. An approval refused this way is still recorded
+and the request stays approved; deploy it with `tenant deploy_release --override-reason`. `--override-policy`
+(with `--reason` as the override reason, and the `workspace:policy` update permission) proceeds past the gate on
+`set_status --status approve` and on `bypass`. Approval bypass and policy override are separate permissions:
+neither implies the other.
+
+CI example (e.g. a GitHub Action step):
+
+```bash
+xano tenant_deploy_request create "$PR_TITLE" --tenant prod --release v1.2 \
+  --description "$PR_BODY" --reviewers 12,45 -o json
+```
+
 #### Tenant License
 
 ```bash
@@ -694,6 +1013,64 @@ xano tenant cluster license set <cluster_id>
 xano tenant cluster license set <cluster_id> --file ./kubeconfig.yaml
 ```
 
+### Ephemeral Tenants
+
+Manage ephemeral tenants — short-lived, auto-expiring tenants scoped to a workspace (default TTL 1h, max 24h). Unlike a sandbox, an ephemeral tenant requires a workspace.
+
+```bash
+# List ephemeral tenants in the current workspace
+xano ephemeral list
+xano ephemeral list -w 5
+
+# List ephemeral tenants across every workspace you can access
+xano ephemeral list --global
+
+# Create an ephemeral tenant (workspace required)
+xano ephemeral create "PR preview"
+xano ephemeral create "Demo" --expires-hours 24 -w 5
+xano ephemeral create "Load test" -d "overnight soak" --expires-hours 24
+
+# Get / edit / delete
+xano ephemeral get <tenant_name>
+xano ephemeral edit <tenant_name> --display "New Name" -d "New description"
+xano ephemeral delete <tenant_name> --force
+
+# Pull to / push from local files (multidoc)
+xano ephemeral pull <tenant_name> -d ./my-ephemeral
+xano ephemeral push <tenant_name> -d ./my-ephemeral --dry-run   # preview first
+xano ephemeral push <tenant_name> -d ./my-ephemeral
+
+# Open in the browser (or print the URL)
+xano ephemeral impersonate <tenant_name>
+xano ephemeral impersonate <tenant_name> --url-only
+xano ephemeral impersonate <tenant_name> --guest       # read-only session (browse only)
+```
+
+#### Static hosting for an ephemeral tenant
+
+An ephemeral tenant can host static sites, scoped to that tenant. These commands mirror
+`xano static_host *` but take the tenant name as the first argument (the tenant's static
+hosting is isolated inside the tenant's own database).
+
+```bash
+# List / create / inspect a tenant's static hosts
+xano ephemeral static_host list <tenant_name>
+xano ephemeral static_host create <tenant_name> --name marketing --description "Marketing site"
+xano ephemeral static_host get <tenant_name> -H marketing
+xano ephemeral static_host edit <tenant_name> -H marketing --description "Updated"
+
+# Builds: push a directory, list, inspect, deploy to an env, pull, delete
+xano ephemeral static_host build push <tenant_name> -H default -f ./site
+xano ephemeral static_host build list <tenant_name> -H default
+xano ephemeral static_host build get <tenant_name> -H default --build_id 52
+xano ephemeral static_host deploy <tenant_name> -H default --build_id 52 --env prod
+xano ephemeral static_host build pull <tenant_name> -H default --latest
+xano ephemeral static_host build delete <tenant_name> -H default --build_id 52
+```
+
+> Static hosting is currently available for **local** tenants. Remote (tier2/tier3)
+> tenants are not yet supported and will return an error.
+
 ### Sandbox
 
 Manage your sandbox tenant. Each user has a single sandbox tenant that is auto-provisioned on first use.