@oxy-hq/cli 0.8.0 → 0.10.0

package/README.md

@@ -7,7 +7,7 @@ manages customer workspace repos.
 - **Customer workspaces** — `list`, `new`, `import`, `doctor`, `update`, `adopt`, `launch`
 - **Custom apps** — `publish`, `init-ci`, `proxy`, `apps`
 - **Checks** — `checks run`
-- **Sandboxes** — `env`, `fn call`, `invocations`, `logs`
+- **Sandboxes** — `env`, `fn dev`, `fn call`, `invocations`, `logs`
 - **Workspace previews** — `preview`
 - **Development** — `validate`, `mcp`, `guide`, `skills`
 
@@ -149,7 +149,7 @@ route's surface and fleet role.
 ## Authentication
 
 ```bash
-oxyc login [--env <e>] [--login-env <e...>] [--assume <org> -r <why>]
+oxyc login [--env <e>] [--login-env <e...>] [--assume <org> -r <why>] [--no-browser [--approver <email>]]
 oxyc whoami [--json]        # who the credential is, and what it can reach
 oxyc token                  # print the bearer, for a raw curl
 oxyc login-link [--next <path>] [--json] [--open]   # a one-time URL that signs a browser in
@@ -158,9 +158,24 @@ oxyc tokens list [--json]   # your personal access tokens
 oxyc tokens revoke <id>
 oxyc tokens revoke --current   # end the token in OXY_TOKEN
 oxyc tokens create          # opens Account → Personal access tokens
-oxyc tokens create --sandbox-agent --app <org>/<app> [--app …] [--hours 8] [--name …]
+oxyc tokens create --sandbox-agent --app <org>/<app> [--app …] [--hours 8] [--name …] [--no-browser [--approver <email>]]
+oxyc tokens create --agent [--standing] [--hours 8] [--name …] [--no-browser [--approver <email>]]
 ```
 
+**An agent runs on its own token, never on the person's `oxyc login`.** Which
+one depends on the task:
+
+| The agent is… | It mints | Which reaches |
+| --- | --- | --- |
+| building a custom app in a sandbox | `tokens create --sandbox-agent --app …` (`oxy_sbx_…`) | the sandboxes of the apps it names, and nothing else |
+| doing anything else: reading data with `oxyc api`, reproducing a bug against live data | `tokens create --agent` (`oxy_pat_…`) | everything its approver can, for hours |
+
+Both are approved once in the browser by the person the agent works for, both
+are printed once as `export OXY_TOKEN=…` and never stored, and both end with
+`tokens revoke --current`. After a mint, pass `--token-env OXY_TOKEN` to every
+command: a named variable is the only source, so a command that lost the
+variable exits `4` instead of quietly running on the person's cached login.
+
 **Every command resolves its credential the same way, first match wins:**
 
 1. **`OXY_TOKEN`** (or the variable `--token-env` names). It holds any
@@ -168,7 +183,8 @@ oxyc tokens create --sandbox-agent --app <org>/<app> [--app …] [--hours 8] [--
    token (`oxy_pat_…`), a service account token (`oxy_sat_…`), a CI token
    (`oxy_ci_…`) or a sandbox agent token (`oxy_sbx_…`) — a legacy API key
    (`oxy_…`), a publish token, or a session token. A blank value counts as
-   unset.
+   unset. An agent token is a personal access token by its prefix: only its
+   own description tells it from a login (`oxyc whoami`).
 2. **The login cache** — what `oxyc login` stored for this deployment.
 3. **GitHub OIDC**, in a GitHub Actions job granted `id-token: write`: the job's
    OIDC token is exchanged, once per process, for a fifteen-minute token acting
@@ -196,7 +212,7 @@ Settings → Workspace → Legacy API keys. Use an API token for anything new.
 
 **`login`** runs a browser loopback flow. Against a current deployment it
 receives a one-time code and exchanges it (PKCE) for a **personal access
-token** named `oxyc on <hostname>`: revocable, ninety days, and replacing that
+token** named `oxyc on <hostname>`: revocable, a year, and replacing that
 machine's previous one. No credential travels in a URL. Against a deployment
 that predates the exchange it stores the session token the page hands back,
 exactly as before, and says so — nothing needs upgrading first, in either
@@ -212,7 +228,10 @@ rather than reading as fine from the cache. For a token it also prints what the
 token is and what it can reach — `all access`, or one line per grant with the
 role it is capped at, and any organization whose policy blocks it. For a legacy
 API key it prints `Legacy API key`, and that it reaches everything its owner
-can.
+can. For an agent token it says `agent token`, who approved it, whether it
+carries their staff or partner access, and when it expires. When a token in
+`OXY_TOKEN` is refused (exit `4`), the advice is never to log in — a login
+cannot replace what is in the variable. An agent stops and reports.
 
 **`token`** prints the bearer on stdout and nothing else. Inside a GitHub
 Actions job with nothing stored it prints the token the job's OIDC identity
@@ -245,6 +264,37 @@ writes the credentials file, and revokes no other token. `--app` is
 `<org>/<app>` and repeats; arguments are checked before the browser opens
 (exit `2`). Only staff who can open the app's sandboxes can approve.
 
+**`--no-browser`** is the same approval for a machine no browser can reach
+(a cloud container, a CI runner, a remote dev box), where the loopback's
+`127.0.0.1` port is not the approver's. Instead of opening a page, `oxyc`
+asks for a device code (`POST /api/auth/cli/device`) and prints, on stderr,
+a URL (`<deployment>/cli-auth/device?code=…`) and an eight-letter code. The
+operator opens the URL on any device where they are signed in, types the
+code from the terminal (the page never shows it), and approves; `oxyc` polls
+(`POST /api/auth/cli/device/poll`, with the PKCE verifier) and prints the
+token exactly as above. A request lives ten minutes. A decline, or a refusal
+on the page, stops the command with exit `4` (`access_denied`) and the
+reason; nobody deciding in time is exit `7`. It works the same for
+`tokens create --agent` and for `oxyc login`, with one difference: a token
+approved by device code **never carries staff or partner access**, since
+whoever started the request collects it and the approver cannot see who that
+is. `--standing --no-browser` is a usage error (exit `2`), and a login made
+this way reaches only what its approver's organization memberships do.
+
+**`--approver <email>`** (env `OXY_APPROVER`, valid only with `--no-browser`;
+anything else is a usage error, exit `2`) names who must approve, so nobody
+has to hand them a URL: the platform tells that person itself, by push,
+email and Slack DM where their organization connected it, and in their
+Oxygen inbox. They type the code from your output on the approval page. The
+notice never holds the code and links to `/cli-auth/device` without it, and
+the request is then theirs alone: anyone else who finds the page is told
+there is no such request. `oxyc` prints `Approval request sent to <email>`
+beside the code and the URL; it prints that whether or not the deployment
+knew the address, since the deployment never says. An address nobody holds
+leaves a request nobody can approve: it lapses after ten minutes, so a typo
+means running the command again with the right one. An agent still never
+opens or approves the page.
+
 What comes back is checked before anything is printed: it must be an
 `oxy_sbx_`, described as `sandbox_agent` and not all-access, for exactly the
 apps named, expiring no later than the hours asked for. Anything the check
@@ -257,14 +307,17 @@ what was minted, and exits `8`.
 With that token in `OXY_TOKEN`, `oxyc` behaves differently in five ways:
 
 - **An app resolves against the token's own list** (`GET /api/auth/token`),
-  never `/api/admin/apps`. An app it was not minted for is exit `5`.
+  never the app listing (`GET /api/customer-apps`), which it may not call. An
+  app it was not minted for is exit `5`.
 - **Read-back uses `/api/customer-apps/{id}/…`** — `invocations list`,
-  `invocations held` and `checks run` — since the token never reaches `/admin`.
+  `invocations held` and `checks run` — the same routes every other credential
+  uses; the token never reaches `/admin`.
 - **Refused before any request, exit `2`:** an `--app-env` that is not
   `dev-<handle>`; `publish` without `--app-env`, or with `--promote`;
-  `fn call`, `logs`, `invocations list` and `checks run` without `--app-env`;
-  `env show` of production or staging; `oxyc apps`, `tokens list` and
-  `tokens revoke <id>`; and `oxyc api` against any path.
+  `fn call`, `fn run`, `logs`, `invocations list` and `checks run` without
+  `--app-env`; `env show` of production or staging; `env schedules`;
+  `oxyc apps`, `tokens list` and `tokens revoke <id>`; and `oxyc api` against
+  any path.
 - **`whoami`** prints the token's description — `kind`, `expires_at`, the
   `apps` it reaches and its `minter` — and `--json` is that document as the
   server sent it.
@@ -276,6 +329,35 @@ A refusal from the server carries a hint an agent can act on — never "try
 `oxyc login` again". Exit `4` under this token means it expired, was revoked,
 or its minter lost access: stop and report.
 
+**`tokens create --agent`** mints an **agent token** for everything that is not
+a sandbox: a personal access token (`oxy_pat_…`) that reaches what its approver
+reaches through their organization memberships, for 8 hours by default
+(`--hours`, 1 to 168). It cannot be extended, edited or regenerated, and it
+cannot create, extend or revoke tokens; it can open a browser session as itself
+(`login-link`).
+
+```bash
+eval "$(oxyc tokens create --agent --env dev)"
+```
+
+The same browser loopback again, with the same guarantees: stdout is the single
+line `export OXY_TOKEN=oxy_pat_…`, printed once, everything else is on stderr,
+it holds no credential while it runs, never writes the credentials file and
+revokes no other token. Arguments are checked before the browser opens (exit
+`2`); `--agent` and `--sandbox-agent` together are a usage error.
+
+`--standing` asks for the approver's staff or partner access as well. The
+approver decides on the page, where it starts **off**: a token that comes back
+without it is accepted, and stderr says so in one line. Without `--standing`, a
+token that carries either is refused.
+
+What comes back is checked before anything is printed: it must be a whole
+`oxy_pat_`; it must describe itself (`GET /api/auth/token`) as `personal` with
+`source` `oxyc_agent`; it must expire no later than the hours asked for; and it
+must carry no standing that was not asked for. A deployment that predates agent
+tokens would otherwise hand back an ordinary ninety-day login. On any mismatch
+the command prints nothing, revokes what was minted, and exits `8`.
+
 Credentials live in the OS config directory under **`oxy`** — the same file the
 Rust `oxy login` wrote before it was removed, so an existing login still works:
 
@@ -493,6 +575,8 @@ the current directory while granting access to the customer's repo.
 
 ```bash
 oxyc publish [--env <e>] [--dir <path>] [--promote] [--build-only | --prebuilt] [--json] [--allow-function-lint] [--app-env <dev-handle>]
+oxyc promote <app> [--from staging|dev-<handle>] [--build <id>] [--remove-schedule <fn>]… [--dry-run] [--yes] [--json]
+oxyc rollback <app> --app-env staging|production [--to <build>] [--remove-schedule <fn>]… [--dry-run] [--yes] [--json]
 oxyc init-ci [--app <org>/<app>] [--environment <name>] [--promote] [--force] [--no-register] [--setup-action]
 oxyc proxy [--port <n>] [--allow-writes] [--allow-events] [--yes]
 ```
@@ -501,11 +585,32 @@ oxyc proxy [--port <n>] [--allow-writes] [--allow-events] [--yes]
 `pnpm install`, `pnpm build`, output `out/`), bundles each declared Oxy Function
 with `pnpm exec esbuild` into `functions/<name>.js`, resolves the project from
 the target's public `build-config`, and uploads the bundle — to the **draft**
-channel unless `--promote`. `--env` defaults to **production**; name it.
-
+channel (staging). `--env` defaults to **production**; name it. Ship it with
+`oxyc promote`, below. `--promote` still publishes and promotes in one request,
+through the same server-side path, and the server answers it with a
+deprecation warning: it shows nobody the plan.
+
+- **The manifest** is read strictly: `oxy-app.json` is validated against the
+  JSON Schema `@oxy-hq/sdk` generates from its `OxyAppManifest` type (the same
+  check `oxyc validate` and `@oxy-hq/vite-plugin` make, in the same words). An
+  error — a wrong type, a malformed `slug` or function name, a missing
+  required field, a notification catalogue the server refuses — stops the
+  publish before the build with exit `2`, listing every problem; a field the
+  schema does not know is a warning, since the platform ignores what it does
+  not read.
 - **Identity**: `--org` / `--app`, then `OXY_ORG` / `OXY_APP`, then the manifest's
   `orgSlug` / `slug`, then an `apps/<org>/<app>/` working directory. `--org`
   takes a slug or a UUID. `--project` pins the workspace (and implies its org).
+- **First publish**: an app the target does not know yet makes the
+  build-config lookup 404. With a stored token, `publish` lists the org's
+  workspaces: exactly one, and it publishes there, saying so on stderr;
+  several, and it exits `5` listing them with their uuids beside the
+  `--project <uuid>` to pass. Under trusted publishing (no token) it exits `5`
+  with the two-step hint, as before.
+- **Kit versions**: an app whose `@oxy-hq/sdk` or `@oxy-hq/vite-plugin` is more
+  than one minor behind the versions this `oxyc` was built beside gets one
+  warning per package before the build, naming the `pnpm add`. Read from the
+  app's `package.json` (the installed copy when there is one); no network.
 - **`--dir`** publishes a pre-built directory instead of building; functions are
   still bundled into it. **`--build-only`** stops after building and bundling —
   no credential, no network unless the org must come from `--project`.
@@ -548,7 +653,15 @@ lets it publish.
 *The workflow* is `.github/workflows/oxy-publish.yml` at the repo root: a
 `build` job (no id-token) that runs `publish --build-only`, and a `publish` job
 bound to a GitHub `environment:` (`--environment`, default `oxy-publish`) whose
-only work is `publish --prebuilt`. That job uses no third-party action: each
+only work is `publish --prebuilt`. `build` installs pnpm with
+`pnpm/action-setup@v6` — the pnpm the repo root's package.json pins
+(`packageManager` or `devEngines.packageManager`), with no `version:` of its
+own, since the action refuses a second, different one; pnpm 11 when nothing
+pins it — and both jobs run the Node in `.nvmrc`, else 26 (pnpm 11 needs
+Node 22.13 or later). It warns when nothing pins pnpm, and when
+`pnpm-workspace.yaml` approves build scripts only with `onlyBuiltDependencies`,
+which pnpm 11 ignores (the build's install would fail with
+`ERR_PNPM_IGNORED_BUILDS`; move the entries to `allowBuilds`). The publish job uses no third-party action: each
 step runs `npx @oxy-hq/cli@<this version>` and `oxyc` exchanges the job's OIDC
 token for itself, acting as the service account `--service-account <org>/<name>`
 names — by default `<app's org>/deployer`. **Here, and only here, the account is
@@ -589,13 +702,42 @@ policies. Registration never fails the command.
 **`--app-env <dev-handle>`** moves one sandbox's build pointer instead of the
 draft/live channel — see [Sandboxes](#sandboxes). It needs a staff credential
 (never a publish token or OIDC) and is refused together with `--promote`: a
-sandbox build is never promoted, so the loop is publish to the sandbox,
-iterate, then publish the same tree to staging and promote that.
+sandbox build goes to production only through staging — `oxyc promote <app>
+--from dev-<handle>`, then `oxyc promote <app>`.
+
+**`promote`** moves a build up one environment: staging's to production (the
+default), or a sandbox's to staging (`--from dev-<handle>`). Nothing else —
+production is never promoted, and moving it backwards is `rollback`. It asks the
+server for the **plan** first and prints it: the build (commit, branch,
+publisher, how long the source has served it), what the target serves now,
+functions and production schedules that change, the migrations production
+applies **before** it moves, and `required` secrets production has no value for.
+Then it asks on a terminal (off one it needs `--yes`, else exit `8`) and acts,
+sending the plan's build and `expect_current` back — `409 target_moved` if the
+target moved in between. `--dry-run` stops at the plan. A plan with blockers is
+refused before any act (exit `6`): `staging_never_served` (production only
+serves a build staging has served), `validation_not_passed`,
+`required_secrets_unset`, and `schedule_removal_unconfirmed` — name each retired
+schedule with `--remove-schedule <function>`. `--build` names an older build the
+source served (publish id or UUID). Promoting the build already served is
+`409 already_serving`.
+
+**`rollback`** moves `--app-env` (staging or production; never a sandbox) back
+to the build it served before its current one — twice swaps back — or `--to`
+one it served earlier. Same plan, prompt and `--yes`. A rollback never reverses
+a migration: the target's pending files are applied like any production move,
+and the plan warns when the target predates files already applied. An unset
+`required` secret only warns here (it is the emergency path).
+
+Both need a staff credential: a publish token, a service account's and a sandbox
+agent token are refused before any request (exit `2`). `--json` prints the
+server's plan verbatim.
 
 ## Apps
 
-Read-only: every request these make is a GET, against `/api/customer-apps/**`
-(the app-admin role). `<app>` is `<org-slug>/<app-slug>` or an app UUID.
+Read-only except `domains add | verify | remove`: every other request these make
+is a GET, against `/api/customer-apps/**` (the app-admin role). `<app>` is
+`<org-slug>/<app-slug>` or an app UUID.
 
 ```bash
 oxyc apps list [--org <slug>] [--published | --draft] [--builds] [--json]
@@ -604,6 +746,10 @@ oxyc apps builds <app> [--json]
 oxyc apps health [<app>] [--needs-attention] [--json]
 oxyc apps usage <app> [--json]
 oxyc apps drift [<app>] [--org <slug>] [--dir <path>] [--refresh] [--json]
+oxyc apps domains [list] <app> [--json]
+oxyc apps domains add <app> <domain> [--json]
+oxyc apps domains verify <app> <domain> [--json]
+oxyc apps domains remove <app> <domain> [--json]
 ```
 
 - **`list`** — every app you can see, across organizations, walking the paged
@@ -611,12 +757,17 @@ oxyc apps drift [<app>] [--org <slug>] [--dir <path>] [--refresh] [--json]
   `draft` when it has none. `SOURCE` is the repository the app is *registered*
   against. `--builds` adds the live build's id, the repository and commit it was
   built from, who published it and when — one extra request per app, six at a
-  time.
+  time. `--json` rows also carry the server's `verdict` and, for a published
+  app that was measured, `availability`: request success over six windows and
+  the burn verdict. An absent `availability` means "not read", never healthy.
 - **`show`** — one app on one screen: the registry row, the live build, the
   draft build when it is newer than the live one, deployment integrity,
   availability, and the 7-day usage summary. `last promote` is when the promote
   or rollback action was last used; `oxyc publish --promote` does not update it,
-  so it can be older than the live build.
+  so it can be older than the live build. Availability is the registry row's
+  reading, not a request of its own: with none, `show` prints `no reading`, and
+  it is never in `failed`. `--json` has the registry row under `app` and its
+  `availability` (or `null`) under `availability`.
 - **`builds`** — the build history, newest first. `CHANNEL` marks the build each
   channel points at: `live`, `draft`, or both for one build.
 - **`health`** — with no argument, the fleet table (published apps only):
@@ -626,6 +777,7 @@ oxyc apps drift [<app>] [--org <slug>] [--dir <path>] [--refresh] [--json]
   of the last 24 hours.
 - **`usage`** — the 7-day summary, the visitors, and the tracked events by name.
 - **`drift`** — see below.
+- **`domains`** — see [Custom domains](#custom-domains).
 
 Times are UTC. `--json` prints one document on stdout; a table goes to stdout and
 the count line to stderr.
@@ -642,6 +794,39 @@ a drifted app is an answer and exits `0` — read it from the output.
 The health route answers **503 with its report** when a check fails; `oxyc`
 prints that as a failing report, not as an outage.
 
+### Custom domains
+
+Serve an app on a domain the customer owns (`app.acme.com`) instead of its Oxy
+subdomain. `<domain>` is a bare host name; `verify` and `remove` find the row by
+that name (case-insensitive), so you never handle the domain's id.
+
+```bash
+oxyc apps domains acme/store                         # list (the default verb)
+oxyc apps domains add acme/store app.acme.com        # then create the two DNS records it prints
+oxyc apps domains verify acme/store app.acme.com
+oxyc apps domains remove acme/store app.acme.com
+```
+
+- **`list`** — each domain's `STATUS` (`pending` or `verified`), its URL and
+  when it was last checked. For every `pending` domain it prints the DNS records
+  to create — a `CNAME` from the domain to the deployment's target (a note to
+  ask Oxy ops when the deployment has none configured) and a `TXT` ownership
+  record — plus the checker's last error, if any.
+- **`add`** — registers the domain as `pending` and prints the same two records
+  and the `verify` command to run next. A malformed name is `400
+  invalid_domain` and a duplicate `409 domain_exists`; both exit `6` with the
+  server's message.
+- **`verify`** — checks DNS now. `verified` prints the URL and exits `0`. Still
+  `pending` is **not** success: it prints the records again and the checker's
+  reason, and exits `1` — DNS may not have propagated, so re-run it. `409
+  domain_taken` (another app already serves the domain) exits `6`.
+- **`remove`** — stops serving the app on that domain. A name the app does not
+  have exits `5` and deletes nothing.
+
+`--json` prints one document on stdout: `{app, app_id, domains, cname_target}`
+for `list`, and `{app, app_id, domain, cname_target}` for `add` and `verify`
+(`verify` still exits `1` while pending).
+
 ### `apps drift`
 
 Compares what is live against source on **this machine**. For each app it takes
@@ -705,8 +890,28 @@ object to stdout instead:
 { "app": "acme/dashboards", "appId": "…", "checks": [{ "name": "canary", "runId": "…", "status": "done", "passed": true, "durationMs": 4123 }] }
 ```
 
+**`--browser`** also loads the app's page in headless Chromium and proves it
+mounted: the platform runtime's `oxy-app-ready` beacon fires, nothing on the
+page throws, and `--expect-selector <css>` (optional) becomes visible. With
+`--app-env` the page must also report that environment and the build it serves
+(`oxyc env show`'s `build_uuid`) in `window.__OXY_APP__`. The credential and
+`X-Oxy-App-Env` ride only on requests under the app's own base path
+(`/customer-apps/<org>/<app>/`: the document, assets, beacon and `/fn` calls).
+The rest of the deployment's API is on the same origin, and the code under test
+is often a build someone else published, so its `/api/…` calls go without the
+credential, as an anonymous visitor's would. The result is one more entry in `checks[]`, with `"kind": "browser"` and
+the `/fn` calls the page made. Playwright is not a dependency: it is resolved
+from the working directory (`playwright`, `playwright-core` or
+`@playwright/test`), so run it where one is installed. The page loads as a
+user, so a publish, service-account, CI or sandbox agent token is refused
+before any request.
+
+```bash
+oxyc checks run acme/store --app-env dev-a1 --browser --expect-selector 'main'
+```
+
 **Auth** follows the same rule as `oxyc api`'s bearer surface, with one
-difference: `checks run` talks to `/api/admin/**`, which is not the
+difference: `checks run` talks to `/api/customer-apps/**`, which is not the
 `/external/api/*` surface, so a configured API key is sent explicitly as
 `X-API-Key` only when **no bearer resolves** — never both. A bearer from
 `oxyc login` (or `--token-env`) always wins when one is present.
@@ -715,11 +920,12 @@ difference: `checks run` talks to `/api/admin/**`, which is not the
 holding `id-token: write` signs itself in from its GitHub OIDC token — the same
 two exchanges `oxyc publish` tries, in the same order: a service account's
 trust policy first, the app's registered publisher second — and drives
-`/api/customer-apps/**` instead: the same three handlers, mounted where a
-machine credential may reach them. A service account's token (`oxy_sat_…`,
-`oxy_ci_…`) or a publish token set in `OXY_TOKEN` takes that surface too,
-without minting; a personal token, a legacy API key or a session takes the admin
-one. `OXY_API_KEY` is read **before** OIDC here: a job that set one has said
+`/api/customer-apps/**`, the same three routes a person's credential uses. A
+service account's token (`oxy_sat_…`, `oxy_ci_…`) or a publish token set in
+`OXY_TOKEN` is used without minting. What differs is the app lookup: a
+personal token, a legacy API key or a session can list apps to resolve
+`<org>/<app>`; a machine credential may not, so it names the app by UUID or
+through its own grants. `OXY_API_KEY` is read **before** OIDC here: a job that set one has said
 which credential it means.
 
 The app id comes from the credential where it can. The publisher exchange
@@ -776,20 +982,33 @@ oxyc env create <app> <name>                 # name is dev-<handle>, 1-12 chars
 oxyc env list <app>
 oxyc env show <app> <name>
 oxyc env delete <app> <name> [--yes] [--wait [seconds]]
+oxyc env schedules <app> <name> [--on|--off] # staging's or a sandbox's switch; off by default
 
 oxyc publish --app-env <name> [--env <e>]    # see "Custom apps" above
+oxyc fn dev <function> [--input <json|@file|->] [--env-file <path>] [--watch] [--read-through [--env <e>]]   # local, in-process
 oxyc fn call <app> <function> [--app-env <name>] [--data <json|@file|->]
+oxyc fn run <app> <function> [--app-env <name>] [--as-schedule] [--data …] [--timeout <s>]
 oxyc checks run <app> --app-env <name>       # see "Checks" above
 
 oxyc invocations list <app> [--app-env] [--build] [--function] [--limit]
 oxyc invocations held <app> <invocation-id>
 oxyc logs <app> [--app-env] [--invocation] [--request] [--hours] [--limit]
+oxyc logs <app> [--app-env <name>] --follow [--timeout <seconds>] [--json]
 
 oxyc env secret list <app> --app-env <name>      # keys and flags, never a value
 oxyc env secret set <app> <key> --app-env <name> (--value <text> | --value-env <VAR>)
 oxyc env secret delete <app> <key> --app-env <name>
 ```
 
+`logs --follow` is the live tail: each line as a function prints it,
+wherever the function runs, with no observability capture needed (the polled
+`logs` reads ClickHouse and answers `501` without it). `--json` prints one
+event per line — `open`, then `start` / `log` / `finish` per invocation,
+`dropped` when lines were lost, and `done` last, on which it exits `0`. A
+dropped connection is reopened with `Last-Event-ID`, and the server replays
+the outcomes of what finished meanwhile, never the lines. Production without
+`--app-env`; staging and sandboxes need staff with non-production reach.
+
 A **sandbox** is a named, short-lived `dev-<handle>` environment of one custom
 app: its own build pointer, storage silo, secrets, Airhouse sibling and — in
 an org with an OLTP staging branch — its own copy of the app's database, with
@@ -817,8 +1036,8 @@ to sit in an agent's context.
 validated client-side — exit `2` on a malformed name) is a *different axis*
 from `--env`, which is the deployment: both can appear on the same command
 (`oxyc fn call acme/store f --env dev --app-env dev-a1`). It is not a global
-flag — only `publish`, `fn call`, `checks run`, `invocations list` and `logs`
-take it. A publish-token credential is refused before any request for
+flag — only `publish`, `fn call`, `fn run`, `checks run`, `invocations list`
+and `logs` take it. A publish-token credential is refused before any request for
 `--app-env` other than `production` (exit `2`); `env`, `invocations` and
 `logs` refuse one outright, for any environment, because sandbox management
 is a staff console surface.
@@ -852,6 +1071,56 @@ distinct from a non-2xx on the POST itself (exit per the usual status mapping
 — e.g. `EnvironmentHasNoBuild` before the stream starts). The
 `x-oxy-invocation-id` response header becomes `invocationId` in the result.
 
+**`fn dev`** runs a handler locally, from the app directory, with no server and
+no credentials: it bundles `functions/<name>.ts` with the esbuild call `oxyc
+publish` uses, runs it in-process on `createTestContext` from
+`@oxy-hq/sdk/testing`, and prints the response and every host op the handler
+made (`host ops: email.send`, one line per call). The context is seeded from
+`oxy-app.json` — the function's capabilities and destinations — and `ctx.env`
+from `--env-file` (default `.env`; never your shell). `--input` is the request
+body, as `fn call --data`. `--watch` re-runs on a change under the app
+directory. It exits `0` for a 2xx `Response`, `1` when the handler throws or
+answers non-2xx, `2` for a function the manifest does not declare. **A local run
+is not the isolate:** no timeout, memory or log limits, Node globals the isolate
+lacks, and every warehouse, semantic, storage, fetch and email call is stubbed
+in memory — nothing reaches a deployment. Check it where it really runs with
+`fn call` against a sandbox.
+
+`fn dev --read-through [--env <name|url>]` sends exactly `ctx.query`,
+`ctx.warehouse.query` and `ctx.semantic.query` to that deployment, through
+`POST /api/projects/{project}/query` and `/semantic-query` (the routes a
+published app calls), authenticated as `oxyc api` is (`OXY_TOKEN` or your
+`oxyc login`). The server decides what you may read. The project is `--project`
+/ `OXY_PROJECT`, else looked up from `oxy-app.json` `slug` + `orgSlug`. Every
+other call — writes, transactions, storage, fetch, email — stays stubbed, the
+report marks each call `real` or `stubbed`, and a local run is still not the
+isolate.
+
+**`env schedules`** reads, or with `--on` / `--off` flips, the schedules
+switch of staging or a sandbox (`GET`/`PUT
+/api/customer-apps/{id}/environments/{name}/schedules`). Off by default: a
+schedule outside production reads production data on a timer and calls third
+parties with staging's credentials, so an environment fires its functions'
+`schedule`s only once staff turn it on. On, it has one schedule row per
+function its build schedules, kept in step by every publish to it; `--off`
+removes them. Production has no switch (exit `2`) — its schedules always run.
+Staff only: a sandbox agent token is refused before any request (exit `2`).
+A scheduled fire, and a delivery to the environment's own webhook route
+(`/api/webhooks/apps-env/{environment}/{org}/{app}/{function}`, verified with
+that environment's own secret), are not a sandbox's activity.
+
+**`fn run`** queues a function as a background run — the console's **Run
+now** — and polls it to a verdict (`--timeout`, default 300 s), unlike `fn
+call`, which is the function's own route. It runs as the system (the org
+owner, no caller), with the function's retry policy; outside production only a
+`"check": true` function runs. **`--as-schedule`** runs a function that
+declares a `schedule` once, as its cron would: no input (`--data` is exit
+`2`), the environment's build and policy, whether or not its switch is on —
+the way to test a scheduled function in a sandbox without turning schedules
+on. A function with no schedule is `409 not_scheduled` (exit `6`), production
+included. `--json` prints `{function, environment, runId, status, ok, trigger,
+answer, error?, invocationId}`; exit `1` when the run did not end `done`.
+
 **`invocations held`** is what the non-production write policy did *not* do —
 production's would-be effect, recorded rather than performed. It is `[]` for a
 production invocation, since nothing is held there.
@@ -1021,9 +1290,12 @@ them, and a tool that can only fail still costs its schema every turn. A dead
 token ends the server at startup with exit `4`.
 
 **`guide`** prints a page to paste into `AGENTS.md` / `CLAUDE.md`.
-**`skills install`** symlinks the six bundled Claude skills into
+**`skills install`** symlinks the bundled Oxy platform skills into
 `~/.claude/skills`; it refuses to run from an `npx` cache, whose symlinks dangle
-once npm reclaims it.
+once npm reclaims it. The same skills are published to
+[`oxy-hq/skills`](https://github.com/oxy-hq/skills) for every other agent —
+`npx skills add oxy-hq/skills`, or the Claude Code plugin `oxy@oxy-hq`. They are
+written in `skills/` here; see `internal-docs/platform-skills.md`.
 
 ## Exit codes
 
@@ -1039,7 +1311,10 @@ once npm reclaims it.
 9  a check ran and failed or timed out (`oxyc checks run`)
 ```
 
-`4` almost always means the wrong `--env`. `7` is worth retrying; `6` never is.
+`4` almost always means the wrong `--env`. A person logs in again. An agent on
+its own token (`tokens create --agent` or `--sandbox-agent`) does not: there,
+`4` means the token expired or was revoked, and the agent stops and reports.
+`7` is worth retrying; `6` never is.
 
 ## Environment variables
 
@@ -1067,6 +1342,12 @@ once npm reclaims it.
 | `OXYC_QUIET` | — | `1` is `--quiet` |
 | `OXYC_DRY_RUN` | — | `1` makes `launch` print the command instead of running it |
 | `NO_COLOR` / `FORCE_COLOR` | — | force plain / coloured output |
+| `HTTPS_PROXY` / `HTTP_PROXY` | — | requests go through it. On Node 22.21+ and 24.5+, `oxyc` turns on Node's proxy support itself (`NODE_USE_ENV_PROXY`), re-running once if it has to. Older Node cannot proxy `fetch`, and the error says so |
+
+**In a Claude Code cloud session,** the repo's SessionStart hook installs
+`oxyc` and keeps an agent token across shell calls. The environment must allow
+the Oxy hosts. Setup: the `oxy-custom-apps` skill, "Headless and cloud
+sessions".
 
 **An agent should set `OXY_AGENT`.** Every request `oxyc` makes to a deployment
 carries the user agent `oxyc/<version>`, with `agent/<label>` after it when an